Connect Your Machine

Managed runners and BYOVM are in private beta. This guide describes the flow available to allowlisted teams. If you do not have access yet, request the beta. The dashboard surfaces (Runners → Your Machines, template launches, fleet launches) are gated behind the FF_GATEWAY_MANAGED_RUNNER_BETA and RUNNER_BYOVM feature flags and are not visible without access.

This guide installs the public cm-runner agent on a machine you control so the Curate-Me dashboard can launch runners on it. The agent only makes outbound HTTPS connections — no inbound ports, no firewall changes.

Supported platforms. Linux (Ubuntu/Debian/RHEL/Fedora/Arch) is the primary target and what production runners are validated against. macOS 13+ on Apple Silicon and Windows 10+ via WSL2 are supported for development use in private beta — see the per-platform notes below for known limits.

Looking for the dashboard-generated install command? Open Runners → Your Machines → Connect Machine in the dashboard. The InstallGuide.tsx panel emits a pre-filled command with your org-scoped registration token already substituted. The instructions on this page are kept in sync with that panel — the env-var names, image ref, and volume layout below match exactly what the dashboard emits.

Prerequisites (all platforms)

A Curate-Me account with a Gateway API key (cm_sk_*)
Docker installed and the daemon running (Install Docker )
Outbound HTTPS access to api.curate-me.ai

Step 1 — Generate a registration token

The dashboard token is short-lived (1 hour). Generate one each time you connect a new machine.


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

Response:


{
  "token": "byovm_reg_a1b2c3d4...",
  "expires_at": "2026-05-19T15:00:00Z",
  "ttl_seconds": 3600
}

Copy the token value. The install commands below reference it as $REGISTRATION_TOKEN.

Step 2 — Install the agent

Linux server

Linux server (Hetzner / DigitalOcean / generic VPS)

The agent ships as a Docker container. The image is published on GitHub Container Registry — no private registry credentials required.

Run the container directly. This is what the dashboard emits in Runners → Your Machines → Connect Machine:


docker run -d \
  --name cm-runner \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v cm-runner-data:/etc/curateme \
  -v cm-runner-workspaces:/data/workspaces \
  -v cm-runner-orgdrive:/data/org-drives \
  -e CM_GATEWAY_URL=https://api.curate-me.ai \
  -e CM_HOSTNAME=$(hostname) \
  -e CM_REG_TOKEN=$REGISTRATION_TOKEN \
  ghcr.io/curate-me-ai/cm-runner:2026.5.21

These commands use the pinned production tag ghcr.io/curate-me-ai/cm-runner:2026.5.21 — the same ref the dashboard emits by default. Use the mutable :latest tag (or --image <ref> to mirror to a private registry) only if you specifically want the always-newest build.

A one-line installer (scripts/install-byovm-universal.sh, which also installs Docker if it is missing) exists in the repository but is not yet hosted anywhere you can curl it. Use the docker run above until it is published.

Private session image. The OpenClaw session image (openclaw-base) is a private GHCR package. When your org has a pull token configured, the dashboard’s Connect-Machine command automatically adds -e CM_GHCR_PULL_TOKEN=… (and -e CM_GHCR_PULL_USER) so the agent can docker login ghcr.io and pull it — no manual step. The --ghcr-token flag on the curl … | bash installer does the same. Public / already-cached images need no token.

Then verify the agent registered:


docker logs cm-runner --tail 50

You should see agent_registered followed by heartbeat_sent cycles every 30 seconds.

For long-running production use, install the agent as a systemd service instead of a one-shot container — see the Runner Operations runbook.

macOS

macOS (Docker Desktop) — beta

macOS support is in private beta. Tested on macOS 13+ (Ventura and later) with Apple Silicon (M1/M2/M3/M4). Intel Macs and older macOS versions are not validated. Templates that depend on desktop streaming or KVM passthrough are not available on macOS hosts.

The agent runs in the same Docker socket as Docker Desktop. Run it with docker run:


docker run -d \
  --name cm-runner \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v cm-runner-data:/etc/curateme \
  -v cm-runner-workspaces:/data/workspaces \
  -v cm-runner-orgdrive:/data/org-drives \
  -e CM_GATEWAY_URL=https://api.curate-me.ai \
  -e CM_HOSTNAME=$(scutil --get LocalHostName) \
  -e CM_REG_TOKEN=$REGISTRATION_TOKEN \
  ghcr.io/curate-me-ai/cm-runner:2026.5.21

Docker Desktop on macOS allocates a fixed memory budget. Open Docker Desktop → Settings → Resources and bump RAM to at least 8 GB before launching OpenClaw-based runners. With less, OpenClaw containers will OOM-kill on their first prompt.

Verify the agent is online:


docker logs cm-runner --tail 50

Look for agent_registered followed by periodic heartbeat_sent lines.

Windows / WSL

Windows / WSL — beta

Windows support is in private beta. The recommended path is WSL2 on Windows 10 21H2+ or Windows 11 with Docker Desktop’s WSL integration enabled. Native Windows containers (the cm-runner-windows image and PowerShell installer) are available for allowlisted teams only — contact support if you need them.

Run the agent inside WSL2 with Docker Desktop’s WSL integration enabled.

In a WSL2 shell:


docker run -d \
  --name cm-runner \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v cm-runner-data:/etc/curateme \
  -v cm-runner-workspaces:/data/workspaces \
  -v cm-runner-orgdrive:/data/org-drives \
  -e CM_GATEWAY_URL=https://api.curate-me.ai \
  -e CM_HOSTNAME=$(hostname) \
  -e CM_REG_TOKEN=$REGISTRATION_TOKEN \
  ghcr.io/curate-me-ai/cm-runner:2026.5.21

Open Docker Desktop → Settings → Resources → WSL Integration and enable integration for the distribution you’re using before running the command. Without it the agent can’t reach the Docker socket and will fail with docker_socket_denied — see Docker Socket Denied.

Cloud VM

Cloud VM (AWS / GCP / Azure / generic)

The Linux server flow works on any cloud VM. Two extras when provisioning fresh instances:

Open egress — the VM must reach api.curate-me.ai on :443. Default AWS / GCP / Azure egress rules already permit this; only a custom egress policy would block it.
Disk — runner containers cache 1–4 GB of image layers per template they pre-pull. Provision at least 20 GB of disk so the daemon doesn’t run out mid-pull. See Image Pull Failed for the symptoms.

Cloud-init drop-in (paste into your instance’s user-data field):


#cloud-config
package_update: true
packages:
  - docker.io
runcmd:
  - systemctl enable --now docker
  - |
    docker run -d \
      --name cm-runner \
      --restart unless-stopped \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v cm-runner-data:/etc/curateme \
      -v cm-runner-workspaces:/data/workspaces \
      -v cm-runner-orgdrive:/data/org-drives \
      -e CM_GATEWAY_URL=https://api.curate-me.ai \
      -e CM_HOSTNAME=$(hostname) \
      -e CM_REG_TOKEN=YOUR_TOKEN_HERE \
      ghcr.io/curate-me-ai/cm-runner:2026.5.21

Step 3 — Verify diagnostics

After installation the agent runs a self-check on the first heartbeat and reports the result to the control plane. Expected output in docker logs cm-runner --tail 100:


INFO  agent_starting version=2026.5.x
INFO  agent_registered agent_id=hostname org_id=org_xxx
INFO  diagnostics_pass docker=27.x.x disk_free_gb=58 mem_mb=15880
INFO  heartbeat_sent capabilities=[docker, openclaw, desktop]

If you see diagnostics_fail instead, jump to the matching troubleshooting page:

Symptom	Page
`invalid_registration_token`	Invalid Registration Token
`docker_socket_denied`	Docker Socket Denied
`image_pull_failed`	Image Pull Failed
`missing_credentials`	Missing Credentials
`openclaw_boot_failed` / `openclaw_ready_timeout`	OpenClaw Boot Failed
First launch is slow (>60s in `image_pull`)	Slow First Launch
Agent shows OFFLINE in dashboard	Machine Offline

Step 4 — Confirm online in the dashboard

Open Runners → Your Machines in the dashboard. Your hostname should appear with a teal Online badge within ~30 seconds of registration. The machine card shows:

Last heartbeat (should be < 60s old)
Available templates (pulled images)
CPU / memory / disk
Active sessions

Next steps

Launch your first runner — open Templates in the dashboard, pick a certified template, and click Launch on this machine.
Pre-pull images — for templates you use often, opt your machine into pre-pulling so first-session latency stays under the 60s startup SLO .
Production hardening — see Runner Operations for systemd unit files, agent upgrades, and capacity tuning.

Cleanup

To disconnect a machine:


docker rm -f cm-runner
docker volume rm cm-runner-data

Then in the dashboard, click Deregister on the machine card to remove its record from the control plane.