> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create computer
> Provision a new computer in a workspace.
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
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.
Computer name. Must be unique within the workspace. A name already in use returns `409`, and omitting the field returns `400`.
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`.
RAM in GB: `4`, `8`, `16`, `32`, or `64`. With `os: "macos"`, `12` is also accepted. `0` is treated as `4`. Any other value returns `400`. A value above your plan's per-computer ceiling is rejected with `403`, not clamped. Ignored for `os: "ios"`, which always records `4`.
vCPU: `0.5`, `1`, `2`, `4`, `8`, or `16`. `0` is treated as `1`. Any other value returns `400`. A value above your plan's per-computer ceiling is rejected with `403`, not clamped. Ignored for `os: "ios"`, which always records `1`.
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.
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.
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`.
Launch from a [template](/guides/templates/introduction)'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 clamped to your plan's per-computer ceiling 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 | 2 | 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: 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](https://orgo.ai/pricing).
## Response
Returns the created computer.
Computer identifier (UUID).
Computer name.
Parent workspace ID.
Deprecated alias for `workspace_id`, carrying the same value.
Operating system.
RAM in GB.
vCPU.
Display resolution in `WIDTHxHEIGHTxDEPTH` format.
One of `creating`, `running`, `restarting`, `updating`, `suspended`, `frozen`, `stopped`, `error`, `deleted`. A successful create returns `running`. See [Get computer](/api-reference/computers/get) for what each value means.
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.
ISO 8601 timestamp.
Stable identifier for the underlying compute instance. Use it for connection URLs and to reference the computer across restarts.
Deprecated alias for `instance_id`, carrying the same value.
Same-origin host for the computer's connection endpoints: `www.orgo.ai`.
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}`.
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` when the stored credential cannot be decrypted.
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.
Present when the host reports how it launched the computer. What the computer runs on, in the shape [Get computer](/api-reference/computers/get) returns.
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.
Present and `true` only when you asked for a `gpu` and no GPU host was available, so a CPU computer was created instead.
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
```bash cURL theme={null}
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
}'
```
```python Python theme={null}
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']}")
```
```javascript JavaScript theme={null}
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
```json theme={null}
{
"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` | `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. |
| `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, account-RAM, or per-computer ceiling is reached and an add-on would raise it. |
| `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. |
| `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. |
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.
```json theme={null}
{
"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.
## OpenAPI
````yaml POST /computers
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
paths:
/computers:
post:
tags:
- Computers
summary: Create computer
description: >-
Creates a new virtual computer in a workspace. The computer starts
automatically after creation.
operationId: createComputer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateComputerRequest'
example:
workspace_id: 550e8400-e29b-41d4-a716-446655440000
name: agent-1
os: linux
ram: 4
cpu: 1
responses:
'201':
description: Computer created
content:
application/json:
schema:
$ref: '#/components/schemas/Computer'
example:
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
'400':
description: >-
A missing or unaccepted field: no `workspace_id`, no `name`, a
`ram`/`cpu`/`os`/`gpu` value outside the accepted set, `gpu` with a
non-Linux `os` (`GPU_REQUIRES_LINUX`), a `disk_size_gb` below 1 or
above your ceiling (`disk_exceeds_quota`, with `max_disk_gb` and
`canManageCapacity`), or a malformed `template_ref`.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/QuotaError'
- $ref: '#/components/schemas/Error'
examples:
missing-workspace:
summary: No workspace
value:
error: workspace_id is required
bad-os:
summary: Unaccepted OS
value:
error: 'os must be one of: linux, windows, macos, android, ios'
gpu-os:
summary: GPU with a non-Linux OS
value:
error: GPU computers are Linux-only.
code: GPU_REQUIRES_LINUX
disk:
summary: Disk outside the ceiling
value:
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
'401':
$ref: '#/components/responses/UnauthorizedWithAccess'
'403':
description: >-
The workspace owner's plan does not fund the computer, the request
asks for Windows without a licence, or you joined through a share
link. Codes: `GUEST_RESTRICTED`, `WINDOWS_REQUIRES_SCALE`,
`UPGRADE_REQUIRED`, `VM_SLOT_ADDON`, `RAM_ADDON`, `VCPU_ADDON`,
`PER_COMPUTER_RAM_CAP`, `PER_COMPUTER_CPU_CAP`, `CHANGE_PLAN`,
`PLAN_LIMIT` (a limit of a plan negotiated with Orgo: a computer
count, a per-OS count, the RAM pool, or a per-computer RAM or vCPU
ceiling), or none for a grandfathered plan over its limit. The quota
refusals carry `canManageCapacity` and, where a plan change would
fix it, `upgradeTier`.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/QuotaError'
- $ref: '#/components/schemas/Error'
examples:
plan-limit:
summary: Plan does not fund it
value:
error: >-
Creating a computer requires a paid plan. Upgrade to
launch your first computer.
code: UPGRADE_REQUIRED
canManageCapacity: true
deal:
summary: Past a limit of a plan negotiated with Orgo
value:
error: >-
Your plan allows 3 computers, and you have 3. Delete one,
or contact us to change your plan.
code: PLAN_LIMIT
upgradeTier: enterprise
canManageCapacity: true
windows:
summary: Windows not on the plan
value:
error: >-
This needs a Windows computer. Add one under Usage, or
move to a Scale plan where Windows is included.
code: WINDOWS_REQUIRES_SCALE
upgradeTier: scale_v2
guest:
summary: Share-link guest
value:
error: Sign up to create your own workspace.
code: GUEST_RESTRICTED
'409':
description: >-
The workspace already has a computer with that name (`NAME_TAKEN`,
or `name_taken` when two creates race), or the template you named
has no finished build (`TEMPLATE_NOT_READY`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
name-taken:
summary: Name in use
value:
error: >-
A computer named "agent-1" already exists. Pick a
different name.
code: NAME_TAKEN
template:
summary: Template not built
value:
error: …
code: TEMPLATE_NOT_READY
'422':
description: No eligible host supports the requested `os`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: …
code: OS_UNAVAILABLE
'500':
description: >-
Unmapped failure, such as a database error or a body that is not
valid JSON.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: …
'503':
description: >-
The fleet could not place the computer right now. `code` is
`golden_unavailable`, `TEMPLATE_HOST_UNAVAILABLE`,
`TEMPLATE_READINESS_UNAVAILABLE`, `DEDICATED_CAPACITY_FULL`,
`FLEET_CAPACITY_FULL`, `GPU_HOST_UNAVAILABLE`, or
`BACKEND_UNAVAILABLE`. The capacity and readiness codes carry
`retryable: true`. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/BackendError'
example:
error: …
code: FLEET_CAPACITY_FULL
retryable: true
components:
schemas:
CreateComputerRequest:
type: object
required:
- workspace_id
- name
properties:
workspace_id:
type: string
description: ID of the workspace to create the computer in
example: 550e8400-e29b-41d4-a716-446655440000
name:
type: string
description: Computer name
minLength: 1
example: agent-1
os:
type: string
enum:
- linux
- windows
- macos
- android
- ios
default: linux
description: >-
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`.
cpu:
type: number
enum:
- 0.5
- 1
- 2
- 4
- 8
- 16
default: 1
description: >-
vCPU cores. Omitted, you get 1. Capped by the workspace owner's
plan.
ram:
type: integer
enum:
- 4
- 8
- 12
- 16
- 32
- 64
default: 4
description: >-
RAM in GB. Omitted, you get 4. `12` is accepted only with `os:
"macos"`; with any other `os` it returns `400`. Capped by the
workspace owner's plan.
disk_size_gb:
type: integer
description: >-
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:
type: string
default: 1280x720x24
description: >-
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:
type: string
enum:
- 2q
- 4q
description: >-
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`.
template_ref:
type: string
description: >-
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
Computer:
type: object
properties:
id:
type: string
description: Unique computer identifier
example: a3bb189e-8bf9-3888-9912-ace4e6543002
name:
type: string
description: Computer name
example: agent-1
workspace_id:
type: string
description: >-
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:
type: string
description: Name of the parent workspace
example: production
os:
type: string
enum:
- linux
- windows
- macos
- android
- ios
description: >-
Operating system. `ios` is a physical handset rather than a virtual
computer.
example: linux
ram:
type: integer
enum:
- 4
- 8
- 12
- 16
- 32
- 64
description: RAM in GB. `12` occurs only on macOS.
example: 4
cpu:
type: number
enum:
- 0.5
- 1
- 2
- 4
- 8
- 16
description: vCPU cores.
example: 1
status:
type: string
enum:
- creating
- running
- restarting
- updating
- suspended
- frozen
- stopped
- error
- deleted
description: Current status
example: running
url:
type: string
description: >-
Base URL of the computer's own API on the host that runs it, as
`http://:`. 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:
type: string
format: date-time
instance_id:
type: string
description: >-
Stable identifier for the underlying compute instance, returned by
`POST /computers`. Use it for connection URLs and to reference the
computer across restarts. `GET /computers/{id}` returns the same
value as `fly_instance_id`.
example: a3881618
hostname:
type: string
description: >-
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`.
example: www.orgo.ai
connection_url:
type: string
description: >-
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:
type:
- string
- 'null'
description: >-
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:
type: string
description: >-
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:
type:
- string
- 'null'
description: >-
The instance id under its legacy name. The same value `POST
/computers` returns as `instance_id`. `GET /computers/{id}` returns
only this name. `null` while the computer has no host (`frozen`).
example: a3881618
permissions:
$ref: '#/components/schemas/Permissions'
private_screens:
type: boolean
description: >-
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:
type: object
additionalProperties: true
description: >-
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:
type:
- object
- 'null'
description: >-
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.
properties:
host_cpu:
type:
- object
- 'null'
description: >-
The host's CPU, or `null` when the launch record does not name
it.
properties:
family:
type:
- string
- 'null'
name:
type:
- string
- 'null'
signature:
type:
- string
- 'null'
cpu_model:
type:
- string
- 'null'
description: '`host`, or the named CPU model the guest was given.'
hypervisor:
type:
- string
- 'null'
description: '`qemu` or `firecracker`.'
qemu:
type:
- string
- 'null'
description: The QEMU version that ran the computer.
boot:
type:
- string
- 'null'
description: How the computer last booted.
fallback:
type:
- string
- 'null'
description: >-
Set when the launch could not do what it was asked and fell
back, such as a resume that cold-booted because the CPU
differed.
launched_at:
type:
- string
- 'null'
format: date-time
launch:
type: object
additionalProperties: true
description: >-
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:
type: string
description: >-
Display resolution in `WIDTHxHEIGHTxDEPTH` format. Returned by `POST
/computers`.
example: 1280x720x24
gpu_downgraded:
type: boolean
description: >-
Returned by `POST /computers` only, present and `true` when you
asked for a `gpu` and a CPU computer was created instead.
warning:
type: string
description: Present only alongside `gpu_downgraded`, explaining the downgrade.
description: >-
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`, and `hardware`; a computer embedded in a workspace
carries the stored row. Each operation's example shows what that
operation returns.
QuotaError:
type: object
description: >-
The request was refused by the plan the workspace owner is on rather
than by ownership. See https://orgo.ai/pricing for what each plan
includes.
required:
- error
properties:
error:
type: string
code:
type: string
description: >-
Machine-readable reason. Values this API emits: `UPGRADE_REQUIRED`,
`DESKTOP_LIMIT`, `VM_SLOT_ADDON`, `RAM_ADDON`,
`PER_COMPUTER_RAM_CAP`, `VCPU_ADDON`, `PER_COMPUTER_CPU_CAP`,
`DISK_QUOTA_EXCEEDED`, `disk_exceeds_quota`,
`WINDOWS_REQUIRES_SCALE`, `GUEST_RESTRICTED`, `NOT_A_MEMBER`,
`CHANGE_PLAN`, `PLAN_LIMIT`, `upgrade_required`.
upgradeTier:
type: string
description: The plan that would allow the request.
canManageCapacity:
type: boolean
description: True when you own the workspace and can raise the limit yourself.
max_ram_gb:
type: integer
description: >-
On a RAM refusal from resize: the largest RAM a live resize can
reach for this computer.
max_disk_gb:
type: integer
description: 'On a storage refusal: the largest disk this computer may have.'
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
BackendError:
type: object
description: The fleet could not satisfy the request right now. Retry.
required:
- error
properties:
error:
type: string
code:
type: string
description: >-
`golden_unavailable`, `TEMPLATE_HOST_UNAVAILABLE`,
`TEMPLATE_READINESS_UNAVAILABLE`, `DEDICATED_CAPACITY_FULL`,
`FLEET_CAPACITY_FULL`, `GPU_HOST_UNAVAILABLE`, or
`BACKEND_UNAVAILABLE`.
retryable:
type: boolean
description: Present and `true` on the capacity failures a later retry can clear.
Permissions:
type: object
description: What your role in the workspace allows.
properties:
canView:
type: boolean
example: true
canWrite:
type: boolean
description: '`false` for a view-only member.'
example: true
canManageAccess:
type: boolean
description: Only the owner has it.
example: true
responses:
UnauthorizedWithAccess:
description: >-
No usable credential, or an access check failed. This endpoint runs its
workspace access checks during authentication, so it answers a missing
membership, view-only access, or a key scoped to another workspace with
`401`, not `403`. A server-side fault while verifying the credential
also returns `401`, with a `Service temporarily unavailable` message.
Retry that one; the key is fine.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
no-access:
summary: Not the owner or a member of the workspace
value:
error: You do not have access to this workspace.
view-only:
summary: View-only member, and the request changes something
value:
error: >-
This workspace is view-only. Ask the owner for write access
(workspace_read_only).
scope-mismatch:
summary: The API key is scoped to another workspace
value:
error: >-
This API key cannot access this workspace
(workspace_scope_mismatch).
service-unavailable:
summary: Server-side fault while verifying the credential. Retry.
value:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.