Create computer
Provision a new computer in a workspace.
template_ref create restores the template’s golden snapshot, which boots far faster than the plain base image. Without one the computer cold-boots from the base image.Request
400.409, and omitting the field returns 400.linux, windows, macos, or android. Any other value returns 400. windows needs a Scale plan or a purchased Windows licence, otherwise it returns 403 with code WINDOWS_REQUIRES_SCALE. macos and android boot on shim hosts, so they only succeed where the fleet has a host that supports them.4, 8, 16, 32, or 64. Any other value returns 400. A value above your plan’s per-computer ceiling is rejected with 403, not clamped.0.5, 1, 2, 4, 8, or 16. Any other value returns 400. A value above your plan’s per-computer ceiling is rejected with 403, not clamped.8 GB when there is no template. A value below 1 or above your plan’s per-computer ceiling is rejected with 400 and code disk_exceeds_quota, not clamped.WIDTHxHEIGHTxDEPTH format (e.g. 1024x768x24, 1920x1080x24). Omitted means 1280x720x24.2q (2 GB VRAM) or 4q (4 GB VRAM). Any other value returns 400. Linux only: combining it with another os returns 400 with code GPU_REQUIRES_LINUX. Omitted means a CPU-only computer. If no GPU host can take the create, the request either returns 503 GPU_HOST_UNAVAILABLE or falls back to a CPU computer, in which case the 201 body carries gpu_downgraded and warning.namespace/name@version, for example system/claude-code@1.0.0 (curated) or default/my-template@1.0.0 (your own). A malformed ref returns 400; a template whose build is not ready returns 409 with code TEMPLATE_NOT_READY. Explicit cpu, ram, and disk_size_gb override the template’s own hardware; the template’s implicit hardware is clamped to your plan’s per-computer ceiling rather than rejected. Omitted means a plain base-image computer.Common configurations
cpu: 8 and cpu: 16 therefore pass the value check and then return 403 with code PER_COMPUTER_CPU_CAP.
Your own per-computer ceiling starts below the cap and depends on your plan. See https://orgo.ai/pricing.
Response
Returns the created computer.WIDTHxHEIGHTxDEPTH format.creating, running, restarting, updating, suspended, frozen, stopped, deleted. A successful create returns running. See Get computer for what each value means.http://{host}:{port}. This is an internal fleet address, not a dashboard link and not the endpoint you connect to. Use connection_url to connect. It is rewritten whenever the computer restarts, is started again, or has its RAM resized.hostname and to reference the computer across restarts.instance_id, carrying the same value.www.orgo.ai.https://www.orgo.ai/desktops/{instance_id}). Append /ws/websockify, /ws/terminal, or /ws/audio for the WebSocket endpoints; HTTP Desktop API calls go to https://www.orgo.ai/api/desktops/{instance_id}/proxy/{endpoint}.POST /computers or GET /computers/{id}. null when the stored credential cannot be decrypted.provider, id, name, webUrl, vncHost, vncPort, apiPort, serverAddress, resolution, plus hypervisor and templateTerminals when they apply.true only when you asked for a gpu and no GPU host was available, so a CPU computer was created instead.gpu_downgraded, explaining the downgrade.Example
Response
Errors
Every error body carrieserror. Most also carry a machine-readable code, and some carry extra fields, listed below.
UPGRADE_REQUIRED, VM_SLOT_ADDON, RAM_ADDON, VCPU_ADDON, PER_COMPUTER_RAM_CAP, PER_COMPUTER_CPU_CAP, CHANGE_PLAN, and the code-less grandfathered case) also carry canManageCapacity, which tells you whether you are the workspace owner and can raise the limit yourself. Where a plan change would fix it, they also carry upgradeTier. WINDOWS_REQUIRES_SCALE carries upgradeTier alone.
Authorizations
API key authentication. Get your key at orgo.ai/workspaces
Body
ID of the workspace to create the computer in
"550e8400-e29b-41d4-a716-446655440000"
Computer name
1"agent-1"
Operating system. Omitted, you get linux. windows needs a Windows licence on the owner's plan and is refused with 403 otherwise.
linux, windows, macos, android vCPU cores. Omitted, you get 1. Capped by the workspace owner's plan.
0.5, 1, 2, 4, 8, 16 RAM in GB. Omitted, you get 4. Capped by the workspace owner's plan.
4, 8, 16, 32, 64 Disk size in GB. Omitted, you get the template's disk if you passed template_ref, otherwise 8. Capped by the workspace owner's plan.
Display resolution in WIDTHxHEIGHTxDEPTH format
"1280x720x24"
Launch from a template's golden snapshot instead of a base image. Format namespace/name@version, e.g. system/claude-code@1.0.0 (curated) or default/my-template@1.0.0 (your own). The hardware fields above override the template's defaults. The template's build must be ready.
"system/claude-code@1.0.0"
Response
Computer created
A computer. No single response carries every field: POST /computers returns the workspace ids and the connect fields, GET /computers/{id} returns project_name and the connect fields, and a computer embedded in a workspace carries the stored row. Each operation's example shows what that operation returns.
Unique computer identifier
"a3bb189e-8bf9-3888-9912-ace4e6543002"
Computer name
"agent-1"
ID of the workspace the computer belongs to. Returned by POST /computers.
"550e8400-e29b-41d4-a716-446655440000"
Name of the parent workspace
"production"
Operating system.
linux, windows, macos, android "linux"
RAM in GB.
4, 8, 16, 32, 64 4
vCPU cores.
0.5, 1, 2, 4, 8, 16 1
Current status
creating, running, restarting, updating, suspended, frozen, stopped, deleted "running"
Base URL of the computer's own API on the host that runs it, as http://<host>:<port>. Plain HTTP, and reachable only from inside Orgo's network. It is not a dashboard link and not an endpoint you can call. Use connection_url from your own code.
"http://198.51.100.24:8081"
Stable identifier for the underlying compute instance. Use this for proxy hostnames and for any client that needs to reference the VM across restarts.
"a3881618"
Same-origin host for the computer's connection endpoints (always www.orgo.ai).
"www.orgo.ai"
Same-origin connection base (https://www.orgo.ai/desktops/{instance_id}). Append /ws/websockify, /ws/terminal, or /ws/audio for WebSocket endpoints; HTTP Desktop API calls go to https://www.orgo.ai/api/desktops/{instance_id}/proxy/{endpoint}.
"https://www.orgo.ai/desktops/a3881618"
VNC / WebSocket Bearer token. Rotates on every restart, so do not persist it across restarts.
"a06db12a8683df96"