Orgo - Cloud computers for AI agents

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

import requests

url = "https://www.orgo.ai/api/computers"

payload = {
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "agent-1",
    "os": "linux",
    "ram": 4,
    "cpu": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    workspace_id: '550e8400-e29b-41d4-a716-446655440000',
    name: 'agent-1',
    os: 'linux',
    ram: 4,
    cpu: 1
  })
};

fetch('https://www.orgo.ai/api/computers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.orgo.ai/api/computers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'workspace_id' => '550e8400-e29b-41d4-a716-446655440000',
    'name' => 'agent-1',
    'os' => 'linux',
    'ram' => 4,
    'cpu' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.orgo.ai/api/computers"

	payload := strings.NewReader("{\n  \"workspace_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"agent-1\",\n  \"os\": \"linux\",\n  \"ram\": 4,\n  \"cpu\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.orgo.ai/api/computers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"workspace_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"agent-1\",\n  \"os\": \"linux\",\n  \"ram\": 4,\n  \"cpu\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/computers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"workspace_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"agent-1\",\n  \"os\": \"linux\",\n  \"ram\": 4,\n  \"cpu\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "agent-1",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "resolution": "1280x720x24",
  "status": "running",
  "url": "http://162.43.189.25:8231",
  "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",
  "instance_details": {
    "provider": "metal",
    "id": "a3881618",
    "name": "a3881618",
    "webUrl": "http://162.43.189.25:8231",
    "vncHost": "162.43.189.25",
    "vncPort": 8232,
    "apiPort": 8231,
    "serverAddress": "http://10.0.0.4:9000",
    "resolution": "1280x720x24",
    "fromPool": false
  }
}

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. The older name project_id is also accepted; workspace_id wins when you send both.

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, android, or ios. Any other value returns 400. windows needs a Scale plan or a purchased Windows licence, otherwise it returns 403 with code WINDOWS_REQUIRES_SCALE. ios is a physical handset rather than a virtual computer. Every value other than linux only succeeds where the fleet has a host that supports it, otherwise create returns 422 with code OS_UNAVAILABLE.

integer

default:"4"

RAM in GB: 4, 8, 16, 32, or 64. 0 is treated as 4. Any other value returns 400. A macOS computer always has 10 GB: omit ram or send 10. Any other value with os: "macos" returns 400 with code MACOS_RAM_FIXED. One computer can use up to your account’s total RAM, 64 GB at most. A value above that, or above what your other computers leave of it, is rejected with 403, not clamped. Ignored for os: "ios", which always records 4.

number

vCPU: 0.5, 1, 2, 4, 6, 8, or 16. 0 is treated as 1. Any other value returns 400. Omitted means the vCPU that goes with the RAM: 1 for 4 GB, 2 for 8 GB, and 4 for 16 GB or more. With a template_ref, omitted means the template’s own vCPU, never below that RAM default. A value above what your account’s vCPU pool has left returns 403, not clamped. Ignored for os: "ios", which always records 1.

integer

Disk size in GB. When omitted it falls back to the template’s declared disk, or the workspace owner’s plan birth size when there is no template or the template declares none (40 GB on current paid plans). 0 counts as omitted. A negative or non-numeric value, or one 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, or 1920x1080x24 for macos. With a template_ref, omitting it keeps the template’s own resolution.

string

vGPU slice to attach: 2q (2 GB VRAM) or 4q (4 GB VRAM). "none", "", false, and "false" are treated as omitted. 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

default:"plan"

How the computer is paid for. plan counts it against the workspace owner’s plan. hourly runs it on credits by the hour, and free accounts can launch this way. Only the workspace owner can launch an hourly computer, and only with os linux or windows, no gpu, and no template_ref other than a starter template; anything else returns 400. Orgo quotes a Medium computer at the listed hourly price, so you do not send a quote. Send an Idempotency-Key header with a UUID so a retry launches the computer once. Without enough credit the create returns 402 with code insufficient_credit. Any other value returns 400 with code INVALID_BILLING_MODE.

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 own cpu and ram are brought down to what your account can give one computer rather than rejected; its disk is not, so a template disk above your ceiling returns 400 with code disk_exceeds_quota. Omitted means a plain base-image computer.

Common configurations

RAM	vCPU	Best for
4 GB	0.5	Light, always-on agents
4 GB	1	Standard workflows (default)
8 GB	2	Heavier automation
16 GB	4	Development and browser automation
32 GB	4	Memory-intensive tasks
64 GB	4	The largest computer you can create

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: 6, cpu: 8 and cpu: 16 therefore pass the value check and then return 403 with code PER_COMPUTER_CPU_CAP. Below the cap, a computer can use up to your account’s total RAM, and its vCPU comes from your account’s vCPU pool. Disk has a per-computer ceiling that 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

Deprecated alias for workspace_id, carrying the same value.

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, error, 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

Identifier of the computer’s current VM. It changes when the computer is started from its archive or wakes from storage, so keep id (the UUID) as your handle and read this fresh from Get computer.

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

Token for the computer’s WebSocket APIs (VNC, terminal, audio, events), sent as ?token=, and Bearer token for its Desktop API proxy. Rotates on every restart. Do not persist it. Take a fresh value from POST /computers or GET /computers/{id}. null for an MCP sign-in, or when the stored credential cannot be decrypted.

object

The computer’s placement and connection record: provider, id, name, webUrl, vncHost, vncPort, apiPort, serverAddress, resolution, and fromPool (always false), plus hypervisor and templateTerminals when they apply.

object

Present when the host reports how it launched the computer. What the computer runs on, in the shape Get computer returns.

object

Present alongside hardware. The host’s launch record for the new computer, without the host’s name or the source its state was restored from.

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

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

import requests

response = requests.post(
    "https://www.orgo.ai/api/computers",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "workspace_id": workspace_id,
        "name": "agent-1",
        "os": "linux",
        "ram": 4,
        "cpu": 1
    }
)

computer = response.json()
print(f"Created: {computer['id']}")
print(f"Connect at: {computer['connection_url']}")

const response = await fetch('https://www.orgo.ai/api/computers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspace_id: workspaceId,
    name: 'agent-1',
    os: 'linux',
    ram: 4,
    cpu: 1
  })
});

const computer = await response.json();
console.log(`Created: ${computer.id}`);
console.log(`Connect at: ${computer.connection_url}`);

Response

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "agent-1",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "resolution": "1280x720x24",
  "status": "running",
  "url": "http://162.43.189.25:8231",
  "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",
  "instance_details": {
    "provider": "metal",
    "id": "a3881618",
    "name": "a3881618",
    "webUrl": "http://162.43.189.25:8231",
    "vncHost": "162.43.189.25",
    "vncPort": 8232,
    "apiPort": 8231,
    "serverAddress": "http://10.0.0.4:9000",
    "resolution": "1280x720x24",
    "fromPool": false
  }
}

Errors

Every error body carries error. Most also carry a machine-readable code, and some carry extra fields, listed below.

Status	`code`	When
`400`	none	`workspace_id` or `name` missing, `ram`/`cpu`/`os`/`gpu` outside the accepted values, `template_ref` malformed, or a body that is valid JSON but not an object (`A computer configuration is required.`).
`400`	`MACOS_RAM_FIXED`	`os: "macos"` with a `ram` other than `10`: `macOS computers have 10 GB RAM. Contact us for more.`
`400`	`INVALID_BILLING_MODE`	`billing_mode` is neither `plan` nor `hourly`.
`400`	none	An hourly create with another `os`, a `gpu`, an image, or a template that is not a starter: `Hourly launch uses the operating system and hardware in your quote.`
`400`	`GPU_REQUIRES_LINUX`	`gpu` was combined with a non-Linux `os`.
`400`	`disk_exceeds_quota`	`disk_size_gb` is negative or not a number, or it (or the template’s declared disk) is above your per-computer ceiling. Also carries `max_disk_gb` and `canManageCapacity`.
`401`	none	The Bearer token starts with `sk_` but is not a known Orgo key. The body is `{ "error": "Invalid API key" }`.
`401`	none	No `Authorization` header, or a Bearer token that is not an `sk_` key. The body is `{ "error": "Authentication required" }`.
`401`	none	The workspace does not exist, or you are not its owner or a member: `You do not have access to this workspace.` A view-only member gets `This workspace is view-only. Ask the owner for write access (workspace_read_only).` A key scoped to another workspace gets `This API key cannot access this workspace (workspace_scope_mismatch).` These checks run during authentication, so they return `401`, not `403`.
`401`	none	The credential store is unavailable: `Service temporarily unavailable. The database is not accepting requests. Retry shortly.` Retry; your key is not the problem.
`402`	`insufficient_credit`	An hourly create without enough credit: `Add credit to launch this computer.`
`402`	`agent_account_prepaid_only`	An unclaimed agent account asked for a plan computer. It runs computers by the hour: send `"billing_mode": "hourly"`.
`403`	none	An hourly create by someone other than the workspace owner: `Only the workspace owner can approve hourly spending.`
`403`	`agent_account_expired`	The agent account expired before anyone claimed it.
`403`	`GUEST_RESTRICTED`	Share-link guests cannot create computers.
`403`	none	A grandfathered plan is over its computer or RAM limit.
`403`	`WINDOWS_REQUIRES_SCALE`	`os: "windows"` with no Windows licence available.
`403`	`UPGRADE_REQUIRED`	The workspace owner’s plan funds no computers.
`403`	`VM_SLOT_ADDON`, `RAM_ADDON`, `VCPU_ADDON`	The owner’s computer count, account RAM, or account vCPU pool is used up, and an add-on would raise it.
`403`	`ACCOUNT_COMPUTER_LIMIT`	The workspace is a client workspace under Invoicing and has reached the computer limit you set for it.
`403`	`CLIENT_PRICE_EXCEEDED`	The client pays a fixed price for the workspace, and this computer would push its cost above it. Raise the price first.
`403`	`PER_COMPUTER_RAM_CAP`, `PER_COMPUTER_CPU_CAP`	The request is past the universal per-computer hard cap, which no plan raises.
`403`	`CHANGE_PLAN`	The owner’s legacy plan is larger than every sold plan, so the fix is a plan change rather than an upgrade.
`403`	`PLAN_LIMIT`	The owner has a plan negotiated with Orgo, and the create is past one of its limits: a computer count, a per-OS count, the RAM pool, or a per-computer RAM or vCPU ceiling.
`409`	`NAME_TAKEN` / `name_taken`	A computer of that name already exists in the workspace.
`409`	`TEMPLATE_NOT_READY`	The template’s build is still running or has failed.
`409`	`HOURLY_NOT_ENABLED`, `COMPUTE_OFFER_UNAVAILABLE`	An hourly create when hourly computers are not available for the workspace, or no size is offered by the hour right now.
`422`	`OS_UNAVAILABLE`	No eligible host supports the requested `os`.
`500`	none	Unmapped failure, such as a database error or a body that is not valid JSON.
`503`	`golden_unavailable`	The template’s golden image could not be resolved on the host.
`503`	`TEMPLATE_HOST_UNAVAILABLE`	No template-capable host could take the create.
`503`	`TEMPLATE_READINESS_UNAVAILABLE`	The template’s build status could not be read. Also carries `retryable: true`.
`503`	`DEDICATED_CAPACITY_FULL`, `FLEET_CAPACITY_FULL`, `GPU_HOST_UNAVAILABLE`	Capacity is exhausted. Each also carries `retryable: true`.
`503`	`BACKEND_UNAVAILABLE`	The fleet is unreachable. Retry.
`503`	none	An hourly create whose funding could not be confirmed: `Hourly funding could not be confirmed. Retry this request.`

The quota responses (UPGRADE_REQUIRED, VM_SLOT_ADDON, RAM_ADDON, VCPU_ADDON, PER_COMPUTER_RAM_CAP, PER_COMPUTER_CPU_CAP, CHANGE_PLAN, PLAN_LIMIT, 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.

{
  "error": "disk_size_gb must be between 1 and 28 (8 GB plan + 20 GB add-on)",
  "code": "disk_exceeds_quota",
  "max_disk_gb": 28,
  "canManageCapacity": true
}

Unavailable operating systems

An accepted OS value can still be unavailable in your workspace. When no eligible host supports it, create returns 422 with code OS_UNAVAILABLE. Failed provisioning removes its placeholder record, so you can retry the name. Temporary capacity failures remain retryable service errors. The 300 GB disk cap is a product maximum, not an included allowance. Current Scale includes a 150 GB per-computer ceiling; unused storage add-ons can raise it to 300 GB. Complimentary current Scale has the same resource limits as paid current Scale.

Authorizations

Authorization

string

header

required

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

Headers

Idempotency-Key

string<uuid>

For billing_mode: "hourly": a UUID. A retry with the same key launches nothing new and returns the first outcome.

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"

enum<string>

default:linux

Operating system. Omitted, you get linux. Any other value returns 400. windows needs a Scale plan or a purchased Windows licence, otherwise it returns 403 with code WINDOWS_REQUIRES_SCALE. ios is a physical handset rather than a virtual computer. Every value other than linux only succeeds where the fleet has a host that supports it, otherwise create returns 422 with code OS_UNAVAILABLE.

Available options:

linux,

windows,

macos,

android,

ios

cpu

enum<number>

vCPU cores. Omitted, it follows the RAM: 4 GB gets 1, 8 GB gets 2, 16 GB or more gets 4. With a template_ref, the template's vCPU, never below that. Above what the account vCPU pool has left returns 403 (VCPU_ADDON). 0 is read as 1. Ignored for ios.

Available options:

0.5,

1,

2,

4,

6,

8,

16

ram

enum<integer>

default:4

RAM in GB. Omitted, you get 4, or 10 for macos. A macos computer is always 10: any other value returns 400 with code MACOS_RAM_FIXED. 10 with any other os returns 400. Capped by the workspace owner's plan.

Available options:

4,

8,

10,

16,

32,

64

disk_size_gb

integer

Disk size in GB. Omit to use template sizing or the owner plan birth size (40 GB on current paid plans). Your plan and unused storage add-ons determine the ceiling, up to 300 GB on current plans. A 150 GB plan ceiling does not include a free 300 GB disk.

resolution

string

default:1280x720x24

Display resolution in WIDTHxHEIGHTxDEPTH format. Omitted, 1280x720x24, or 1920x1080x24 for macos. With a template_ref, omitting it keeps the template's own resolution.

Example:

"1280x720x24"

gpu

enum<string>

vGPU slice to attach: 2q (2 GB VRAM) or 4q (4 GB VRAM). "none", "", false, and "false" are treated as omitted; any other value returns 400. Linux only: combining it with another os returns 400 with code GPU_REQUIRES_LINUX. Omitted, you get a CPU-only computer. If no GPU host can take the create, it either returns 503 with code GPU_HOST_UNAVAILABLE or falls back to a CPU computer, and the 201 body then carries gpu_downgraded and warning.

Available options:

2q,

4q

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"

billing_mode

enum<string>

default:plan

How the computer is paid for. plan (the default) counts against the owner's plan. hourly runs it by the hour from credit, at the listed price of a Medium computer of that os. Hourly is for the workspace owner only, Linux or Windows, with no gpu, image or snapshot, and only a starter template_ref. Send an Idempotency-Key header so a retry returns the same computer. Without enough credit it returns 402 (insufficient_credit). An unclaimed agent account's create is hourly when this is omitted.

Available options:

plan,

hourly

compute_quote_id

string<uuid>

With billing_mode: "hourly": a quote from POST /api/billing/compute. Omitted, Orgo makes one at the listed price. Sent without hourly, returns 400 (BILLING_MODE_REQUIRED).

compute_request_id

string<uuid>

With billing_mode: "hourly": a UUID naming this launch, so a retry with it reads the first outcome. Omitted, the Idempotency-Key is used when it is a UUID, else a new one.

Response

Computer created

A computer. No single response carries every field: POST /computers returns workspace_id, project_id, instance_id, fly_instance_id, and the connect fields, plus hardware and launch when the host reports them; GET /computers/{id} returns project_id, project_name, permissions, fly_instance_id, the connect fields, private_screens, hardware, device_tag, asleep, and suspension; a computer embedded in a workspace carries the stored row. Each operation's example shows what that operation returns.

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; GET /computers/{id} returns it as project_id.

Example:

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

project_name

string

Name of the parent workspace

Example:

"production"

enum<string>

Operating system. ios is a physical handset rather than a virtual computer.

Available options:

linux,

windows,

macos,

android,

ios

Example:

"linux"

ram

enum<integer>

RAM in GB. 10 or 12 occurs only on macOS.

Available options:

4,

8,

10,

12,

16,

32,

64

Example:

4

cpu

enum<number>

vCPU cores.

Available options:

0.5,

1,

2,

4,

6,

8,

16

Example:

1

status

enum<string>

Current status. suspending while a suspend is being saved, resuming while a resume brings it back from storage.

Available options:

creating,

running,

restarting,

updating,

suspending,

suspended,

resuming,

frozen,

stopped,

error,

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 | null

Identifier of the computer's current VM, returned by POST /computers. It changes when the computer is started from archive or woken from storage, so use id to refer to the computer. null while it has no host (frozen, or asleep in storage).

Example:

"a3881618"

hostname

string

Same-origin host for the computer's connection endpoints: www.orgo.ai. Empty while the computer has no instance id, such as when it is frozen or asleep in storage.

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 | null

VNC / WebSocket Bearer token. Rotates on restart, on start, and on a RAM resize, so do not persist it. null when you have view-only access to the workspace, or when the stored credential cannot be decrypted.

Example:

"a06db12a8683df96"

project_id

string

ID of the parent workspace, under its older name. POST /computers returns it as a deprecated alias of workspace_id; GET /computers/{id} returns only this name.

Example:

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

fly_instance_id

string | null

The instance id under its legacy name. The same value POST /computers returns as instance_id. GET /computers/{id} returns only this name. It changes when the computer is started from archive or woken from storage, so use id. null while it has no host (frozen, or asleep in storage).

Example:

"a3881618"

permissions

object

What your role in the workspace allows.

Show child attributes

private_screens

boolean

Returned by GET /computers/{id}. true when the computer's workspace keeps screens private, so the Orgo dashboard keeps the screen covered until someone chooses to show it.

Example:

false

instance_details

object

The computer's placement and connection record: provider, id, name, webUrl, vncHost, vncPort, apiPort, serverAddress, resolution, and fromPool, plus hypervisor and templateTerminals when they apply. GET /computers/{id} and the workspace endpoints remove every field whose name contains password, secret, token, api_key, or authorized_keys, in any letter case and at any depth.

hardware

object | null

What the computer runs on, from its current VM's launch record. GET /computers/{id} always returns it, null when the host has not reported a launch record for the computer's current VM. POST /computers returns it, with launch, only when the host reports how it launched the computer.

Show child attributes

device_tag

string | null

Returned by GET /computers/{id}. The Device ID Orgo prints on a physical device (or, for a macOS VM, on the Mac it runs on). null for a VM on Orgo's servers. Read-only.

asleep

object | null

Returned by GET /computers/{id}. Where a suspended computer is. null when it is not suspended.

Show child attributes

suspension

object | null

Returned by GET /computers/{id}. The current suspension of a suspended, suspending or resuming computer. null otherwise, or when nothing is recorded.

Show child attributes

launch

object

Returned by POST /computers alongside hardware, when the host reports how it launched the computer: the host's launch record for the new computer, without the host's name or the source its state was restored from.

resolution

string

Display resolution in WIDTHxHEIGHTxDEPTH format. Returned by POST /computers.

Example:

"1280x720x24"

gpu_downgraded

boolean

Returned by POST /computers only, present and true when you asked for a gpu and a CPU computer was created instead.

warning

string

Present only alongside gpu_downgraded, explaining the downgrade.

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

import requests

url = "https://www.orgo.ai/api/computers"

payload = {
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "agent-1",
    "os": "linux",
    "ram": 4,
    "cpu": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    workspace_id: '550e8400-e29b-41d4-a716-446655440000',
    name: 'agent-1',
    os: 'linux',
    ram: 4,
    cpu: 1
  })
};

fetch('https://www.orgo.ai/api/computers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.orgo.ai/api/computers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'workspace_id' => '550e8400-e29b-41d4-a716-446655440000',
    'name' => 'agent-1',
    'os' => 'linux',
    'ram' => 4,
    'cpu' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.orgo.ai/api/computers"

	payload := strings.NewReader("{\n  \"workspace_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"agent-1\",\n  \"os\": \"linux\",\n  \"ram\": 4,\n  \"cpu\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.orgo.ai/api/computers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"workspace_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"agent-1\",\n  \"os\": \"linux\",\n  \"ram\": 4,\n  \"cpu\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/computers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"workspace_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"agent-1\",\n  \"os\": \"linux\",\n  \"ram\": 4,\n  \"cpu\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "agent-1",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "resolution": "1280x720x24",
  "status": "running",
  "url": "http://162.43.189.25:8231",
  "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",
  "instance_details": {
    "provider": "metal",
    "id": "a3881618",
    "name": "a3881618",
    "webUrl": "http://162.43.189.25:8231",
    "vncHost": "162.43.189.25",
    "vncPort": 8232,
    "apiPort": 8231,
    "serverAddress": "http://10.0.0.4:9000",
    "resolution": "1280x720x24",
    "fromPool": false
  }
}

Overview

Support

Account

Agent accounts

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Create computer

Request

Common configurations

Response

Example

Response

Errors

Unavailable operating systems

Authorizations

Headers

Body

Response

​Request

​Common configurations

​Response

​Example

​Response

​Errors

​Unavailable operating systems

Authorizations

Headers

Body

Response

Request

Common configurations

Response

Example

Response

Errors

Unavailable operating systems