API Reference

Base URL: https://api.orbcloud.dev

All endpoints require Authorization: Bearer orb_YOUR_KEY unless noted.

Auth

Register


POST /api/v1/auth/register

No auth required.

Body:

json


{"email": "[email protected]"}

Response:

json


{"tenant_id": "uuid", "api_key": "YdZM..."}

Login (get JWT)


POST /api/v1/auth/login

No auth required.

Body:

json


{"api_key": "YdZM..."}

Response:

json


{"token": "eyJ...", "expires_in": 86400}

API Keys

Create Org Key


POST /v1/keys

Body:

json


{"name": "production"}

Response:

json


{"key_id": "uuid", "api_key": "orb_...", "name": "production"}

List Keys


GET /v1/keys

Revoke Key


DELETE /v1/keys/{key_id}

Computers

Create Computer


POST /v1/computers

Body:

json


{
  "name": "my-agent",
  "runtime_mb": 1024,
  "disk_mb": 4096
}

Field	Type	Default	Description
name	string	required	Display name
runtime_mb	int	512	RAM budget (MB)
disk_mb	int	1024	Storage budget (MB)

Response:

json


{
  "id": "abc12345-1234-5678-...",
  "org_id": "...",
  "name": "my-agent",
  "runtime_mb": 1024,
  "disk_mb": 4096,
  "status": "ready",
  "agent_count": 0,
  "port_mappings": []
}

List Computers


GET /v1/computers

Response:

json


{
  "computers": [...],
  "total": 3
}

Get Computer


GET /v1/computers/{id}

Delete Computer


DELETE /v1/computers/{id}

Config

Upload Config


POST /v1/computers/{id}/config
Content-Type: application/toml

Send the raw orb.toml file as the body.

Response:

json


{
  "computer_id": "...",
  "config_summary": {
    "agent": {"name": "...", "lang": "...", "entry": "..."},
    "backend": {"provider": "..."}
  },
  "source": "uploaded"
}

Get Config


GET /v1/computers/{id}/config

Build

Trigger Build


POST /v1/computers/{id}/build

Clones the git repo (if [source] is in config) and runs build steps (if [build] is in config). This is a synchronous call — it blocks until the build completes. Use a long timeout (e.g., curl -m 600). Builds typically take 1-3 minutes.

Response:

json


{
  "computer_id": "...",
  "cloned": true,
  "steps": [
    {"step": "npm install", "exit_code": 0, "stdout": "...", "stderr": "..."},
    {"step": "npm build", "exit_code": 0, "stdout": "...", "stderr": "..."}
  ],
  "success": true
}

Agents

Deploy Agent


POST /v1/computers/{id}/agents

Body:

json

{}

Spawns the agent defined in the uploaded config.

Response:

json


{
  "computer_id": "...",
  "deployed": 1,
  "agents": [{"pid": 12345, "port": 10001}]
}

List Agents


GET /v1/computers/{id}/agents

Exec

Run Command


POST /v1/computers/{id}/exec

Executes a shell command inside the computer's sandbox.

Body:

json


{"command": "ls -la /agent/data"}

Response:

json


{
  "stdout": "total 0\ndrwxr-xr-x 2 root root 40 ...\n",
  "stderr": "",
  "exit_code": 0
}

Notes:

Commands run as root inside the sandbox.
Working directory is /agent/data.
Commands have a timeout (default 30s).
For long-running processes, append & disown to background them.

Terminal

Web Terminal (Browser)

Open in browser:


https://api.orbcloud.dev/terminal/{computer-id}

Enter your API key. Full bash shell inside the computer's sandbox.

Terminal WebSocket (Programmatic)


GET /v1/computers/{id}/terminal?key=orb_YOUR_KEY

WebSocket upgrade. Send text messages as stdin, receive stdout as text messages.

Files

List Files


GET /v1/computers/{id}/files
GET /v1/computers/{id}/files/{path}

Browse the computer's filesystem.

Usage

Get Usage


GET /v1/usage?start=2026-03-01T00:00:00Z&end=2026-03-15T23:59:59Z

Returns runtime and disk GB-hours for the authenticated org.

Webhooks

Create Webhook


POST /v1/webhooks

Body:

json


{"url": "https://your-server.com/webhook", "events": ["agent.spawned", "computer.created"]}

List Webhooks


GET /v1/webhooks

Delete Webhook


DELETE /v1/webhooks/{id}

Event types: agent.spawned, agent.checkpointed, agent.restored, agent.finished, computer.created, computer.destroyed

Exposed Ports

If your app listens on a port inside the computer (e.g., a web server on port 8000), add it to your orb.toml:

toml


[ports]
expose = [8000]

Your app is then accessible at:


https://{short_id}.orbcloud.dev

Where short_id is the first 8 characters of the computer ID.

How it works: Your app binds to its port (e.g., 8000) inside the computer as normal. ORB handles the routing — you don't need to know or use any other port numbers. Just listen on your port and access via the subdomain URL.

The port_mappings field in the computer response shows the internal mapping:

json


"port_mappings": [
  {"host_port": 40001, "container_port": 8000}
]

You can ignore host_port — it's an internal detail. Your app listens on container_port (8000), customers access via {short_id}.orbcloud.dev.

Note: The port field in the deploy response (e.g., "port": 10001) is the internal LLM proxy port, NOT your app's port. This is used by ORB to route LLM API calls and is unrelated to exposed ports.