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.

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.

GET /agents

Query parameters

scope

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

name

string

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

sandbox

string

default:"standard"

Sandbox type. standard (Docker) or nemoclaw (NVIDIA NemoClaw). The nemoclaw option requires nemoclaw to be included in ENABLED_SANDBOX_PROFILES on the server.

vcpu

number

default:"2"

Number of virtual CPUs. Ignored on PaaS deployments (locked to subscription). On self-hosted, clamped to operator limits.

ram_mb

number

default:"2048"

RAM allocation in MB. Ignored on PaaS. Minimum 512.

disk_gb

number

default:"20"

Disk allocation in GB. Ignored on PaaS. Minimum 1.

On PaaS deployments the vcpu, ram_mb, and disk_gb values are determined by your subscription plan and cannot be overridden.

Response

Returns the newly created agent record.

string

UUID of the new agent.

name

string

Agent display name.

status

string

queued — deployment is pending.

sandbox_type

string

standard or nemoclaw.

vcpu

number

Allocated vCPU count.

ram_mb

number

Allocated RAM in MB.

disk_gb

number

Allocated disk in GB.

node

string

Scheduler node assigned to this agent.

container_name

string

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

created_at

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","vcpu":2,"ram_mb":2048,"disk_gb":20}'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Agent",
  "status": "queued",
  "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"
}

Status	Condition
`400`	Name too long or NemoClaw not enabled
`402`	Billing limit reached

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

success

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

success

boolean

true when the redeploy job was queued.

status

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

success

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

cpu_percent

number

CPU utilisation as a percentage across all cores.

memory_usage_mb

number

Actual memory usage in MB (excludes page cache).

memory_limit_mb

number

Memory limit allocated to the container in MB.

memory_percent

number

Memory usage as a percentage of the limit.

network_rx_mb

number

Total received bytes across all network interfaces, in MB.

network_tx_mb

number

Total transmitted bytes across all network interfaces, in MB.

disk_read_mb

number

Total block device read bytes in MB.

disk_write_mb

number

Total block device write bytes in MB.

pids

number

Number of processes running inside the container.

uptime_seconds

number

Seconds since the container last started.

running

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

range

string

default:"15m"

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

from

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.

cpu_percent

number

CPU % at sample time.

memory_usage_mb

number

Memory usage in MB at sample time.

memory_limit_mb

number

Memory limit in MB.

memory_percent

number

Memory % at sample time.

network_rx_mb

number

Cumulative received MB at sample time.

network_tx_mb

number

Cumulative transmitted MB at sample time.

disk_read_mb

number

Cumulative disk read MB at sample time.

disk_write_mb

number

Cumulative disk write MB at sample time.

pids

number

Process count at sample time.

recorded_at

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"

[
  {
    "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

url

string

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

port

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

budgets

array

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

pausedReason

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

period

string

required

daily, weekly, or monthly.

limit_usd

number

required

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

soft_threshold_pct

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

​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

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