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 with credential fields redacted, then writes the complete launch-time configuration into the OpenClaw 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 API server port 8642.
• 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 Agent Commons runtime setup currently provides guided Telegram and WhatsApp configuration for OpenClaw and Hermes. OpenClaw supports additional connector configuration through its native profile; 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.