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",
  "name": "agent-1",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_name": "production",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "status": "running",
  "url": "http://198.51.100.24:8081",
  "created_at": "2023-11-07T05:31:56Z",
  "instance_id": "a3881618",
  "hostname": "www.orgo.ai",
  "connection_url": "https://www.orgo.ai/desktops/a3881618",
  "vnc_password": "a06db12a8683df96"
}

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

Name of the parent workspace.

string

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

integer

RAM in GB.

number

vCPU. Fractional for 0.5 vCPU computers.

string

One of creating, running, restarting, updating, suspended, frozen, stopped, 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

Stable identifier for the underlying compute instance. It is the same value POST /computers returns as instance_id. Use it to build connection_url and to reference the computer across restarts. null while the computer has no host (frozen). 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.

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.

string

Current VNC / WebSocket token. Rotates on restart, on start, and on a RAM resize. null when the stored credential cannot be decrypted.

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.
`suspended`	Paused on its host. It resumes on interaction, not through start.
`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.
`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",
  "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"
}

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.
`403`	`{ "error": "Access denied" }`	You are neither the owner nor a member of the computer’s workspace.
`404`	`{ "error": "Desktop not found" }`	No computer matches the id.
`500`	`{ "error": "…" }`	Lookup failed.

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 member 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.
`403`	`{ "error": "Access denied" }`	You are neither the owner nor a member of the workspace.
`404`	`{ "error": "Desktop not found" }` or `{ "error": "Access denied" }`	No computer matches the id, or you are a member but not the workspace owner.
`500`	`{ "error": "…" }`	The update failed.

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

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"

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"

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",
  "name": "agent-1",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_name": "production",
  "os": "linux",
  "ram": 4,
  "cpu": 1,
  "status": "running",
  "url": "http://198.51.100.24:8081",
  "created_at": "2023-11-07T05:31:56Z",
  "instance_id": "a3881618",
  "hostname": "www.orgo.ai",
  "connection_url": "https://www.orgo.ai/desktops/a3881618",
  "vnc_password": "a06db12a8683df96"
}

Overview

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