Connect Your Machine

Connect any machine — laptop, server, or cloud VM — to the Curate-Me platform with full governance, observability, and cost controls.

Time: ~2 minutes | Difficulty: Beginner

Prerequisites

• A Curate-Me account with a gateway API key (cm_sk_*)
• Docker installed (Install Docker )
• Internet connection (outbound HTTPS only — no ports to open)

Step 1: Generate a Registration Token

Via Dashboard

1. Navigate to Runners > Your Machines in the dashboard
2. Click Connect Machine
3. Choose your configuration:
   • Container Runtime: Docker (recommended) or Docker Compose
   • Operating System: Ubuntu, Debian, macOS, or Windows
   • Cloud Provider: Select your provider (optional, for reference only)
4. Click Generate Token

The dashboard displays a one-time registration token valid for 1 hour.

Via API

curl -X POST https://api.curate-me.ai/gateway/admin/byovm/register-token \
  -H "X-CM-API-Key: cm_sk_your_key_here" \
  -H "Content-Type: application/json"

Response:

{
  "token": "byovm_reg_a1b2c3d4e5f6...",
  "expires_at": "2026-02-28T15:00:00Z",
  "ttl_seconds": 3600
}

Via CLI

curate machines connect

Step 2: Install and Register the Agent

Copy the installation command from the dashboard and run it on your VM.

Linux (Ubuntu / Debian)

docker run -d \
  --name curateme-agent \
  --restart unless-stopped \
  -e CM_REGISTRATION_TOKEN="byovm_reg_your_token_here" \
  -e CM_GATEWAY_URL="https://api.curate-me.ai" \
  -e CM_AGENT_HOSTNAME="$(hostname)" \
  ghcr.io/curate-me-ai/openclaw-base:latest

macOS

docker run -d \
  --name curateme-agent \
  --restart unless-stopped \
  -e CM_REGISTRATION_TOKEN="byovm_reg_your_token_here" \
  -e CM_GATEWAY_URL="https://api.curate-me.ai" \
  -e CM_AGENT_HOSTNAME="$(hostname)" \
  ghcr.io/curate-me-ai/openclaw-base:latest

Windows (PowerShell)

docker run -d `
  --name curateme-agent `
  --restart unless-stopped `
  -e CM_REGISTRATION_TOKEN="byovm_reg_your_token_here" `
  -e CM_GATEWAY_URL="https://api.curate-me.ai" `
  -e CM_AGENT_HOSTNAME="$env:COMPUTERNAME" `
  ghcr.io/curate-me-ai/openclaw-windows:latest

What the Container Does

The Docker container includes:

1. OpenClaw runtime — The AI agent execution engine
2. Governance agent — Enforces your org’s policies (rate limits, cost caps, PII scanning)
3. Heartbeat service — Reports health and resource usage every 30 seconds
4. Job poller — Checks for dispatched jobs and executes them

No inbound ports are opened. All communication is outbound HTTPS to the gateway API.

Step 3: Verify the Connection

Via Dashboard

Return to Runners > Your Machines in the dashboard. Your machine should appear in the grid within 30 seconds with status ONLINE.

The dashboard shows:

• Hostname — Your machine’s hostname
• Status — REGISTERING → ONLINE (with animated pulse indicator)
• OS — Detected operating system
• Resources — CPU cores, RAM, disk space
• Last Heartbeat — Time since last check-in

Via API

curl https://api.curate-me.ai/gateway/admin/byovm/agents \
  -H "X-CM-API-Key: cm_sk_your_key_here"

Response:

{
  "agents": [
    {
      "agent_id": "byovm_a1b2c3d4e5f6",
      "hostname": "my-server",
      "state": "ONLINE",
      "os_type": "linux",
      "resource_usage": {
        "cpu_percent": 12.5,
        "memory_percent": 45.2,
        "disk_percent": 38.0
      },
      "last_heartbeat": "2026-02-28T14:30:15Z"
    }
  ]
}

Via CLI

curate machines list

Step 4: Configure Governance Policies

Once your agent is online, configure the governance policies that apply to all LLM requests routed through it.

Via Dashboard

In the Your Machines page, click on your machine to expand the detail panel. Navigate to the Policies tab to configure:

Via API

curl -X PUT https://api.curate-me.ai/gateway/admin/byovm/agents/byovm_a1b2c3d4e5f6/policies \
  -H "X-CM-API-Key: cm_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_limit_rpm": 200,
    "daily_budget_usd": 25.0,
    "pii_scan_enabled": true,
    "model_allowlist": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.0-flash"]
  }'

Step 5: Dispatch Your First Job

With governance configured, dispatch a job to your agent.

Via Dashboard

1. Go to Runners > Your Machines
2. Select your machine from the grid
3. In the detail panel, click Dispatch Job
4. Choose a command (e.g., session.create) or enter a custom command
5. Monitor execution in the Sessions tab

Via API

# Create a session on the agent
curl -X POST https://api.curate-me.ai/gateway/admin/byovm/dispatch \
  -H "X-CM-API-Key: cm_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "byovm_a1b2c3d4e5f6",
    "command": ["session.create"],
    "template_id": "default"
  }'

Response:

{
  "job_id": "job_x1y2z3",
  "agent_id": "byovm_a1b2c3d4e5f6",
  "status": "queued",
  "command": ["session.create"]
}

Container Images

Choose the image that matches your use case:

Environment Variables

Security Notes

• The registration token is one-time use and expires after 1 hour
• After registration, the agent receives a durable auth token — only the SHA-256 hash is stored server-side; the plaintext is shown once during registration
• All traffic is encrypted via HTTPS
• The agent authenticates via X-CM-Agent-Token header on every request
• No inbound ports are required on your VM

Next Steps

• Fleet Deployment — Scale to multiple agents
• Troubleshooting — Common issues
• Runners Security — Security model deep-dive
• API Reference — Complete endpoint documentation