Skip to main content
POST
Create computer
Creates a computer in a workspace and boots it. The response carries everything you need to connect, so no follow-up request is required.
A 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

string
required
ID of the workspace to create the computer in. Omitting it returns 400.
string
required
Computer name. Must be unique within the workspace. A name already in use returns 409, and omitting the field returns 400.
string
default:"linux"
Operating system: 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.
integer
default:"4"
RAM in GB: 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.
number
default:"1"
vCPU: 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.
integer
default:"8"
Disk size in GB. When omitted it falls back to the template’s declared disk, or 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.
string
default:"1280x720x24"
Display resolution in WIDTHxHEIGHTxDEPTH format (e.g. 1024x768x24, 1920x1080x24). Omitted means 1280x720x24.
string
vGPU slice to attach: 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.
string
Launch from a template’s golden snapshot instead of a base image, so the computer boots fully configured. Format 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

One computer is capped at 4 vCPU, 64 GB RAM, and 300 GB of disk. No plan on sale raises that cap, and add-ons only take you up to it. On every plan on sale, 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.
string
Computer identifier (UUID).
string
Computer name.
string
Parent workspace ID.
string
Operating system.
integer
RAM in GB.
number
vCPU.
string
Display resolution in WIDTHxHEIGHTxDEPTH format.
string
One of creating, running, restarting, updating, suspended, frozen, stopped, deleted. A successful create returns running. See Get computer for what each value means.
string
The computer’s API address on its fleet host, as 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.
string
ISO 8601 timestamp.
string
Stable identifier for the underlying compute instance. Use this to construct the hostname and to reference the computer across restarts.
string
Deprecated alias for instance_id, carrying the same value.
string
Same-origin host for the computer’s connection endpoints: www.orgo.ai.
string
Same-origin connection base (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}.
string
VNC / Bearer token for the computer’s WebSocket APIs (VNC, terminal, bash, audio, events). Rotates on every restart. Do not persist it. Take a fresh value from POST /computers or GET /computers/{id}. null when the stored credential cannot be decrypted.
object
The computer’s placement and connection record: provider, id, name, webUrl, vncHost, vncPort, apiPort, serverAddress, resolution, plus hypervisor and templateTerminals when they apply.
boolean
Present and true only when you asked for a gpu and no GPU host was available, so a CPU computer was created instead.
string
Present only alongside gpu_downgraded, explaining the downgrade.
Fast path: 1 API call. The response above contains everything needed to connect. No follow-up GET /computers/{id} or GET /computers/{id}/vnc-password is required. Poll https://www.orgo.ai/api/desktops/{instance_id}/proxy/health until it returns 200, then connect.

Example

Response

Errors

Every error body carries error. Most also carry a machine-readable code, and some carry extra fields, listed below. The quota responses (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

Authorization
string
header
required

API key authentication. Get your key at orgo.ai/workspaces

Body

application/json
workspace_id
string
required

ID of the workspace to create the computer in

Example:

"550e8400-e29b-41d4-a716-446655440000"

name
string
required

Computer name

Minimum string length: 1
Example:

"agent-1"

os
enum<string>
default:linux

Operating system. Omitted, you get linux. windows needs a Windows licence on the owner's plan and is refused with 403 otherwise.

Available options:
linux,
windows,
macos,
android
cpu
enum<number>
default:1

vCPU cores. Omitted, you get 1. Capped by the workspace owner's plan.

Available options:
0.5,
1,
2,
4,
8,
16
ram
enum<integer>
default:4

RAM in GB. Omitted, you get 4. Capped by the workspace owner's plan.

Available options:
4,
8,
16,
32,
64
disk_size_gb
integer
default:8

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.

resolution
string
default:1280x720x24

Display resolution in WIDTHxHEIGHTxDEPTH format

Example:

"1280x720x24"

template_ref
string

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.

Example:

"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.

id
string

Unique computer identifier

Example:

"a3bb189e-8bf9-3888-9912-ace4e6543002"

name
string

Computer name

Example:

"agent-1"

workspace_id
string

ID of the workspace the computer belongs to. Returned by POST /computers.

Example:

"550e8400-e29b-41d4-a716-446655440000"

project_name
string

Name of the parent workspace

Example:

"production"

os
enum<string>

Operating system.

Available options:
linux,
windows,
macos,
android
Example:

"linux"

ram
enum<integer>

RAM in GB.

Available options:
4,
8,
16,
32,
64
Example:

4

cpu
enum<number>

vCPU cores.

Available options:
0.5,
1,
2,
4,
8,
16
Example:

1

status
enum<string>

Current status

Available options:
creating,
running,
restarting,
updating,
suspended,
frozen,
stopped,
deleted
Example:

"running"

url
string

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.

Example:

"http://198.51.100.24:8081"

created_at
string<date-time>
instance_id
string

Stable identifier for the underlying compute instance. Use this for proxy hostnames and for any client that needs to reference the VM across restarts.

Example:

"a3881618"

hostname
string

Same-origin host for the computer's connection endpoints (always www.orgo.ai).

Example:

"www.orgo.ai"

connection_url
string

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}.

Example:

"https://www.orgo.ai/desktops/a3881618"

vnc_password
string

VNC / WebSocket Bearer token. Rotates on every restart, so do not persist it across restarts.

Example:

"a06db12a8683df96"