Agents API: deploy and manage agent runtimes

Deploy, start, stop, restart, and monitor Nora agent containers. Covers all lifecycle endpoints including live stats and gateway URL resolution.

The Agents API is the core of Nora. You use it to deploy new agent containers, control their lifecycle (start, stop, restart, redeploy, delete), poll live resource stats, and retrieve the gateway UI URL for direct browser access. Read endpoints include agents you own directly and agents shared with you through workspaces. Destructive deletion remains limited to the direct agent owner.

A workspace API key is confined to agents assigned to its exact workspace. The same issuing user may belong to other workspaces, but the key cannot list, read, mutate, proxy, export, or execute against those agents. Existing Remote Docker agent operations are session-only because they can reach host credentials and privileged cleanup paths.

Agent export and live-filesystem routes are session-only for every backend. Their allowed runtime roots can contain provider credentials, gateway secrets, paired-device state, and conversation sessions, so workspace API keys cannot call /agents/:id/export or /agents/:id/files/* even when the agent is assigned to the key’s workspace.

An agent moves through the following statuses: queued → deploying → running. From running it can transition to warning, error, or stopped. Use POST /agents/:id/redeploy to recover an agent that is in warning, error, or stopped state.

List agents

Returns all agents accessible to the authenticated user, ordered by creation time (newest first). Use scope=owned when a UI or integration needs only directly owned agents, such as assignment candidates or quota counters. For workspace API keys, both accessible and owned are evaluated inside the key’s exact bound workspace, and the response does not include assignments from another workspace.

GET /agents

Query parameters

string

Optional. accessible (default) includes directly owned and workspace-shared agents. owned returns only directly owned agents.

curl http://localhost:8080/api/agents \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Research Agent",
    "status": "running",
    "sandbox_type": "standard",
    "vcpu": 2,
    "ram_mb": 2048,
    "disk_gb": 20,
    "node": "worker-01",
    "container_id": "abc123def456",
    "created_at": "2025-03-10T09:00:00.000Z",
    "isDirectOwner": true,
    "effectiveRole": "owner",
    "workspaces": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Production",
        "role": "owner"
      }
    ]
  }
]

Deploy an agent

Create and queue a new agent for deployment. The agent record is created immediately with status queued; the actual container is started asynchronously by the deployment worker.

POST /agents/deploy

Request body

string

Human-readable agent name. Maximum 100 characters. Control characters are stripped. Defaults to OpenClaw-Agent-<random>.

string

default:"server default"

Runtime contract to deploy: openclaw or hermes. If omitted, Nora uses the control plane’s configured default runtime family.

string

default:"server default"

Placement family: GA docker or k8s, or experimental remote-docker or proxmox. Registered targets still require their concrete execution_target_id; Nora does not choose a cluster or remote host automatically.

string

default:"derived from deploy_target"

Concrete placement id. Use docker for local Docker, k8s:<cluster-id> for an Admin-registered Kubernetes cluster, remote:<host-id> for a registered Remote Docker host, or proxmox for the configured Proxmox target.

string

default:"standard"

standard or experimental nemoclaw. Hermes supports only standard. nemoclaw requires the profile to be enabled, and NemoClaw on Proxmox remains blocked. The legacy sandbox field is still accepted as an alias, but new clients should send sandbox_profile.

number

default:"operator deployment default (fallback 1)"

Number of virtual CPUs. On self-hosted deployments, an explicit value is clamped to operator limits. PaaS ignores the request value and uses the platform-wide deployment default.

number

default:"operator deployment default (fallback 1024)"

RAM allocation in MB. PaaS ignores the request value and uses the platform-wide deployment default. Minimum 512 when a self-hosted caller supplies a value.

number

default:"operator deployment default (fallback 10)"

Requested disk size in GB. PaaS ignores the request value and uses the platform-wide deployment default. Minimum 1 when a self-hosted caller supplies a value. Kubernetes and Proxmox use this value for provisioned storage; Docker and Remote Docker store it as deployment metadata but do not enforce it as a container storage quota.

string

Optional migration draft UUID. Migration drafts can contain complete managed state, so this field is session-only and returns 403 session_required when supplied with a workspace API key.

On PaaS deployments the operator-managed platform defaults determine vcpu, ram_mb, and disk_gb; plan tiers currently control deployment count, not per-agent resource size.

Response

Returns the newly created agent record. When a workspace API key creates a non-Remote agent, Nora creates the agent and its assignment to the key’s workspace in one database statement before publishing any deployment job. Adoption and duplication follow the same workspace-binding rule.

string

UUID of the new agent.

string

Agent display name.

string

queued — deployment is pending.

string

standard or nemoclaw.

string

Resolved runtime family, openclaw or hermes.

string

Resolved placement family, such as docker, k8s, or remote-docker.

string

Exact selected target, such as docker, k8s:aks-eastus2, or remote:build-host.

string

Resolved sandbox profile, standard or nemoclaw.

number

Allocated vCPU count.

number

Allocated RAM in MB.

number

Resolved disk request in GB. For Docker and Remote Docker this is metadata, not an enforced storage quota.

string

Scheduler node assigned to this agent.

string

Generated runtime resource name, such as a Docker container name or Kubernetes Deployment name.

string

ISO 8601 creation timestamp.

curl -X POST http://localhost:8080/api/agents/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"My Agent",
    "runtime_family":"openclaw",
    "deploy_target":"docker",
    "execution_target_id":"docker",
    "sandbox_profile":"standard",
    "vcpu":2,
    "ram_mb":2048,
    "disk_gb":20
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Agent",
  "status": "queued",
  "runtime_family": "openclaw",
  "deploy_target": "docker",
  "execution_target_id": "docker",
  "sandbox_profile": "standard",
  "sandbox_type": "standard",
  "vcpu": 2,
  "ram_mb": 2048,
  "disk_gb": 20,
  "node": "worker-01",
  "container_name": "nora-oclaw-my-agent-1h8z2k",
  "created_at": "2025-03-10T09:00:00.000Z"
}

Remote Docker and Hermes

Remote-host administration is intentionally session-only. Register and manually test a personal host in App -> Remote Hosts, or have a platform admin create a platform host in Admin -> Remote Hosts, before using its remote:<id> target. Workspace API keys cannot call personal /remote-hosts or platform /admin/remote-hosts management endpoints, and every response masks stored SSH private keys, passwords, and passphrases. The dashboard currently lists registered Remote Docker hosts for OpenClaw only. Hermes Remote Docker is an experimental advanced API path. After registration and testing, deploy it with a session JWT:

curl -X POST http://localhost:8080/api/agents/deploy \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Hermes Remote",
    "runtime_family":"hermes",
    "deploy_target":"remote-docker",
    "execution_target_id":"remote:build-host",
    "sandbox_profile":"standard",
    "vcpu":2,
    "ram_mb":4096,
    "disk_gb":20
  }'

For a personal host, the session user must own it or have an editor, admin, or owner role in a workspace where it is shared. For a platform host, a platform admin, the all-accounts setting, a direct-user grant, a matching user-group grant, or an editor+ workspace grant permits deployment. A workspace viewer can see a granted host but cannot deploy to it. The created agent belongs to the deploying user and is not automatically assigned to any workspace that supplied host access. Remote Docker placement and every existing-agent Remote Docker operation are session-only. A workspace API key receives 403 session_required before host lookup, persistence, queue publication, gateway/file access, or lifecycle cleanup when the source, destination, or persisted agent uses Remote Docker. API-key deploys to non-Remote targets continue to use the normal agents:write scope and are automatically assigned to the key’s workspace. After a session Remote Docker deployment, assign the agent explicitly if workspace access is required. Follow Connect a Remote Docker host for setup, then use the backend reference for the full test, networking, capacity, sharing, and revocation contract.

Status	Condition
`400`	Invalid or unavailable runtime selection, unknown/inaccessible concrete target, or name too long
`402`	Billing limit reached
`403`	API key lacks `agents:write`, uses a migration draft, or targets a session-only Remote Docker path

Adopt an external runtime

Register an already-running OpenClaw or Hermes endpoint without provisioning new compute. Nora stores the gateway credential encrypted, monitors and proxies the runtime, and marks the agent as external. Lifecycle actions are unavailable because Nora does not own the process; deleting the agent only deregisters it.

POST /agents/adopt

Provide runtime_family, either url or host plus optional port, and a cryptographically generated gateway_token. The token must contain at least 32 characters, have no whitespace, and be generated from a cryptographically secure random source. Hosted PaaS accepts only public endpoints; self-hosted operators may adopt a private-network endpoint that passes the gateway proxy’s host and port safety checks. Nora rechecks this contract when an adopted runtime connects, so legacy rows with weak credential shapes fail closed until the external runtime token is rotated.

GATEWAY_TOKEN="$(openssl rand -hex 32)"
curl -X POST http://localhost:8080/api/agents/adopt \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Existing OpenClaw\",\"runtime_family\":\"openclaw\",\"url\":\"https://agent.example.com:18789\",\"gateway_token\":\"$GATEWAY_TOKEN\"}"

The provided token must already be configured on the external runtime; generating a replacement in the example is appropriate only when you can update that runtime to use the same value. Workspace API keys require agents:write, and successful adoptions are atomically assigned to the key’s bound workspace.

Status	Condition
`400`	Weak token, invalid runtime family, unsafe endpoint, or invalid port
`402`	Billing limit reached
`403`	Missing `agents:write` scope

Get agent

Fetch a single agent by ID. The status is reconciled against the live container state on every call — if the container has stopped unexpectedly the stored status is updated before the response is returned.

GET /agents/:id

Path parameters

string

required

Agent UUID.

curl http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Agent",
  "status": "running",
  "container_id": "abc123def456",
  "sandbox_type": "standard",
  "vcpu": 2,
  "ram_mb": 2048,
  "disk_gb": 20,
  "node": "worker-01",
  "gateway_host_port": 32101,
  "created_at": "2025-03-10T09:00:00.000Z"
}

Start agent

Start a stopped agent’s existing container.

POST /agents/:id/start

Path parameters

string

required

Agent UUID.

Returns the updated agent record with status: "running".

curl -X POST http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/start \
  -H "Authorization: Bearer $TOKEN"

Status	Condition
`400`	Agent has no container — redeploy first
`404`	Agent not found

Stop agent

Gracefully stop a running agent’s container. The status is set to stopped regardless of whether the container was already stopped.

POST /agents/:id/stop

Path parameters

string

required

Agent UUID.

Returns the updated agent record with status: "stopped".

curl -X POST http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stop \
  -H "Authorization: Bearer $TOKEN"

Restart agent

Restart a running agent’s container in place (does not redeploy).

POST /agents/:id/restart

Path parameters

string

required

Agent UUID.

Response

boolean

true when the container was restarted.

curl -X POST http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/restart \
  -H "Authorization: Bearer $TOKEN"

{ "success": true }

Status	Condition
`400`	Agent has no container — redeploy first

Redeploy agent

Re-queue an agent for a full redeploy. Only available when the agent is in warning, error, or stopped state. Clears the existing container reference and submits a new deployment job. For Kubernetes-backed agents, the job deletes the previous Deployment, Service, and bootstrap ConfigMap before creating the replacement.

POST /agents/:id/redeploy

Path parameters

string

required

Agent UUID.

Response

boolean

true when the redeploy job was queued.

string

queued.

curl -X POST http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/redeploy \
  -H "Authorization: Bearer $TOKEN"

{ "success": true, "status": "queued" }

Status	Condition
`400`	Agent is not in `warning`, `error`, or `stopped` state

Delete agent

Permanently delete an agent and destroy its container.

DELETE /agents/:id

Path parameters

string

required

Agent UUID.

Response

boolean

true when the agent was deleted.

curl -X DELETE http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN"

{ "success": true }

Deletion is irreversible. All agent data, channel configuration, and integration connections are permanently removed.

Get live stats

Return a single real-time resource snapshot from the running container. Polls the Docker daemon directly.

GET /agents/:id/stats

Path parameters

string

required

Agent UUID.

Response

number

CPU utilisation as a percentage across all cores.

number

Actual memory usage in MB (excludes page cache).

number

Memory limit allocated to the container in MB.

number

Memory usage as a percentage of the limit.

number

Total received bytes across all network interfaces, in MB.

number

Total transmitted bytes across all network interfaces, in MB.

number

Total block device read bytes in MB.

number

Total block device write bytes in MB.

number

Number of processes running inside the container.

number

Seconds since the container last started.

boolean

Whether the container is currently running.

curl http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stats \
  -H "Authorization: Bearer $TOKEN"

{
  "cpu_percent": 4.32,
  "memory_usage_mb": 312,
  "memory_limit_mb": 2048,
  "memory_percent": 15.23,
  "network_rx_mb": 1.04,
  "network_tx_mb": 0.52,
  "disk_read_mb": 0.1,
  "disk_write_mb": 0.04,
  "pids": 21,
  "uptime_seconds": 3600,
  "running": true
}

Status	Condition
`409`	Agent has no container
`502`	Could not reach the Docker daemon

Get stats history

Return time-series container stats stored by the background collector (sampled every 10 seconds, retained for 24 hours).

GET /agents/:id/stats/history

Path parameters

string

required

Agent UUID.

Query parameters

string

default:"15m"

Preset time window. One of 5m, 15m, 30m, 1h, 6h, 24h. Ignored when from and to are provided.

string

ISO 8601 start timestamp for a custom range. Must be used together with to.

string

ISO 8601 end timestamp for a custom range. Must be used together with from.

Returns an array of up to 2 000 stat records, ordered oldest-first.

number

CPU % at sample time.

number

Memory usage in MB at sample time.

number

Memory limit in MB.

number

Memory % at sample time.

number

Cumulative received MB at sample time.

number

Cumulative transmitted MB at sample time.

number

Cumulative disk read MB at sample time.

number

Cumulative disk write MB at sample time.

number

Process count at sample time.

string

ISO 8601 timestamp when the sample was recorded.

curl "http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stats/history?range=1h" \
  -H "Authorization: Bearer $TOKEN"

curl "http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stats/history?from=2025-03-10T08:00:00Z&to=2025-03-10T09:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "cpu_percent": 3.14,
    "memory_usage_mb": 298,
    "memory_limit_mb": 2048,
    "memory_percent": 14.55,
    "network_rx_mb": 0.98,
    "network_tx_mb": 0.47,
    "disk_read_mb": 0.08,
    "disk_write_mb": 0.02,
    "pids": 19,
    "recorded_at": "2025-03-10T08:05:00.000Z"
  }
]

Get gateway URL

Resolve the HTTP URL of the agent’s embedded gateway control UI. The agent must be in running state.

GET /agents/:id/gateway-url

Path parameters

string

required

Agent UUID.

Response

string

Full HTTP URL to the gateway UI, e.g. http://localhost:32101.

number

Resolved host port number.

curl http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/gateway-url \
  -H "Authorization: Bearer $TOKEN"

{
  "url": "http://localhost:32101",
  "port": 32101
}

Status	Condition
`409`	Agent is not running, or has no container
`502`	Could not inspect the container to resolve the port

Get agent budget

List an agent’s LLM spend budgets with current spend attached. When spend crosses 100% of any cap, Nora pauses the runtime automatically (paused_reason becomes budget_exceeded); a warning event fires at the soft threshold.

GET /agents/:id/budget

Response

array

One entry per period (daily, weekly, monthly) with limitUsd, softThresholdPct, currentUsd, pct, and bucket (none | soft | hard).

string | null

budget_exceeded while the agent is paused by a cap.

Set agent budget

Create or update the budget for one period. Requires the agents:write scope.

PUT /agents/:id/budget

Request body

string

required

daily, weekly, or monthly.

number

required

Hard cap in USD. Crossing 100% pauses the runtime.

number

Warning threshold percent (default 80). Emits agent.budget_soft_exceeded.

Delete agent budget

DELETE /agents/:id/budget/:budgetId

Removes the cap. A paused agent stays stopped until started; manually starting an agent clears paused_reason, and the budget sweep re-pauses it within a minute if a cap is still exceeded.

​Agents API: deploy and manage agent runtimes

​List agents

​Query parameters

​Deploy an agent

​Request body

​Response

​Remote Docker and Hermes

​Adopt an external runtime

​Get agent

​Path parameters

​Start agent

​Path parameters

​Stop agent

​Path parameters

​Restart agent

​Path parameters

​Response

​Redeploy agent

​Path parameters

​Response

​Delete agent

​Path parameters

​Response

​Get live stats

​Path parameters

​Response

​Get stats history

​Path parameters

​Query parameters

​Get gateway URL

​Path parameters

​Response

​Get agent budget

​Response

​Set agent budget

​Request body

​Delete agent budget

Agents API: deploy and manage agent runtimes

List agents

Query parameters

Deploy an agent

Request body

Response

Remote Docker and Hermes

Adopt an external runtime

Get agent

Path parameters

Start agent

Path parameters

Stop agent

Path parameters

Restart agent

Path parameters

Response

Redeploy agent

Path parameters

Response

Delete agent

Path parameters

Response

Get live stats

Path parameters

Response

Get stats history

Path parameters

Query parameters

Get gateway URL

Path parameters

Response

Get agent budget

Response

Set agent budget

Request body

Delete agent budget