# Orgo API

> Launch cloud computers that AI agents can control and interact with. Every computer is a full Linux desktop with a browser, reachable over HTTP and VNC. Boots in under 500 ms and runs continuously.

Common use cases:
- Drive a computer with a model provider (Anthropic, OpenAI, Google, or any OpenAI-compatible model). Useful for automating data entry, combining several tools into one interface, or driving software that doesn't expose an API.
- Install an agent like OpenClaw or Hermes Agent inside the computer for a 24/7 runtime.
- Run developer CLIs like Claude Code or Codex on a computer that stays online across sessions.

What Orgo is not:
- Not a browser (Browserbase et al. give a tab; Orgo gives a full computer — browse, save files, run code, install desktop apps).
- Not an AI agent (Orgo provides the computer; bring Claude Computer Use, OpenAI's CUA, Hermes Agent, OpenClaw, or your own loop).
- Not a general cloud platform (Orgo runs one thing: persistent desktops for AI agents, with sub-second boots and an API shaped around computer use).

## Base URL

https://www.orgo.ai/api

## Authentication

All requests require a Bearer token:

```
Authorization: Bearer sk_live_...
```

Get a key at https://www.orgo.ai/start.

API keys have two scopes:
- **Account-wide** (default): can access every workspace you own.
- **Workspace-scoped**: locked to one workspace; 403 on anything else. Use for CI or third-party integrations.

Pick the scope when creating a key in workspace settings. A 403 with `code: "workspace_scope_mismatch"` means a scoped key was used on the wrong workspace.

## Workspaces

- `POST /workspaces`        Create a workspace.
- `GET /workspaces`         List workspaces.
- `GET /workspaces/{id}`    Get workspace by ID.
- `DELETE /workspaces/{id}` Delete workspace.

`/projects` continues to work as a deprecated alias for `/workspaces`.

## Computers

### CRUD

- `POST /computers` - Create a computer.
  - Required: `workspace_id`, `name`.
  - Optional: `os` (linux), `ram` (4/8/16/32/64), `cpu` (1/2/4/8/16), `disk_size_gb`, `resolution` (default `1280x720x24`), `auto_stop_minutes`.
- `GET /computers/{id}`    Get computer.
- `DELETE /computers/{id}` Delete computer.
- `GET /computers/{id}/vnc-password` Get VNC password.

### Lifecycle

- `POST /computers/{id}/start`   Start.
- `POST /computers/{id}/stop`    Stop.
- `POST /computers/{id}/restart` Restart.
- `GET /computers/{id}/auto-stop`   Get auto-stop setting (`auto_stop_minutes`, `configurable`).
- `PATCH /computers/{id}/auto-stop` Update auto-stop (`auto_stop_minutes`, `0` to disable).

### Management

- `POST /computers/{id}/clone`   Clone an existing computer (preserves disk state).
- `PATCH /computers/{id}/resize` Live-resize CPU, RAM, disk, or bandwidth.
  - Optional: `vcpus`, `mem_gb`, `disk_size_gb` (grow only), `bandwidth_limit_mbps`.
- `PATCH /computers/{id}/move`   Move to a different workspace.
  - Required: `workspace_id` (target). `project_id` is accepted as a deprecated alias.

### Status values

`creating`, `starting`, `running`, `stopping`, `stopped`, `suspended`, `restarting`, `deleting`, `error`.

`suspended` indicates a plan downgrade put the computer over the per-account limit. Upgrade or delete other computers to resume it.

### Identifiers

Every computer returns `instance_id`, a stable identifier for the underlying VM. `fly_instance_id` is returned as a deprecated alias for backwards compatibility.

## Actions

- `GET /computers/{id}/screenshot` Returns base64 PNG.
- `POST /computers/{id}/click`     Required: `x`, `y`. Optional: `button` (left/right), `double` (boolean).
- `POST /computers/{id}/drag`      Required: `start_x`, `start_y`, `end_x`, `end_y`. Optional: `button`, `duration`.
- `POST /computers/{id}/type`      Required: `text`.
- `POST /computers/{id}/key`       Required: `key` (e.g. `Enter`, `Tab`, `ctrl+c`).
- `POST /computers/{id}/scroll`    Required: `direction` (up/down). Optional: `amount` (default 3).
- `POST /computers/{id}/wait`      Required: `seconds` (0-60). `duration` is accepted as a deprecated alias.
- `POST /computers/{id}/bash`      Required: `command`.
- `POST /computers/{id}/exec`      Required: `code` (Python). Optional: `timeout`.

## WebSocket APIs

- **Terminal**: `wss://www.orgo.ai/desktops/{instance_id}/ws/terminal?token={password}&cols=80&rows=24`
  - Client to server: input, resize, ping.
  - Server to client: output, exit, pong, error.

- **Audio**: `wss://www.orgo.ai/desktops/{instance_id}/ws/audio?token={password}`
  - PCM s16le 24kHz mono, 20ms frames (~48 KB/s).

- **Events**: `wss://www.orgo.ai/desktops/{instance_id}/ws/events?token={password}`
  - Subscribe: `{"type": "subscribe", "event_types": [...]}`.
  - Types: window_focus, window_open, window_close, clipboard, file_change, screen_change, audio_stream_start, audio_stream_stop, process_start, process_stop, idle, active.

## Streaming (RTMP)

- `POST /computers/{id}/stream/start` Required: `connection_name`.
- `GET /computers/{id}/stream/status`
- `POST /computers/{id}/stream/stop`

## Files

- `POST /files/upload`   multipart/form-data. Required: `file`, `workspaceId`. Optional: `desktopId`. `projectId` is accepted as a deprecated alias.
- `GET /files`           Required: `workspaceId`. Optional: `desktopId`.
- `POST /files/export`   Required: `desktopId`, `path`.
- `GET /files/download?id={file_id}` Returns download URL.
- `DELETE /files/delete?id={file_id}`

## Computer specs

| Param | Options | Default |
|---|---|---|
| os | linux | linux |
| cpu | 1, 2, 4, 8, 16 | 1 |
| ram | 4, 8, 16, 32, 64 GB | 4 |
| disk_size_gb | up to plan limit | 8 |

Specs are capped by your plan. See https://orgo.ai/pricing.

## Quickstart

```bash
# 1. Create workspace
curl -X POST https://www.orgo.ai/api/workspaces \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-workspace"}'

# 2. Create computer
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"}'

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

# 4. Click
curl -X POST https://www.orgo.ai/api/computers/COMPUTER_ID/click \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'
```

## CLI

```bash
# macOS / Linux: installs Node + the CLI in one step
curl -fsSL https://orgo.ai/install.sh | bash

# Or with an existing Node 20+
npm install -g orgo
```

## Claude Code skill

Drop-in Agent Skill that teaches Claude Code when to spin up an Orgo computer (browser automation, visual testing, sandboxing, long-running agent runs). Install:

```bash
mkdir -p ~/.claude/skills/computer && \
  curl -fsSL https://orgo.ai/skills/computer/SKILL.md \
    -o ~/.claude/skills/computer/SKILL.md
```

Restart Claude Code; the skill is discovered automatically. Trigger it with prompts like "spin up an orgo computer and screenshot orgo.ai" or "open chrome and click around on my dev server". Docs: https://docs.orgo.ai/guides/skill.

Then:

```bash
orgo login                              # device-code OAuth in the browser
orgo computers create                   # interactive: workspace, name, RAM, CPU
orgo ssh <name>                         # WebSocket terminal session
orgo agent --computer <name>            # multi-turn TUI agent
orgo run "<prompt>" --computer <name>   # single-shot agent run
orgo resume                             # resume a saved session (~/.orgo/sessions/)
```

Every command accepts `--json` for machine-readable output and `--help`. Sessions auto-persist. Inside `orgo agent`, slash commands: `/help`, `/computer`, `/model`, `/sessions`, `/resume`, `/compact`, `/usage`, `/screenshot`, `/save <title>`. Full docs: https://docs.orgo.ai/guides/cli.

Env vars: `ORGO_API_KEY` (skip credential file), `ORGO_API_BASE_URL` (different host), `ORGO_PROFILE` (named credential profile), `ORGO_JSON=1` (force JSON), `ORGO_NO_COLOR=1` (disable ANSI).

## SDK (Python)

```bash
pip install orgo
```

The `orgo` npm package is the CLI as of v2.0. A standalone TypeScript SDK is on the way; in the meantime, point any OpenAI SDK at `/api/v1/chat/completions` (see below) or hit the REST endpoints directly with `fetch`.

## Computer use agents (OpenAI-compatible endpoint)

`POST https://www.orgo.ai/api/v1/chat/completions` accepts any OpenAI SDK. Add a `computer_id` field on the request body and the chosen model will run a full computer-use loop on that computer.

Supported models: `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6` (default), `claude-haiku-4-5`. Dotted forms are accepted as aliases.

To use OpenAI, Google, Nous Research, or any other provider, run your own agent loop with the per-action endpoints (`/computers/{id}/screenshot`, `/click`, etc.) instead of this endpoint.

## Migrating from a VPS (DigitalOcean / Fly.io / Hetzner)

Orgo manages the host. No OS updates, firewall, VNC, fonts, TLS, monitoring, or backups to configure. Computers run continuously by default.

Five steps, same for both agents:

1. Stop the gateway on the source so sqlite flushes cleanly.
2. `tar czf state.tgz -C $HOME .hermes` (or `.openclaw`).
3. Provision an Orgo computer.
4. Upload the tarball via `POST /files/upload`, install the agent with its upstream installer, untar over the fresh skeleton.
5. Install the gateway as a systemd user service, verify with `hermes doctor` / `openclaw doctor`.

Source-specific transfer:
- DigitalOcean: standard `scp root@droplet:/tmp/state.tgz .`
- Fly.io: machines have no public SSH — use `flyctl ssh sftp get -a APP /tmp/state.tgz .` (wireguard).
- Hetzner: standard `scp root@host:/tmp/state.tgz .`
- Any platform: `curl -F file=@state.tgz` against `/files/upload` works from anywhere with network to both ends.

State directories:
- Hermes: `~/.hermes/` (`.env`, `config.yaml`, `SOUL.md`, `sessions/`, `memories/`, `skills/`, `cron/`, `hooks/`, `pairing/`, `whatsapp/`, `logs/`, `image_cache/`, `audio_cache/`).
- OpenClaw: `~/.openclaw/` (`openclaw.json`, `workspace/` with `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `skills/<name>/SKILL.md`).

What does **not** transfer in the tarball: WhatsApp / iMessage device pairings (re-scan the QR), systemd unit files (re-install with `hermes gateway install` or `openclaw onboard --install-daemon`), and any system-level cron entries.

Full playbook with copy-pasteable commands per agent and per source platform: https://docs.orgo.ai/guides/migrate

## Documentation

Full docs: https://docs.orgo.ai