Getting Started
Configuration
Environment variables used by the API, web app, runner, daemon, cloud provisioners, and integrations.
API
The API reads from apps/api/.env.local during local development.
| Variable | Required | Description |
|---|---|---|
PORT | No | API port. Defaults to 3001. |
API_URL | Yes | Public URL injected into agent pods. |
MONGODB_URI | Yes | MongoDB connection string. Most API routes fail without it. |
PRIVY_APP_ID | Optional | Privy app ID for JWT verification. |
PRIVY_APP_SECRET | Optional | Privy secret for server-side auth checks. |
CLOUD_PROVIDER | Provisioning | Production uses aws and defaults to AWS. GCP support is retained only for archived migration recovery. |
AWS_REGION | AWS | EKS and service region, defaulting to eu-west-1. |
EKS_CLUSTER | AWS | EKS cluster name. |
AGENT_IMAGE_URL | Provisioning | Container image used for agent pods. |
RUNNER_URL | Native runtime | Shared runner service URL used by native agents. |
AXL_MODE | Optional | P2P mode for agent pods. Defaults to explicit, which exposes the AXL tool but does not run background inbox routing. Use auto for automatic inbound AXL polling/replies, or off to skip AXL entirely. |
AGENTCOMMONS_API_KEY | Native runtime | Platform key for Agent Commons registration and bootstrap. |
AGC_API_URL | Optional | Agent Commons API base URL. |
AGC_INITIATOR | Optional | Initiator header/value for Agent Commons calls. |
AGENTCOMMONS_MODEL_PROVIDER | Native runtime | Default provider for newly registered native agents. Defaults to openai. |
AGENTCOMMONS_MODEL_ID | Native runtime | Default model for newly registered native agents. Defaults to gpt-5.4-mini. |
OPENCLAW_IMAGE_URL | OpenClaw runtime | Image used for the per-agent OpenClaw Gateway sidecar. Required for one-click OpenClaw deploys unless OPENCLAW_GATEWAY_URL is set. |
OPENCLAW_GATEWAY_URL | OpenClaw runtime | Existing OpenClaw Gateway URL. When set without an image, CommonOS targets this Gateway instead of launching a sidecar. |
OPENCLAW_MODEL_PROVIDER | OpenClaw runtime | Default provider injected for OpenClaw agents. |
OPENCLAW_MODEL_ID | OpenClaw runtime | Default OpenClaw model route for generated gateway config, for example openai/gpt-5.4-mini. |
OPENCLAW_MODEL_API_KEY | OpenClaw runtime | Default model provider key injected for OpenClaw agents. |
HERMES_IMAGE_URL | Hermes runtime | Image used for the per-agent Hermes Gateway sidecar. Required for one-click Hermes deploys unless HERMES_GATEWAY_URL is set. |
HERMES_GATEWAY_URL | Hermes runtime | Existing Hermes Gateway URL. When set without an image, CommonOS targets this Gateway instead of launching a sidecar. |
HERMES_MODEL_PROVIDER | Hermes runtime | Default provider injected for Hermes agents. |
HERMES_MODEL_ID | Hermes runtime | Default Hermes model route for generated gateway config, for example openai/gpt-5.4-mini. |
HERMES_MODEL_API_KEY | Hermes runtime | Default model provider key injected for Hermes agents. |
HERMES_GATEWAY_API_KEY | Hermes runtime | Optional bearer token used when the daemon calls a secured Hermes Gateway. |
Web
The web app reads from apps/web/.env.local.
| Variable | Required | Description |
|---|---|---|
NEXT_PUBLIC_API_URL | Optional | API URL. Omit for demo-only world usage. |
NEXT_PUBLIC_PRIVY_APP_ID | Optional | Enables Privy login. |
NEXT_PUBLIC_API_KEY | Optional | Static tenant API key for local/demo authentication. |
Runner
The runner exposes:
GET /healthPOST /run
Native agents call POST {RUNNER_URL}/run to execute Agent Commons CLI-backed work.
Daemon
The pod entrypoint writes daemon config and injects values such as:
| Variable | Purpose |
|---|---|
AGENT_ID | CommonOS agent ID. |
AGENT_TOKEN | Scoped cos_agent_... token. |
FLEET_ID | Parent fleet ID. |
TENANT_ID | Tenant owner ID. |
API_URL | Control plane URL. |
COMMONS_AGENT_ID | Agent Commons runtime identity. |
COMMONS_API_KEY | Agent Commons key, when available. |
COMMONOS_WORKSPACE | Workspace path, usually /mnt/shared. |
AXL_API_URL | Local AXL API URL used by daemon messaging. |
Secrets
Never expose cos_live_... tenant API keys or cos_agent_... tokens in client-side code unless deliberately running a local demo. Tenant API keys can create fleets, deploy agents, assign tasks, and terminate runtimes.