Orgo - Cloud computers for AI agents

The Orgo API provisions virtual computers and controls them programmatically. Use it to run agent fleets, automation workflows, or browser testing.

Base URL

https://www.orgo.ai/api

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer $ORGO_API_KEY

Get your API key at orgo.ai/start. See Authentication for key scopes and what they do and do not restrict.

Quick start

1. Create a workspace

Workspaces organize your computers.

curl -X POST https://www.orgo.ai/api/workspaces \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-workspace"}'

2. Create a computer

curl -X POST https://www.orgo.ai/api/computers \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"workspace_id\": \"$WORKSPACE_ID\", \"name\": \"agent-1\", \"os\": \"linux\", \"ram\": 4, \"cpu\": 1}"

3. Control the computer

# Take a screenshot
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/screenshot \
  -H "Authorization: Bearer $ORGO_API_KEY"

# Click at coordinates
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'

# Type text
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/type \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world"}'

# Run a bash command
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/bash \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}'

Resource hierarchy

User
└── Workspaces
    └── Computers

Workspaces group related computers together. Use them to separate environments (production, staging) or projects.

Computer specs

Parameter	Values the API accepts	Default when omitted
`os`	`linux`, `windows`, `macos`, `android`, `ios`	`linux`
`cpu`	0.5, 1, 2, 4, 8, 16 cores	1, or the template’s size when you pass `template_ref`
`ram`	4, 8, 16, 32, 64 GB (macOS also accepts 12)	4, or the template’s size when you pass `template_ref`
`disk_size_gb`	1 up to your plan’s per-computer maximum	The template’s disk when you pass `template_ref`. Otherwise set by your plan: 40 GB on current paid plans, 20 GB on legacy plans, and never above the plan’s per-computer maximum (8 GB on Free).
`gpu`	`2q` (2 GB VRAM), `4q` (4 GB VRAM)	none
`resolution`	`WIDTHxHEIGHTxDEPTH` (e.g. `1024x768x24`, `1920x1080x24`)	`1280x720x24` (`1920x1080x24` on macOS), or the template’s when you pass `template_ref`

Any other value for os, cpu, ram, or gpu is rejected with 400. ios places the computer on a physical handset, so it succeeds only where one is available, and cpu and ram are ignored for it. GPU computers are Linux only. Windows requires either a Windows license on the account or a plan that includes Windows. Maximum CPU, RAM, and disk per computer are capped by your plan. See orgo.ai/pricing.

Recommended configurations

RAM	CPU	Best for
4 GB	1 core	Standard workflows (default)
8 GB	2 cores	Heavier automation
16 GB	4 cores	Development
32 GB	8 cores	Large-scale processing

Available actions

Mouse

Click (left, right, double)
Move (hover, without clicking)
Drag
Scroll

Keyboard

Type text
Press keys (Enter, Tab, ctrl+c, etc.)

Execution

Bash commands
Python code

Real-time (WebSocket)

Terminal: interactive PTY shell
Audio: live PCM audio stream from the computer’s virtual speaker
Events: subscribe to window, clipboard, file, process, and idle events

Lifecycle

Start, stop, restart
Auto-stop (off by default; configurable per computer on paid plans)
Clone (copy a computer with full disk state)
Fork (copy a running computer, memory included)
Resize (live CPU/RAM/disk hot-resize)
Move (transfer between workspaces)

Other

Screenshots
Wait/delays

Templates

Templates are reproducible computers defined in a single orgo.ai/v1 file: hardware, installed apps, long-running services, secrets, and lifecycle hooks. Orgo builds the file once into a golden snapshot, and every launch restores from it in seconds.

Launch a curated template. Pass a system/… ref as template_ref to Create computer.
Author your own. Validate, publish, and build over HTTP. Start at the Templates API.

Template authoring availability depends on your plan. See orgo.ai/pricing.

Resource IDs

Workspaces, computers, files, and threads are identified by UUIDs. Pass the UUID in the URL path wherever you see an {id} placeholder, as in /workspaces/{id} or /computers/{id}/click. Workspace and computer UUIDs are returned in the id field of every create, get, and list response. A computer also has a separate instance id, returned as instance_id by Create computer. The instance id addresses WebSocket paths such as wss://www.orgo.ai/desktops/{instance_id}/ws/websockify, not the REST endpoints.

Error responses

Errors return a JSON object with an error field holding a human-readable message:

{
  "error": "Invalid API key"
}

The OpenAI-compatible endpoints under /v1 are the exception. Their error is an object with type, message, and code, described in Create chat completion. Some errors add a machine-readable code (for example workspace_scope_mismatch, GUEST_RESTRICTED, disk_exceeds_quota). Branch on code where it is present. It is stable, and the error string is not. Workspaces are called projects internally, so a few error messages on the workspace endpoints say “project”. They refer to the same resource.

Status	Meaning
`200`	Success
`201`	Created
`204`	Success with no body (destroying a screen)
`207`	Partial success (resize only: some dimensions applied, others rejected)
`400`	Invalid request: bad JSON, missing required field, out-of-range value
`401`	Invalid API key (`Invalid API key`) or no API key (`Authentication required`). Some endpoints also answer an access or scope failure with `401`.
`402`	Payment required: the credit balance is too low, a free trial computer can no longer run, or a computer paid for on its own has a lapsed payment
`403`	Authenticated, but not allowed: plan limit exceeded, workspace scope mismatch, view-only access, or no access to the resource
`404`	Resource not found
`405`	Method not allowed. Check the verb for the endpoint.
`409`	Conflict: the resource is in a state that blocks this operation (e.g. resizing a computer that is not running)
`422`	Validation failed: all dimensions of a resize were rejected
`429`	Rate limited. Back off and retry.
`500`	Unexpected server error
`501`	Not supported on this computer’s operating system (for example `exec` on an iPhone)
`502`	The computer was asked to do something and did not confirm it (for example placing an uploaded file)
`503`	Orgo, or the computer, could not be reached. Retry after the `Retry-After` delay when the response carries one.
`504`	A command on the computer ran past its allowed time (`bash` and `exec`)

Rate limits

Some endpoints are rate limited. If you get a 429, back off with exponential retry: start at 1s, double each retry, and cap the delay at 60s. Email spencer@orgo.ai if you need higher limits.

Next steps

Create Workspace

Organize computers

Create Computer

Provision a computer

Templates

Reproducible computers

Authentication

API key setup

Use Any Model

Claude, GPT, Gemini, and more

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

API Reference

Base URL

Authentication

Quick start

1. Create a workspace

2. Create a computer

3. Control the computer

Resource hierarchy

Computer specs

Recommended configurations

Available actions

Mouse

Keyboard

Execution

Real-time (WebSocket)

Lifecycle

Other

Templates

Resource IDs

Error responses

Rate limits

Next steps

Create Workspace

Create Computer

Templates

Authentication

Use Any Model

​Base URL

​Authentication

​Quick start

​1. Create a workspace

​2. Create a computer

​3. Control the computer

​Resource hierarchy

​Computer specs

​Recommended configurations

​Available actions

​Mouse

​Keyboard

​Execution

​Real-time (WebSocket)

​Lifecycle

​Other

​Templates

​Resource IDs

​Error responses

​Rate limits

​Next steps

Create Workspace

Create Computer

Templates

Authentication

Use Any Model

Base URL

Authentication

Quick start

1. Create a workspace

2. Create a computer

3. Control the computer

Resource hierarchy

Computer specs

Recommended configurations

Available actions

Mouse

Keyboard

Execution

Real-time (WebSocket)

Lifecycle

Other

Templates

Resource IDs

Error responses

Rate limits

Next steps