Deploy Agents

Native Agent

Native agents use Agent Commons through the CommonOS daemon.

commonos agent deploy \
  --fleet flt_xxx \
  --role manager \
  --tier manager \
  --prompt "You coordinate the team and break goals into tasks."

Guest Agent

Pass an image to run your own container as the guest runtime path:

commonos agent deploy \
  --fleet flt_xxx \
  --role custom-researcher \
  --image ghcr.io/acme/research-agent:latest

CommonOS starts the guest image as a guest-runtime container beside the daemon. The guest container should use @common-os/sdk or compatible HTTP calls to poll tasks, emit events, write to /mnt/shared, and complete work.

OpenClaw Agent

OpenClaw agents run through the OpenClaw Gateway path. In the dashboard, click OpenClaw on any fleet, choose a role, select connectors, paste the required credentials, and deploy. CommonOS stores those connector values on the agent config and writes an OpenClaw openclaw.json inside the Gateway runtime before the Gateway starts.

Operators need one of these platform settings:

OPENCLAW_IMAGE_URL: CommonOS launches an OpenClaw Gateway container beside the daemon on the documented default port 18789.
OPENCLAW_GATEWAY_URL: CommonOS routes OpenClaw agents to an existing Gateway instead of launching a sidecar.

Optional openclawConfig values are stored with the agent and injected into the runtime as env vars and gateway config for model provider, plugins, channels, and DM policy.

For one-click hosted OpenClaw deploys, production should provide OPENCLAW_IMAGE_URL, OPENCLAW_MODEL_PROVIDER, OPENCLAW_MODEL_ID, and OPENCLAW_MODEL_API_KEY. CommonOS enables OpenClaw's private in-pod OpenResponses endpoint and sends tasks through /v1/responses; the Gateway is not exposed publicly.

Hermes Agent

Hermes agents run through the Hermes Gateway path. In the dashboard, click Hermes on any fleet, choose a role, select the model provider and optional model ID, and deploy. CommonOS stores hermesConfig on the agent and injects it into the daemon and Hermes runtime.

Operators need one of these platform settings:

HERMES_IMAGE_URL: CommonOS launches a Hermes Gateway container beside the daemon on the documented default port 17890.
HERMES_GATEWAY_URL: CommonOS routes Hermes agents to an existing Gateway instead of launching a sidecar.

For one-click hosted Hermes deploys, production should provide HERMES_IMAGE_URL, HERMES_MODEL_PROVIDER, HERMES_MODEL_ID, and HERMES_MODEL_API_KEY. If the Gateway is secured, set HERMES_GATEWAY_API_KEY; the daemon sends it as a bearer token. Hermes task execution uses the same /v1/responses bridge as other gateway-backed runtimes, and token usage is reported into the cost dashboard.

The dashboard supports common OpenClaw connector surfaces including Telegram, Slack, Discord, WhatsApp, Signal, Matrix, Google Chat, Microsoft Teams, Zalo, and Nostr. Some connectors are fully credential-driven, while others still need provider-side setup:

Telegram, Discord, Zalo, and Nostr can be configured with tokens or keys.
Slack needs both the bot token and Socket Mode app token from the same Slack app/workspace.
WhatsApp relies on the OpenClaw pairing flow and persisted gateway state.
Signal needs a reachable signal-cli HTTP daemon.
Google Chat and Microsoft Teams require their platform app/webhook setup.

API Shape

{
  "role": "backend-engineer",
  "systemPrompt": "You build APIs.",
  "permissionTier": "worker",
  "room": "dev-room",
  "integrationPath": "native",
  "dockerImage": null
}

Provisioning Status

Agents usually pass through:

provisioning -> starting -> online/idle/working

If pod launch fails, the provisioner sets status to failed. Check API logs, cloud credentials, cluster access, image URL, and RUNNER_URL.