Skip to main content
An Agent is configuration, not compute. It defines what snapshot to boot, what entrypoint to run, which secrets to inject, and how elasticity works. The same agent can back both Instances and Sessions.

​
Create agent

POST /v1/agents

{
  "id": "issue-resolver",
  "display_name": "Issue Resolver",
  "config": {
    "snapshot": "agent-snapshot-v1",
    "entrypoint": "node /workspace/agent/index.js",
    "env": { "LOG_LEVEL": "info" },
    "elasticity": { "baseline_mb": 1024, "max_mb": 8192 },
    "idle_timeout_s": 600
  }
}
id must be DNS-safe (lowercase alphanumeric + hyphens). Returns 201 with the agent object. Entrypoint vs agent_config: if config.entrypoint is set, the platform runs it via sandbox.exec.start(). If config.agent_config is set instead, the platform uses sandbox.agent.start() with the provided system_prompt and allowed_tools. They are mutually exclusive.

​
CRUD

GET    /v1/agents                  List all agents
GET    /v1/agents/:agentId         Get agent
PATCH  /v1/agents/:agentId         Update (accepts display_name, config)
DELETE /v1/agents/:agentId         Delete (cascades to instances and sessions)

​
Agent object

{
  "id": "issue-resolver",
  "display_name": "Issue Resolver",
  "secret_store": "agent:issue-resolver",
  "config": { ... },
  "created_at": "2026-04-09T...",
  "updated_at": "2026-04-09T..."
}

​
Secrets

Convenience wrapper over OpenComputer’s secret store. Values are AES-256-GCM encrypted at rest, injected as sealed tokens at sandbox creation. Values are never returned via API. 
PUT    /v1/agents/:agentId/secrets/:key     Set a secret
GET    /v1/agents/:agentId/secrets          List keys (values never returned)
DELETE /v1/agents/:agentId/secrets/:key     Remove a secret
Set secret: 
PUT /v1/agents/issue-resolver/secrets/ANTHROPIC_API_KEY
{ "value": "sk-ant-...", "allowed_hosts": ["api.anthropic.com"] }
The first PUT auto-creates a backing OC secret store named agent:{agentId}. allowed_hosts is optional — restricts which outbound hosts can receive the decrypted value. List secrets returns keys and metadata only: 
{ "secrets": [{ "key": "ANTHROPIC_API_KEY", "allowed_hosts": ["api.anthropic.com"], "set_at": "..." }] }