Connect Your Machine

Run AI agents on your own hardware — a Windows laptop, a Mac, a Linux server, or any cloud VM. Connect it to Curate-Me in 2 minutes and get full governance, cost tracking, and observability without moving your data off-premise.

Why Connect Your Own Machine?

Benefit	Description
Data stays local	Files never leave your machine — agents process data where it lives
Use your GPU	Run local models (Ollama, vLLM) alongside cloud LLMs
Firewall-friendly	All connections are outbound — no ports to open
Full governance	Same cost limits, audit trail, and approval workflows as cloud runners
Free tier included	1 connected machine on Starter, 3 on Growth, unlimited on Enterprise

Architecture


Your Machine                          Curate-Me Cloud
┌─────────────────┐                  ┌──────────────────┐
│  Your Machine   │─── heartbeat ──→│  Gateway :8002    │
│                 │←── poll jobs ────│                   │
│  ┌───────────┐  │                  │  ┌─────────────┐ │
│  │ OpenClaw  │  │                  │  │ Job Queue   │ │
│  │ + MCP     │  │                  │  │ Audit Trail │ │
│  │ + Workspace│ │                  │  │ Cost Tracker│ │
│  └───────────┘  │                  │  └─────────────┘ │
│                 │                  │                   │
│  C:\workspace   │                  │  Dashboard :3001  │
│  (your files)   │                  │  (monitor agents) │
└─────────────────┘                  └──────────────────┘

Key design: The agent always initiates connections (outbound HTTP). The gateway never connects inbound to your machine. This means connected machines work behind corporate firewalls, NATs, and VPNs with zero network configuration.

Setup (Windows)

Step 1: Get a Registration Token

From the dashboard or API:


# Via API
curl -X POST https://api.curate-me.ai/gateway/admin/runners/byovm/register-token \
  -H "Authorization: Bearer $YOUR_JWT" \
  -H "X-Org-ID: $YOUR_ORG_ID"
 
# Response:
# {
#   "token": "cmreg_aB9cDeFgHiJk...",
#   "expires_at": "2026-03-01T11:00:00Z"
# }

Or click “Connect Machine” in the Dashboard Your Machines page (/runners/byovm).

Step 2: Run the Installer

Open PowerShell as Administrator:


# Download and run the installer
.\install-byovm.ps1 -GatewayUrl "https://api.curate-me.ai" -RegToken "cmreg_aB9cDeFg..."

The installer:

Checks prerequisites (admin privileges, PowerShell 5.1+)
Installs Node.js 22 LTS via Chocolatey (if not present)
Installs Git, ripgrep, jq (optional dev tools)
Installs OpenClaw v2026.3.13 globally
Installs @curate-me/cli and @curate-me/mcp-server
Creates workspace directories:
- C:\workspace — agent working directory
- C:\openclaw-config — OpenClaw configuration
- C:\ProgramData\cm-runner — runner service data
Registers the agent with the gateway
Starts the cm-runner service (auto-restarts on reboot)

Step 3: Verify Connection

Check the dashboard — your agent should appear within 30 seconds:


# Or verify via API
curl https://api.curate-me.ai/gateway/admin/runners/byovm/agents \
  -H "Authorization: Bearer $YOUR_JWT"
 
# Response shows your agent:
# {
#   "agents": [{
#     "agent_id": "byovm_c8a4acd75ea7",
#     "hostname": "YOUR-LAPTOP",
#     "os_type": "windows",
#     "state": "online",
#     "resource_usage": {"cpu_percent": 12, "memory_percent": 38}
#   }]
# }

Setup (macOS / Linux)


# 1. Install prerequisites
brew install node@22  # macOS
# or: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -  # Linux
 
# 2. Install OpenClaw + Curate-Me tools
npm install -g openclaw@latest @curate-me/cli @curate-me/mcp-server
 
# 3. Register the agent
curate machines connect \
  --gateway-url https://api.curate-me.ai \
  --reg-token cmreg_aB9cDeFg...
 
# 4. Start the agent
curate machines start

How It Works

Heartbeat Loop

Your agent sends a heartbeat every 30 seconds:


POST /gateway/admin/runners/byovm/agents/{agent_id}/heartbeat
Header: X-CM-Agent-Token: cmagent_xxx
Body: {
  "resource_usage": {
    "cpu_percent": 15.2,
    "memory_percent": 42.8,
    "disk_percent": 68.1
  }
}

The gateway responds with polling instructions:


{
  "next_poll_seconds": 30,
  "pending_jobs_count": 0
}

When jobs are queued, next_poll_seconds drops to 1 for immediate pickup.

Agent States


registering → online ↔ busy → offline → stale (5min) → dead (15min)

State	Meaning
online	Heartbeat active, ready for jobs
busy	Currently executing a job
offline	Agent manually paused
stale	No heartbeat for 5 minutes
dead	No heartbeat for 15+ minutes

Job Execution

When you dispatch work (from the dashboard, Slack, or API), it follows this flow:

Job enters the queue (status: queued)
Agent polls and picks it up (status: dispatched)
Agent executes the command locally
Agent reports results back (status: completed or failed)


# Dispatch a job
curl -X POST https://api.curate-me.ai/gateway/admin/runners/byovm/dispatch \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "agent_id": "byovm_c8a4acd75ea7",
    "command": ["echo", "hello from my machine"]
  }'

Your Files Stay Local

The agent’s workspace (C:\workspace on Windows, ~/workspace on macOS/Linux) is where your agents read and write files. Files never leave your machine unless you explicitly share them.

Uploading Files to the Agent

Push files from the dashboard or API into the agent’s workspace:


# Upload a file for the agent to process
curl -X POST https://api.curate-me.ai/gateway/admin/runners/{runner_id}/files/upload \
  -F "file=@data.csv" \
  -H "Authorization: Bearer $JWT"

The file is transmitted to the gateway, then delivered to the agent on its next poll cycle. The agent writes it to the workspace directory.

Shared Org Drive

For files that multiple agents need access to:


# Write to shared drive
curl -X PUT https://api.curate-me.ai/gateway/admin/runners/orgs/drive/files/content \
  -H "Authorization: Bearer $JWT" \
  -d '{"path": "/project/config.json", "content": "{...}"}'
 
# Read from shared drive
curl "https://api.curate-me.ai/gateway/admin/runners/orgs/drive/files/content?path=/project/config.json" \
  -H "Authorization: Bearer $JWT"

During Active Sessions

Push files directly into a running session:


curl -X POST https://api.curate-me.ai/gateway/admin/runners/{runner_id}/sessions/{session_id}/files/push \
  -F "file=@input.json" \
  -H "Authorization: Bearer $JWT" \
  --data-urlencode "path=/workspace/inputs"

MCP Integration

Every connected machine ships with the @curate-me/mcp-server pre-installed. This gives OpenClaw agents running on your machine access to 21+ governance tools:

Tool	What It Does
`curate_check_budget`	Check daily LLM spend vs. org limit
`curate_get_status`	Get runner status and resource usage
`curate_emit_event`	Log audit events to the control plane
`curate_discover_peers`	Find other agents in your org
`curate_request_approval`	Flag high-cost operations for human review
`curate_read_memory`	Read from shared knowledge base
`curate_search_memory`	Semantic search across agent memory
`curate_credentials_read`	Get credentials from the vault
`curate_spawn_subagent`	Fork a child agent
`curate_fleet_message`	Send message to fleet peers

See the BYO MCP Guide for full documentation on MCP tools.

Environment Variables

These are automatically set when the agent starts:


CM_API_KEY=cm_rt_...              # Agent's gateway auth token
CM_GATEWAY_URL=https://api.curate-me.ai
CM_RUNNER_ID=byovm_c8a4acd75ea7
CM_ORG_ID=org_xxx

The MCP server uses these to authenticate all governance calls back to the gateway.

Windows-Specific Notes

Docker Option

If you prefer containerized isolation on Windows:


docker run -d --name cm-runner --restart unless-stopped `
  -e CM_GATEWAY_URL=https://api.curate-me.ai `
  -e CM_REG_TOKEN=cmreg_your_token `
  -v C:\workspace:/workspace `
  -p 18789:18789 `
  ghcr.io/curate-me-ai/openclaw-windows:2026.3.13

This gives you:

Isolated OpenClaw runtime in a container
Mounted workspace for file access
Desktop streaming via RDP (port 3389)
All governance tools pre-installed

Service Management

The installer creates a Windows service via NSSM:


# Check status
nssm status cm-runner
 
# Restart
nssm restart cm-runner
 
# View logs
Get-Content C:\ProgramData\cm-runner\logs\agent.log -Tail 50

The service auto-starts on boot and restarts on crashes.

Firewall

Your machine only needs outbound HTTPS (port 443) to the gateway URL. No inbound ports required. If your network blocks outbound connections, whitelist your gateway domain.

Monitoring

Dashboard

The Your Machines page (/runners/byovm) shows:

Agent grid with online/offline status
Resource usage bars (CPU, Memory, Disk)
OS badges (Windows, macOS, Linux)
Job history and active sessions
“Connect Machine” button for adding new machines

API


# Get agent detail
curl https://api.curate-me.ai/gateway/admin/runners/byovm/agents/{agent_id}/detail \
  -H "Authorization: Bearer $JWT"
 
# Get all agents
curl https://api.curate-me.ai/gateway/admin/runners/byovm/agents \
  -H "Authorization: Bearer $JWT"
 
# Bridge status (WebSocket connections)
curl https://api.curate-me.ai/gateway/admin/runners/byovm/bridge/status \
  -H "Authorization: Bearer $JWT"

Security

Feature	Implementation
Auth tokens	SHA-256 hashed in MongoDB — plaintext never stored
Org isolation	Each agent scoped to its registering organization
RBAC	Dispatch requires `RUNNER_EXEC` permission
Audit trail	Every heartbeat, job, and event recorded immutably
Credential vault	Secrets stored encrypted, accessed via MCP tools
Token rotation	Registration tokens expire in 1 hour (configurable)

Plan Limits

Plan	Connected Machines
Free	0
Starter ($49/mo)	1
Growth ($199/mo)	5
Enterprise ($499/mo)	Unlimited

Next Steps

BYO MCP Guide — Connect custom MCP servers to your agents
Slack Integration — Control agents from Slack
Runners Quickstart — Cloud-hosted runners