> ## 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 virtual computer in a workspace.
Creates a new virtual computer in a workspace. The computer starts automatically after creation.
Computers boot in under 500ms and come pre-configured with a desktop environment, browser, and common tools.
## Request
ID of the workspace to create the computer in.
Computer name. Must be unique within the workspace.
Operating system. Currently only `linux` is supported.
RAM in GB: `4`, `8`, `16`, `32`, or `64`. Capped by your plan's per-computer limit.
CPU cores: `1`, `2`, `4`, `8`, or `16`. Capped by your plan's per-computer limit.
Disk size in GB. Defaults to 8 GB. Capped by your plan's per-computer limit.
Display resolution in `WIDTHxHEIGHTxDEPTH` format (e.g., `1024x768x24`, `1920x1080x24`).
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` — 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`.
### Common configurations
| RAM | CPU | Best for |
| ----- | -------- | ----------------------------------- |
| 4 GB | 1 core | Standard workflows (default) |
| 8 GB | 2 cores | Heavier automation |
| 16 GB | 4 cores | Development, memory-intensive tasks |
| 32 GB | 8 cores | Large-scale processing |
| 64 GB | 16 cores | Enterprise workloads |
Maximum CPU/RAM per computer is capped by your plan. See [https://orgo.ai/pricing](https://orgo.ai/pricing).
## Response
Returns the created computer object.
Unique computer identifier.
Computer name.
Parent workspace ID.
Operating system.
RAM in GB.
CPU cores.
Display resolution in `WIDTHxHEIGHTxDEPTH` format.
One of `creating`, `starting`, `running`, `stopping`, `stopped`, `restarting`, `deleting`, `error`.
URL to view the computer in the dashboard.
ISO 8601 timestamp.
Stable identifier for the underlying compute instance. Use this to construct the `hostname` and to reference the VM across restarts.
Same-origin host for the computer's connection endpoints. Always `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}`.
VNC / Bearer token for the computer's WebSocket APIs (VNC, terminal, bash, audio, events). **Rotates on every restart** - do not persist across restarts; use a fresh value from the latest `POST /computers` or `GET /computers/{id}`.
**Fast path: 1 API call.** The response above contains everything needed to connect - no follow-up `GET /computers/{id}` or `GET /computers/{id}/vnc-password` is required. Just poll `https://www.orgo.ai/api/desktops/{instance_id}/proxy/health` until it returns 200 (\~300 ms with golden snapshots), then connect.
## Example
```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": "550e8400-e29b-41d4-a716-446655440000",
"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"URL: {computer['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(`URL: ${computer.url}`);
```
### Response
```json theme={null}
{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"name": "agent-1",
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"os": "linux",
"ram": 4,
"cpu": 1,
"resolution": "1280x720x24",
"status": "running",
"url": "https://orgo.ai/workspaces/550e8400-e29b-41d4-a716-446655440000/computers/a3bb189e-8bf9-3888-9912-ace4e6543002",
"created_at": "2026-04-07T10:35:00Z",
"instance_id": "a3881618",
"hostname": "www.orgo.ai",
"connection_url": "https://www.orgo.ai/desktops/a3881618",
"vnc_password": "a06db12a8683df96"
}
```
## 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: 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: Streaming
description: Stream computer display via RTMP
- 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
os: linux
ram: 4
cpu: 1
status: running
url: >-
https://orgo.ai/workspaces/a3bb189e-8bf9-3888-9912-ace4e6543002
created_at: '2026-04-07T10:35:00Z'
instance_id: a3881618
hostname: www.orgo.ai
connection_url: https://www.orgo.ai/desktops/a3881618
vnc_password: a06db12a8683df96
'400':
description: Invalid configuration or quota exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Workspace not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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
default: linux
description: Operating system
cpu:
type: integer
enum:
- 1
- 2
- 4
- 8
- 16
default: 1
description: CPU cores. Capped by plan.
ram:
type: integer
enum:
- 4
- 8
- 16
- 32
- 64
default: 4
description: RAM in GB. Capped by plan.
disk_size_gb:
type: integer
default: 8
description: Disk size in GB. Capped by plan.
resolution:
type: string
default: 1280x720x24
description: Display resolution in WIDTHxHEIGHTxDEPTH format
example: 1280x720x24
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
project_name:
type: string
description: Name of the parent workspace
example: production
os:
type: string
enum:
- linux
description: Operating system
example: linux
ram:
type: integer
enum:
- 4
- 8
- 16
- 32
- 64
description: RAM in GB
example: 4
cpu:
type: integer
enum:
- 1
- 2
- 4
- 8
- 16
description: CPU cores
example: 1
disk_size_gb:
type: integer
description: Disk size in GB
example: 8
status:
type: string
enum:
- creating
- starting
- running
- stopping
- stopped
- restarting
- deleting
- error
description: Current status
example: running
url:
type: string
description: Dashboard URL for the computer
example: https://orgo.ai/workspaces/a3bb189e-8bf9-3888-9912-ace4e6543002
created_at:
type: string
format: date-time
instance_id:
type: string
description: >-
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:
type: string
description: >-
Same-origin host for the computer's connection endpoints (always
`www.orgo.ai`).
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
description: >-
VNC / WebSocket Bearer token. Rotates on every restart - do not
persist across restarts.
example: a06db12a8683df96
Error:
type: object
properties:
error:
type: string
description: Error message
responses:
Unauthorized:
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Invalid API key
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````