Skip to main content
POST
/
computers
Create computer
curl --request POST \
  --url https://www.orgo.ai/api/computers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "agent-1",
  "os": "linux",
  "ram": 4,
  "cpu": 1
}
'
{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "agent-1",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "status": "running",
  "url": "https://orgo.ai/workspaces/a3bb189e-8bf9-3888-9912-ace4e6543002",
  "created_at": "2026-04-07T10:35:00Z",
  "instance_id": "a3881618",
  "fly_instance_id": "a3881618",
  "hostname": "www.orgo.ai",
  "connection_url": "https://www.orgo.ai/desktops/a3881618",
  "vnc_password": "a06db12a8683df96"
}
Creates a new virtual computer in a workspace. The computer starts automatically after creation.
Computers boot in under 500ms and come pre-configured with a desktop environment, browser, and common tools.

​
Request

​
workspace_id
string
required
ID of the workspace to create the computer in.
​
name
string
required
Computer name. Must be unique within the workspace.
​
os
string
default:"linux"
Operating system. Currently only linux is supported.
​
ram
integer
default:"4"
RAM in GB: 4, 8, 16, 32, or 64. Capped by your plan’s per-computer limit.
​
cpu
integer
default:"1"
CPU cores: 1, 2, 4, 8, or 16. Capped by your plan’s per-computer limit.
​
disk_size_gb
integer
default:"8"
Disk size in GB. Defaults to 8 GB. Capped by your plan’s per-computer limit.
​
resolution
string
default:"1280x720x24"
Display resolution in WIDTHxHEIGHTxDEPTH format (e.g., 1024x768x24, 1920x1080x24).
​
auto_stop_minutes
integer
Auto-stop after this many minutes of inactivity. Defaults to no auto-stop. Set to 0 to explicitly keep the computer always-on.

​
Common configurations

RAMCPUBest for
4 GB1 coreStandard workflows (default)
8 GB2 coresHeavier automation
16 GB4 coresDevelopment, memory-intensive tasks
32 GB8 coresLarge-scale processing
64 GB16 coresEnterprise workloads
Maximum CPU/RAM per computer is capped by your plan. See https://orgo.ai/pricing.

​
Response

Returns the created computer object.
​
id
string
Unique computer identifier.
​
name
string
Computer name.
​
workspace_id
string
Parent workspace ID.
​
os
string
Operating system.
​
ram
integer
RAM in GB.
​
cpu
integer
CPU cores.
​
resolution
string
Display resolution in WIDTHxHEIGHTxDEPTH format.
​
status
string
One of creating, starting, running, stopping, stopped, restarting, suspended, deleting, error.
​
auto_stop_minutes
integer
Minutes of inactivity before auto-stop. null if auto-stop is disabled.
​
url
string
URL to view the computer in the dashboard.
​
created_at
string
ISO 8601 timestamp.
​
instance_id
string
Stable identifier for the underlying compute instance. Use this to construct the hostname and to reference the VM across restarts.
​
fly_instance_id
string
deprecated
Deprecated alias for instance_id. Returned for backwards compatibility - new clients should read instance_id.
​
hostname
string
Same-origin host for the computer’s connection endpoints. Always 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 the WebSocket endpoints; HTTP Desktop API calls go to https://www.orgo.ai/api/desktops/{instance_id}/proxy/{endpoint}.
​
vnc_password
string
VNC / Bearer token for the computer’s WebSocket APIs (VNC, terminal, bash, audio, events). Rotates on every restart - do not persist across restarts; use a fresh value from the latest POST /computers or GET /computers/{id}.
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. Just poll https://www.orgo.ai/api/desktops/{instance_id}/proxy/health until it returns 200 (~300 ms with golden snapshots), then connect.

​
Example

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

​
Response

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "agent-1",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "resolution": "1280x720x24",
  "status": "running",
  "url": "https://orgo.ai/workspaces/550e8400-e29b-41d4-a716-446655440000/computers/a3bb189e-8bf9-3888-9912-ace4e6543002",
  "created_at": "2026-04-07T10:35:00Z",
  "instance_id": "a3881618",
  "hostname": "www.orgo.ai",
  "connection_url": "https://www.orgo.ai/desktops/a3881618",
  "vnc_password": "a06db12a8683df96"
}

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

Available options:
linux
​
cpu
enum<integer>
default:1

CPU cores. Capped by plan.

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

RAM in GB. Capped by plan.

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

Disk size in GB. Capped by plan.

​
resolution
string
default:1280x720x24

Display resolution in WIDTHxHEIGHTxDEPTH format

Example:

"1280x720x24"

​
auto_stop_minutes
integer

Auto-stop after this many minutes of inactivity. Defaults to disabled. Set to 0 to explicitly keep the computer always-on.

Required range: x >= 0
Example:

30

Response

Computer created

​
id
string

Unique computer identifier

Example:

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

​
name
string

Computer name

Example:

"agent-1"

​
project_name
string

Name of the parent workspace

Example:

"production"

​
os
enum<string>

Operating system

Available options:
linux
Example:

"linux"

​
ram
enum<integer>

RAM in GB

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

4

​
cpu
enum<integer>

CPU cores

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

1

​
disk_size_gb
integer

Disk size in GB

Example:

8

​
status
enum<string>

Current status

Available options:
creating,
starting,
running,
stopping,
stopped,
restarting,
suspended,
deleting,
error
Example:

"running"

​
url
string

Dashboard URL for the computer

Example:

"https://orgo.ai/workspaces/a3bb189e-8bf9-3888-9912-ace4e6543002"

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

​
fly_instance_id
string
deprecated

Deprecated alias for instance_id. Returned for backwards compatibility - new clients should read instance_id.

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 - do not persist across restarts.

Example:

"a06db12a8683df96"