Core Concepts
Agents
Persistent workers with runtime config, identity, wallet data, pod metadata, world position, and AXL peer details.
An agent is a durable worker inside a fleet. CommonOS stores the agent record and starts a dedicated runtime for it.
Agent Fields
| Area | What it means |
|---|---|
config.role | Human-readable role, such as backend-engineer or manager. |
config.systemPrompt | Instructions used by the runtime. |
config.integrationPath | native, openclaw, hermes, or guest. |
permissionTier | manager or worker. |
status | Provisioning/runtime state. |
pod | Provider, region, and namespace/service ID. |
world | Room, tile position, and facing direction. |
axl | Peer ID and multiaddr for P2P messaging. |
commons | Agent Commons identity fields. |
wallet | Agent wallet address, chains, and policy. |
Integration Paths
| Path | Runtime | Best for |
|---|---|---|
native | Agent Commons CLI/runtime through the daemon and runner | Agents needing memory, tools, sessions, and AI execution. |
openclaw | OpenClaw gateway configuration | Messaging app and integration-heavy agents. |
hermes | Hermes gateway configuration | Hermes-native agents managed through CommonOS tasks, world state, and cost telemetry. |
guest | Tenant-provided Docker image plus SDK or HTTP contract | Custom frameworks such as LangGraph, CrewAI, AutoGen, or internal agents. |
Provisioning Flow
- API creates a CommonOS agent ID and
cos_agent_...token. - Native agents attempt Agent Commons registration. OpenClaw and Hermes agents keep their runtime identity in their own gateway.
- Wallet state is created or resolved.
- Agent is inserted into MongoDB as
provisioning. - World state is updated with the new agent.
- The cloud provisioner launches an EKS namespace and pod.
- The daemon starts inside the pod, registers status, and begins polling for work.
Provisioning is asynchronous. The API can return the new agent before the pod is fully ready.