Orgo - Cloud computers for AI agents

GET

computers

{id}

Get computer

curl --request GET \
  --url https://www.orgo.ai/api/computers/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.orgo.ai/api/computers/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": {
    "canView": true,
    "canWrite": true,
    "canManageAccess": true
  },
  "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
  },
  "name": "agent-1",
  "project_name": "production",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "status": "running",
  "url": "http://162.43.189.25:8231",
  "fly_instance_id": "a3881618",
  "created_at": "2026-04-07T10:35:00Z",
  "hostname": "www.orgo.ai",
  "connection_url": "https://www.orgo.ai/desktops/a3881618",
  "vnc_password": "a06db12a8683df96",
  "private_screens": false,
  "hardware": null
}

Returns a computer’s details, including its current status and everything needed to connect to it.

Path parameters

string

required

Computer UUID or instance_id. Both resolve to the same computer.

Response

string

Computer identifier (UUID).

string

Computer name.

string

ID of the parent workspace.

string

Name of the parent workspace.

object

What you can do in the computer’s workspace: canView, canWrite, and canManageAccess, each a boolean.

object

The computer’s placement and connection record, with every field whose name contains password, secret, token, api_key, or authorized_keys removed.

string

Operating system: linux, windows, macos, android, or ios.

integer

RAM in GB.

number

vCPU. Fractional for 0.5 vCPU computers.

string

One of creating, running, restarting, updating, suspending, suspended, resuming, frozen, stopped, error, deleted. See Status values.

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. The value is rewritten whenever the computer restarts, is started again, or has its RAM resized. It still holds the last host’s address after the computer is stopped, so it is only meaningful while the computer is running.

string

Identifier of the computer’s current VM, the same value POST /computers returns as instance_id. 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 this endpoint. null while the computer has no host (frozen, or asleep in storage). This endpoint returns the field under its legacy name only.

string

ISO 8601 timestamp.

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.

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}. Empty while the computer has no instance id, such as when it is frozen or asleep in storage.

string

Current VNC / WebSocket token. Rotates on restart, on start, and on a RAM resize. null when you have view-only access to the workspace, for an MCP sign-in, or when the stored credential cannot be decrypted.

boolean

true when the computer’s workspace keeps screens private, so the Orgo dashboard keeps the screen covered until someone chooses to show it.

object | null

What the computer runs on, from its current VM’s launch record: host_cpu (family, name, and signature, or null), cpu_model, hypervisor, qemu, boot, fallback, and launched_at. null when the host has not reported a launch record for the computer’s current VM.

string | null

The Device ID Orgo prints on a physical device, or for a macOS computer on the Mac it runs on. Read-only. null for a computer on Orgo’s servers.

object | null

Where a suspended computer is. null for any other status. where is host (resumes on interaction) or storage (moved off its host; Start, Resume, or any action wakes it in about a minute). since is when it went to sleep. A computer in storage also carries reason (hours, idle, or null), waking ({ since, expected_seconds } while a wake runs, else null), and wake_error (why the last wake failed, else null).

object | null

The computer’s current suspension while it is suspending, suspended, or resuming: state (capturing, uploading, stored, resuming, resumed, failed, or abandoned), where (host or storage), saving (true while its copy is still being saved; Resume and Delete still work meanwhile), and region (the storage region, or null). null for any other status or when nothing is recorded. Get suspension has the full record.

Status values

Status	Meaning
`creating`	The record exists and the computer is being provisioned.
`running`	The computer is up on a host and reachable.
`restarting`	A restart is in flight.
`updating`	An in-place OS image update is in flight.
`suspending`	A suspend is saving its memory.
`suspended`	Paused with its memory saved, on its host or in storage. Start, or any action, wakes a computer stored off its host. One still on its host resumes on interaction or through Resume.
`resuming`	Its memory is being brought back from storage.
`frozen`	Stopped. The disk is archived to object storage and no host is held. This is what stop produces.
`stopped`	The computer was not found on its host, or its host reported a terminal state. Like `frozen`, it can be started again.
`error`	Its host reported the computer in an error state when a restart or OS update did not finish. Like `stopped`, it can be started again.
`deleted`	Tombstoned after its archived disk passed the retention window.

Example

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

import requests

response = requests.get(
    f"https://www.orgo.ai/api/computers/{computer_id}",
    headers={"Authorization": f"Bearer {api_key}"}
)

computer = response.json()
print(f"Status: {computer['status']}")

const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}`, {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

const computer = await response.json();
console.log(`Status: ${computer.status}`);

Response

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": { "canView": true, "canWrite": true, "canManageAccess": true },
  "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
  },
  "name": "agent-1",
  "project_name": "production",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "status": "running",
  "url": "http://162.43.189.25:8231",
  "fly_instance_id": "a3881618",
  "created_at": "2026-04-07T10:35:00Z",
  "hostname": "www.orgo.ai",
  "connection_url": "https://www.orgo.ai/desktops/a3881618",
  "vnc_password": "a06db12a8683df96",
  "private_screens": false,
  "hardware": null,
  "device_tag": null,
  "asleep": null,
  "suspension": null
}

Errors

Status	Body	When
`401`	`{ "error": "Invalid API key" }`	The Bearer token starts with `sk_` but is not a known Orgo key.
`401`	`{ "error": "Authentication required" }`	No `Authorization` header, or a Bearer token that is not an `sk_` key.
`402`	`{ "error": "Choose a plan to continue." }`	The computer is a trial computer whose trial has ended.
`403`	`{ "error": "You do not have access to this workspace." }`	You are neither the owner nor a member of the computer’s workspace.
`403`	`{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }`	The API key is scoped to a different workspace.
`404`	`{ "error": "Desktop not found" }`	No computer matches the id.
`500`	`{ "error": "…" }`	Lookup failed.
`503`	`{ "error": "Service temporarily unavailable. The database is not accepting requests. Retry shortly." }`	The credential store is unavailable. Carries `Retry-After: 5`.

Rename a computer

PATCH /computers/{id} updates a computer’s name and its mascot. It takes the same path parameter as GET, and requires that you own the workspace. A view-only member gets 403, and a member with write access who is not the owner gets 404 with Access denied.

string

New computer name. Omitted leaves the name alone; an empty or non-string value returns 400.

object

The computer’s mascot look, with all fields optional: color (stone, pearl, graphite, ink, green, blue, red, orange, purple, cyan, pink, yellow, teal, coral), expression (deadpan, friendly, focused, thinking, excited, sleepy, surprised, skeptical, worried, mischievous), and accessory (none, beanie, tophat, party, glasses, sunglasses, bow). Unrecognised fields and values are dropped rather than rejected, so a field you send with an unknown value falls back to the default. null clears the mascot; omitting the field leaves it alone; any other non-object value returns 400.

The response is the updated record, not the full computer object. It carries id, name, bot_mascot (null when unset), and updated_at.

curl -X PATCH https://www.orgo.ai/api/computers/$COMPUTER_ID \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-1-renamed", "bot_mascot": {"color": "teal", "expression": "focused"}}'

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "agent-1-renamed",
  "bot_mascot": { "color": "teal", "expression": "focused" },
  "updated_at": "2026-04-07T11:02:14.000Z"
}

Status	Body	When
`400`	`{ "error": "Computer name cannot be empty" }`	`name` is present but empty or not a string.
`400`	`{ "error": "bot_mascot must be an object or null" }`	`bot_mascot` is neither an object nor `null`.
`401`	`{ "error": "Invalid API key" }`	The Bearer token starts with `sk_` but is not a known Orgo key.
`401`	`{ "error": "Authentication required" }`	No `Authorization` header, or a Bearer token that is not an `sk_` key.
`402`	`{ "error": "Choose a plan to continue." }`	The computer is a trial computer whose trial has ended.
`403`	`{ "error": "You do not have access to this workspace." }`	You are neither the owner nor a member of the workspace.
`403`	`{ "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)." }`	You are a view-only member.
`403`	`{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }`	The API key is scoped to a different workspace.
`404`	`{ "error": "Desktop not found" }` or `{ "error": "Access denied" }`	No computer matches the id, or you are a member with write access but not the workspace owner.
`500`	`{ "error": "…" }`	The update failed, for example because another computer in the workspace already has that `name`, or the body is not valid JSON.
`503`	`{ "error": "Service temporarily unavailable. …" }`	Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay.

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Computer ID

Response

Computer details

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.

Get computer

curl --request GET \
  --url https://www.orgo.ai/api/computers/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.orgo.ai/api/computers/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": {
    "canView": true,
    "canWrite": true,
    "canManageAccess": true
  },
  "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
  },
  "name": "agent-1",
  "project_name": "production",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "status": "running",
  "url": "http://162.43.189.25:8231",
  "fly_instance_id": "a3881618",
  "created_at": "2026-04-07T10:35:00Z",
  "hostname": "www.orgo.ai",
  "connection_url": "https://www.orgo.ai/desktops/a3881618",
  "vnc_password": "a06db12a8683df96",
  "private_screens": false,
  "hardware": null
}

Overview

Support

Account

Agent accounts

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Get computer

Path parameters

Response

Status values

Example

Response

Errors

Rename a computer

Authorizations

Path Parameters

Response

​Path parameters

​Response

​Status values

​Example

​Response

​Errors

​Rename a computer

Authorizations

Path Parameters

Response

Path parameters

Response

Status values

Example

Response

Errors

Rename a computer