Getting Started

1. Register

curl


curl -X POST https://api.orbcloud.dev/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]"}'

Response:

json


{
  "tenant_id": "your-org-id",
  "api_key": "YdZMrIaa..."
}

Save the api_key — you'll use it for all API calls.

2. Create an Org API Key

The registration key works, but org API keys are prefixed with orb_ and can be revoked independently.

curl


curl -X POST https://api.orbcloud.dev/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-key"}'

Response:

json


{
  "key_id": "...",
  "api_key": "orb_ONajt...",
  "name": "my-key"
}

Use orb_... keys for all subsequent calls.

3. Create a Computer

curl


curl -X POST https://api.orbcloud.dev/v1/computers \
  -H "Authorization: Bearer orb_YOUR_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent","runtime_mb":1024,"disk_mb":4096}'

Response:

json


{
  "id": "abc12345-...",
  "name": "my-agent",
  "status": "ready",
  "port_mappings": []
}

4. Upload Config

Create an orb.toml file describing your agent:

toml


[agent]
name = "my-agent"
lang = "python"
entry = "agent.py"

[backend]
provider = "anthropic"

Upload it:

curl


curl -X POST https://api.orbcloud.dev/v1/computers/COMPUTER_ID/config \
  -H "Authorization: Bearer orb_YOUR_KEY" \
  -H 'Content-Type: application/toml' \
  --data-binary @orb.toml

5. Run Commands

Execute commands inside the computer:

curl


curl -X POST https://api.orbcloud.dev/v1/computers/COMPUTER_ID/exec \
  -H "Authorization: Bearer orb_YOUR_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"command":"echo hello from ORB && uname -a"}'

Response:

json


{
  "stdout": "hello from ORB\nLinux ... x86_64\n",
  "stderr": "",
  "exit_code": 0
}

6. Build from Git (Optional)

If your agent lives in a git repo, add [source] and [build] to orb.toml:

toml


[source]
git = "https://github.com/you/your-agent"
branch = "main"

[build]
steps = [
  "pip install -r requirements.txt",
]
working_dir = "/agent/code"

Then trigger the build:

curl


curl -X POST https://api.orbcloud.dev/v1/computers/COMPUTER_ID/build \
  -H "Authorization: Bearer orb_YOUR_KEY"

7. Deploy Agent

curl


curl -X POST https://api.orbcloud.dev/v1/computers/COMPUTER_ID/agents \
  -H "Authorization: Bearer orb_YOUR_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

8. Access Exposed Ports

If your config includes [ports] expose = [8000], your app listening on port 8000 inside the computer is accessible at:


https://COMPUTER_SHORT_ID.orbcloud.dev

The short ID is the first 8 characters of the computer ID. Your app just binds to its port as normal — ORB handles the routing. You don't need to use any other port numbers.

9. Terminal Access

Open a live shell in your browser:


https://api.orbcloud.dev/terminal/COMPUTER_ID

Enter your API key. Full bash terminal inside the sandbox.

10. Destroy Computer

curl


curl -X DELETE https://api.orbcloud.dev/v1/computers/COMPUTER_ID \
  -H "Authorization: Bearer orb_YOUR_KEY"