Running Agents

Production deployment and runtime management

Learn how to run ZeroClaw agents in production with proper supervision and reliability.

Runtime Modes

ZeroClaw supports multiple runtime modes depending on your use case:

Daemon Mode

Long-running supervised process with automatic recovery.

zeroclaw daemon

Features:

• Gateway server
• Channel listeners
• Cron scheduler
• Health monitoring
• Auto-restart on failure

Service Mode

System service with OS-level supervision.

zeroclaw service install
zeroclaw service start

Features:

• Auto-start on boot
• systemd/launchd integration
• Log rotation
• Resource limits

Interactive Chat

One-off agent conversations.

zeroclaw agent -m "Hello!"

Use cases:

• Testing
• Development
• Quick queries

Gateway Only

HTTP/WebSocket gateway without background services.

zeroclaw gateway

Use cases:

• Webhook endpoint
• API server
• Reverse proxy backend

Production Deployment

1. Install as system service

   # Install service
   zeroclaw service install
   
   # Verify installation
   zeroclaw service status
   
2. Configure for production

   Edit ~/.zeroclaw/config.toml:

   [agent]
   provider = "anthropic"
   model = "claude-3-5-sonnet-20241022"
   autonomy_level = "supervised"  # Require approval for tools
   
   [gateway]
   host = "0.0.0.0"
   port = 3000
   require_pairing = true
   rate_limit_per_minute = 60
   
   [security]
   shell_enabled = true
   blocked_commands = ["rm -rf /", "dd if="]
   workspace_path = "/var/zeroclaw/workspace"
   
3. Start the service

   zeroclaw service start
   
4. Verify health

   zeroclaw status
   zeroclaw doctor
   zeroclaw channel doctor
   

Health Checks

System Status

zeroclaw status

Shows:

• Active provider and model
• Configured channels
• Gateway status
• Memory backend

Diagnostics

zeroclaw doctor

Checks:

• Configuration validity
• Provider credentials
• File permissions
• Network connectivity
• Resource availability

Channel Health

zeroclaw channel doctor

Verifies:

• Channel credentials
• API connectivity
• Webhook configuration
• Allowlist validation

Monitoring

Log Files

Linux (systemd)

# Follow logs
journalctl --user -u zeroclaw.service -f

# Last 100 lines
journalctl --user -u zeroclaw.service -n 100

# Since boot
journalctl --user -u zeroclaw.service -b

macOS (launchd)

# Service logs
tail -f ~/.zeroclaw/logs/daemon.stdout.log
tail -f ~/.zeroclaw/logs/daemon.stderr.log

Docker

docker logs -f zeroclaw

State Files

• Daemon State: ~/.zeroclaw/daemon_state.json

  • Updated every 30 seconds
  • Contains runtime statistics
  • Used for health monitoring

• Memory: ~/.zeroclaw/memory/

  • Markdown or SQLite database
  • Conversation history
  • Agent knowledge

Metrics

Enable Prometheus metrics:

[observability]
prometheus_port = 9090

Metrics endpoint: http://localhost:9090/metrics

Key metrics:

• zeroclaw_requests_total - Total requests
• zeroclaw_tool_calls_total - Tool execution count
• zeroclaw_errors_total - Error count
• zeroclaw_token_usage_total - Token consumption
• zeroclaw_latency_seconds - Response latency

Supervision

Auto-restart

The daemon automatically restarts failed components:

• Gateway: Restart on crash
• Channels: Reconnect on disconnect
• Scheduler: Resume after failure

Resource Limits

Configure resource constraints:

[runtime]
max_memory_mb = 512
max_cpu_percent = 80
max_file_descriptors = 1024

Rate Limiting

Protect against abuse:

[security]
max_actions_per_hour = 100
rate_limit_per_minute = 60

Updates

Check for updates

zeroclaw update check

Update to latest

# Stop service
zeroclaw service stop

# Update binary
zeroclaw update

# Start service
zeroclaw service start

Rollback

If an update causes issues:

# Restore previous binary
cp ~/.zeroclaw/backups/zeroclaw-0.1.7 /usr/local/bin/zeroclaw

# Restart service
zeroclaw service restart

Multi-instance

Run multiple agents with different configurations:

# Instance 1: Production
ZEROCLAW_CONFIG_PATH=~/.zeroclaw/prod.toml zeroclaw daemon &

# Instance 2: Staging
ZEROCLAW_CONFIG_PATH=~/.zeroclaw/staging.toml zeroclaw gateway --port 3001 &

Related

• Monitoring Guide
• Troubleshooting
• Security Best Practices
• Daemon Command