Deploy Your First AI Agent on osModa

This guide takes you from zero to a running AI agent on a dedicated osModa server. You will spawn a server, SSH in, install your dependencies via NixOS configuration, deploy your agent process, configure osmoda-watch for automatic crash recovery, and set up scheduled tasks with osmoda-routines.

Last updated: March 2026 · Estimated time: 25-30 minutes

Step 1: Spawn Your Server

Go to spawn.os.moda and pick a plan. For your first agent, the Solo plan ($14.99/month — 2 CPU, 4 GB RAM, 40 GB SSD) is sufficient for any agent that calls external LLM APIs. If you plan to run local models or multiple agents, consider Pro ($34.99 — 4 CPU, 8 GB RAM, 80 GB SSD).

You can also spawn programmatically via the API. The spawn endpoint accepts x402 USDC payment and returns your server's IP address, SSH credentials, and WebSocket endpoint within 5-10 minutes.

POST /api/v1/spawn/solo
Content-Type: application/json
X-402-Payment: <USDC payment token>

# Response:
{
  "ip": "203.0.113.42",
  "ssh_port": 22,
  "ws_endpoint": "wss://203.0.113.42:8443",
  "status": "provisioning",
  "estimated_ready": "5-10 minutes"
}

Once provisioning completes, you will receive an IP address and can add your SSH public key via the dashboard. The server arrives with NixOS installed and all 9 osModa Rust daemons already running: agentd, osmoda-watch, osmoda-mesh, osmoda-mcpd, osmoda-keyd, osmoda-routines, osmoda-voice, osmoda-teachd, and osmoda-egress.

Step 2: SSH In and Explore

Add your SSH public key through the osModa dashboard, then connect to your server. You have full root access — this is your dedicated machine.

# Connect to your server
ssh root@203.0.113.42

# Verify osModa daemons are running
systemctl status agentd
systemctl status osmoda-watch
systemctl status osmoda-mesh

# Check the NixOS generation
nixos-rebuild list-generations | head -5

# View available osModa tools
osmoda-tools --list

All 9 daemons should show active (running). The agentd daemon handles health monitoring, event logging, memory management, and backups. osmoda-watch is already watching for new processes to supervise.

Step 3: Install Dependencies via NixOS

On osModa, system dependencies are managed declaratively through the NixOS configuration. This means your entire environment is reproducible and can be rolled back instantly via SafeSwitch. Edit the configuration to add the packages your agent needs.

{ config, pkgs, ... }:

{
  # System packages available globally
  environment.systemPackages = with pkgs; [
    python312
    python312Packages.pip
    python312Packages.virtualenv
    git
    curl
    jq
    nodejs_22     # if your agent needs Node.js
    # Add any other packages your agent requires
  ];

  # Enable automatic garbage collection
  nix.gc = {
    automatic = true;
    dates = "weekly";
    options = "--delete-older-than 14d";
  };
}

# Build and switch to the new configuration
# SafeSwitch creates a new generation automatically
nixos-rebuild switch

# Verify the new generation
nixos-rebuild list-generations | head -3

# Confirm packages are available
python3 --version
node --version

Every nixos-rebuild switch creates a new generation. If anything breaks, you can instantly roll back to the previous generation with nixos-rebuild switch --rollback. This is the SafeSwitch atomic deployment model — your system is never in a half-configured state. See the NixOS Basics guide for more.

Step 4: Deploy Your Agent Process

Clone your agent code, set up the virtual environment, configure secrets, and start the process. We will use a Python agent as an example, but the same pattern works for any language.

# Clone your agent repository
git clone https://github.com/your-org/your-agent.git /opt/agent
cd /opt/agent

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create a secure environment file
cat << 'EOF' > /opt/agent/.env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql://...
EOF

# Restrict permissions
chmod 600 /opt/agent/.env

# /etc/systemd/system/my-agent.service
[Unit]
Description=My AI Agent
After=network-online.target agentd.service
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/agent
EnvironmentFile=/opt/agent/.env
ExecStart=/opt/agent/.venv/bin/python main.py
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# Enable and start the service
systemctl daemon-reload
systemctl enable my-agent.service
systemctl start my-agent.service

# Verify it is running
systemctl status my-agent.service

# Watch the logs in real time
journalctl -u my-agent.service -f

Your agent is now running as a managed systemd service. It will start automatically on reboot and restart on crash. But systemd alone is basic — next we will configure osmoda-watch for intelligent health monitoring.

Step 5: Configure osmoda-watch for Auto-Recovery

osmoda-watch is a Rust daemon that goes beyond systemd's basic restart. It performs health checks, detects silent hangs (processes that are alive but stuck), implements crash-loop backoff, and logs every event to the audit ledger. It also handles SafeSwitch atomic deployments and instant rollback when a deploy breaks something.

osmoda-watch automatically detects systemd services and begins supervising them. You can verify it has picked up your agent:

# Check osmoda-watch status and supervised processes
systemctl status osmoda-watch

# View watched processes
journalctl -u osmoda-watch --since "5 minutes ago" | grep my-agent

# The audit ledger records supervision events
# Every start, stop, crash, and recovery is hash-chained

When osmoda-watch detects a crash, the recovery flow is:

For deeper monitoring setup including alerting and dashboard integration, see the Agent Monitoring guide.

Step 6: Set Up Scheduled Tasks with osmoda-routines

Most agents need recurring tasks: scraping data on a schedule, sending daily reports, cleaning up temp files, rotating logs, or syncing state with external services. osmoda-routines is the daemon that handles both cron-style scheduling and event-driven task execution.

osmoda-routines goes beyond traditional cron. It supports event-driven triggers (run a task when a specific event occurs), dependency chains (run task B only after task A succeeds), and all task executions are recorded in the audit ledger.

# Check osmoda-routines status
systemctl status osmoda-routines

# View configured routines
journalctl -u osmoda-routines --since "1 hour ago"

# Example routine configurations:
# - Daily data scrape at 6 AM UTC
# - Hourly health report push to Telegram
# - Weekly cleanup of /tmp and old log files
# - Event-driven: re-index when new data arrives

All routines run under the same audit logging as everything else on the platform. Every scheduled execution — success or failure — is recorded with its SHA-256 hash-chain entry.

Step 7: Verify via the Dashboard

The osModa dashboard at spawn.os.moda provides a web interface for managing your agent. You can:

Close your SSH session. Your agent keeps running. Come back in 24 hours — the dashboard will show you exactly what happened while you were away. Every action, every crash, every recovery, recorded in the audit ledger.

What Is Running on Your Server Right Now

After following this guide, your osModa server has these components active:

Your agent process          → supervised by systemd + osmoda-watch
agentd                      → health monitoring, events, memory, backups
osmoda-watch                → crash detection, auto-restart, SafeSwitch
osmoda-routines             → scheduled and event-driven tasks
osmoda-mesh                 → encrypted P2P networking (ready for multi-server)
osmoda-mcpd                 → MCP server lifecycle management
osmoda-keyd                 → ETH + SOL wallet management
osmoda-voice                → speech processing
osmoda-teachd               → learning and optimization
osmoda-egress               → domain allowlisting proxy
SHA-256 audit ledger        → tamper-evident log of every action

You have not needed to configure most of these — they run out of the box. As you scale, you will interact with more daemons. osmoda-mesh becomes essential when you run agents across multiple servers. osmoda-egress matters when you need to lock down network access. osmoda-mcpd is how you connect MCP servers to your agent.

Frequently Asked Questions

Explore More Guides