# Cloud Computer AI — full API notes

> Shapes below are taken from server/index.js, server/computer-lifecycle.js, server/computer-record.js, and server/credits.js. Paths are relative to the console origin. This file does not contain secrets.

## Views and flags

Human canvas: GET /app (also /console, /workspace, /canvas, /computers, /new) serves public/app.html.

Agent view: GET /agent and GET /agent/* serve public/agent.html only when the process environment variable AGENT_VIEW_ENABLED is the string `1`. Otherwise the server responds 302 to /app.

GET /api/flags is public and does not require a session.

Request: none.

Response:

```json
{
  "agentView": false,
  "a11yFocusSafe": false,
  "mcp": false,
  "ownerLock": false,
  "desktopFrameA11y": false,
  "a11yP2CanvasAlt": false,
  "desktopOcr": false,
  "canvasListView": false,
  "composeServices": false
}
```

`agentView` is true only when AGENT_VIEW_ENABLED=1. `a11yFocusSafe` is true only when A11Y_P3_FOCUS_SAFE=1. `mcp` is true only when MCP_ENABLED=1. `ownerLock` is OWNER_LOCK_ENABLED=1. `desktopFrameA11y` is DESKTOP_FRAME_A11Y=1. `a11yP2CanvasAlt` is A11Y_P2_CANVAS_ALT=1. `desktopOcr` is DESKTOP_OCR_ENABLED=1. `canvasListView` is CANVAS_LIST_VIEW=1. `composeServices` is true only when COMPOSE_SERVICES_ENABLED=1. Each defaults to false.

These documents are always served, with or without the flag:

- GET /llms.txt
- GET /llms-full.txt
- GET /.well-known/ccai-actions.json (file public/ccai-actions.json)
- GET /agent-api.html
- GET /openapi.json (file public/openapi.json)

Agent view hash routes: #computers, #launch, #templates, #backups, #billing, #settings, #api, #activity, #help, #desktop/{id}.

The computers table polls GET /api/computers every 5 seconds and patches rows in place. It updates the status cell text when the status string changes. It does not rebuild the table and does not move focus because of a poll.

## Auth

Protected /api routes use server requireAuth.

When Clerk is not configured, or CLERK_AUTH_DISABLED is `1` or `true`, the server sets a dev user and does not require a bearer token.

Otherwise send:

```
Authorization: Bearer <clerk-session-jwt>
```

The browser console gets that JWT from `await window.OpenPCAuth.getToken()`. A missing or invalid token returns:

```json
{ "error": "Sign in required", "code": "unauthenticated" }
```

or:

```json
{ "error": "Invalid or expired session", "code": "invalid_token" }
```

POST /api/api-keys (session required) creates a key. Body `{ "name": "key" }`. Response 201:

```json
{
  "key": { "id": "k_abc123", "name": "key", "prefix": "opc_live_abcd••••wxyz", "created": "2026-10-21" },
  "secret": "<returned-once>"
}
```

The secret is not stored in later responses. GET /api/workspace maps keys with the secret removed: `{ id, name, prefix, created }`.

DELETE /api/api-keys/{id} returns `{ "ok": true }`.

requireAuth verifies the Clerk session JWT. It does not look up opc_live keys. Create and read keys through the session. The human canvas Settings → API keys screen is where a person reveals a new secret.

When MCP_ENABLED=1, a bearer token that starts with `ccai_pat_` is verified as a personal access token. The store keeps sha256 only. requireAuth then sets `{ userId, sessionId: null, orgId: null, bypass: false, viaPat: true, patId }`. An unknown, revoked, or expired token is 401. Token management routes reject `viaPat` with 403. Create a token from a Clerk session:

POST /api/tokens

```json
{ "name": "laptop", "expiresDays": 30 }
```

Response 201. `token` is returned once and is not stored:

```json
{
  "token": "ccai_pat_…",
  "pat": { "id": "pat_…", "name": "laptop", "prefix": "ccai_pat_abcd…wxyz", "createdAt": "2026-10-22T00:00:00.000Z", "lastUsedAt": null, "revokedAt": null, "expiresAt": null }
}
```

GET /api/tokens returns `{ tokens }` without hashes. DELETE /api/tokens/{id} returns `{ "ok": true }`. Omit `expiresDays` for no expiry.

## Computer record

List and get return records shaped by createComputerRecord, plus later fields the provisioner sets (hostname, host, streamUrl, lines, error, backup, provisioning). Railway computers also gain deadline fields from withDeadlines.

Typical fields:

```json
{
  "id": "c_ab12cd34",
  "name": "Ubuntu XFCE",
  "status": "starting",
  "templateId": "t_blank",
  "templateName": "Ubuntu XFCE",
  "provider": "proxmox",
  "hostname": null,
  "externalId": null,
  "sandboxId": null,
  "streamUrl": null,
  "os": "Linux",
  "vcpu": 1,
  "memoryMb": 4096,
  "diskGb": 40,
  "createdAt": "2026-10-21T12:00:00.000Z",
  "error": null,
  "lines": ["$ provisioning…"]
}
```

`status` is one of `starting`, `running`, `stopped`, `error`.

## GET /api/computers

Response:

```json
{ "computers": [ { "id": "c_ab12cd34", "name": "Ubuntu XFCE", "status": "running" } ] }
```

The list is limited to the signed-in user, with the same shared-computer exceptions the console already applies.

## POST /api/computers

Body fields read by the route: `name`, `templateId`, `x`, `y`, `provider`, `vcpu`, `memoryMb`, `diskGb`, `plan`, `ttlHours`, `size`, `disclosureAck`.

`size` is a SKU. `small` is 1 vCPU and 4096 MB. `medium` is 2 vCPU and 8192 MB. The agent view sends `size: "small"` together with `vcpu: 1` and `memoryMb: 4096` for ordinary desktops, and `vcpu: 0`, `memoryMb: 0`, `ttlHours: null` for docker-style templates (n8n, WordPress, React CMS, vscode server, saved prompts, Railway, Backup Cloudflare).

Template ids come from GET /api/workspace `templates[].id`. Examples in the default catalog include `t_blank`, `t_claude`, `t_lubuntu`, `t_debian_trixie`, `t_grok_bot_omarchy`, `t_n8n`, `t_backup_cloudflare`, `t_railway_free_vm`.

Railway (`t_railway_free_vm`) requires `disclosureAck: true` or the server returns 400 `railway_ack_required`.

Success is 201:

```json
{ "computer": { "id": "c_ab12cd34", "name": "Ubuntu XFCE", "status": "starting" } }
```

Errors use `{ "error", "code?" }`.

## GET /api/computers/{id}

```json
{ "computer": { "id": "c_ab12cd34" } }
```

404 `{ "error": "not found" }` when the id is missing or not visible to the user.

## POST /api/computers/{id}/start

No body required. Response `{ "computer": { "id": "c_ab12cd34", "status": "running" } }`.

## POST /api/computers/{id}/stop

No body required. Response `{ "computer": { "id": "c_ab12cd34", "status": "stopped" } }`.

## DELETE /api/computers/{id}

No body required for a normal computer. Response:

```json
{ "ok": true, "id": "c_ab12cd34" }
```

This is destructive. Confirm the computer name and id with the user before calling it. The agent view opens `dialog#confirmDialog`, names the computer, focuses Cancel, and only sends DELETE if the confirm button (`[data-testid="confirm-delete"]`) is used. Cancel and Escape return focus to the button that opened the dialog.

Docker n8n computers can also require an admin password (`body.adminPassword` or header `x-ccai-admin-password`). A wrong password returns 403 and deletes nothing. The agent view surfaces that error and does not invent a password.

## GET /api/computers/{id}/screenshot

Response from computerLifecycle.screenshot:

```json
{ "pngBase64": "<base64-png-bytes-without-a-data-url-prefix>" }
```

The agent view renders `data:image/png;base64,` plus `pngBase64`, and sets the image alt text to `Screenshot of <name> desktop taken at <time>`.

## GET /api/computers/{id}/screen-text

Enabled only when DESKTOP_OCR_ENABLED=1. Otherwise 404 `{ "error": "not found" }`. Visibility matches screenshot (`findComputerForUser`): shared computers can be read. The handler screenshots, then runs `tesseract stdin stdout` (15s timeout, images larger than 10MB are rejected). The result is cached in memory for 60 seconds per computer id and sha1 of the image, up to 200 entries.

```json
{ "text": "Hello", "cachedAt": "2026-10-22T00:00:00.000Z", "engine": "tesseract" }
```

If the `tesseract` binary is missing the status is 501:

```json
{ "error": "tesseract is not installed", "code": "ocr_unavailable" }
```

The MCP tool `screen_text` `{ id }` is listed only when DESKTOP_OCR_ENABLED=1. Its annotation `readOnlyHint` is true.

## Composable services

Enabled only when COMPOSE_SERVICES_ENABLED=1. Otherwise every route below returns 404 `{ "error": "services disabled" }`. MCP tools `list_services` and `add_service` are omitted from tools/list when the flag is off. The human canvas and agent view hide the service UI when `composeServices` is false.

POST /api/computers accepts optional `services` (catalog ids). They are queued after the computer status is `running`. Unknown ids do not fail launch. The 201 body stays `{ "computer" }`.

### GET /api/services

```json
{ "services": [{ "id": "docker", "name": "Docker", "icon": "🐳", "description": "…", "dependsOn": [], "ports": [], "url": null }] }
```

Catalog ids: `docker`, `wordpress` (depends on docker, port 8080), `n8n` (depends on docker, port 5678), `grok_cli` (Grok Build CLI, no dependencies). Install scripts are not returned. Database passwords are generated in the guest and are not printed.

### GET /api/computers/{id}/services

```json
{ "services": [{ "id": "docker", "name": "Docker", "status": "queued", "ports": [], "addedAt": "2026-10-22T00:00:00.000Z", "healthAt": null, "error": null, "dependsOn": [] }] }
```

`status` is `queued`, `installing`, `healthy`, or `failed`.

### POST /api/computers/{id}/services

```json
{ "serviceId": "wordpress" }
```

202 `{ "computer", "services" }`. Dependencies are queued first. 400 `{ "error": "unknown service" }` for an unknown id. 409 when the computer is not running.

### POST /api/computers/{id}/services/{sid}/health

Re-runs the health check for a service that was already added. 404 when it was not added. 409 when the computer is not running. Response `{ "services" }`.

## PATCH /api/computers/{id}

```json
{ "name": "Optional name", "x": 120, "y": 80 }
```

`x` and `y` are the canvas position on the shared computer record. Drag, Move…, Alt+Arrow (40px), and Auto-arrange all PATCH these fields. There is no per-user layout and no `move_computer` MCP tool. When OWNER_LOCK_ENABLED=1 this PATCH, including a body that only has `x` and `y`, returns 403 `not_owner` for a non-owner.

## POST /api/computers/{id}/click

Body is passed to computerLifecycle.click:

```json
{ "x": 100, "y": 200, "button": "left" }
```

`button` is `left`, `middle`, or `right` (default `left`). `double: true` double-clicks. `move: true` moves without clicking. If `x` or `y` is omitted, normalized `nx` and `ny` (0 to 1) are mapped onto a 1280×800 desktop. Missing coordinates return 400 `click needs x and y, or nx and ny`.

Response:

```json
{ "success": true, "action": "click" }
```

`action` is `double_click` when `double` is true.

## POST /api/computers/{id}/type

```json
{ "text": "hello" }
```

Text is capped at 2000 characters. Response `{ "success": true, "action": "type" }`.

## POST /api/computers/{id}/key

```json
{ "key": "ctrl+c" }
```

The key string is restricted to letters, digits, `+`, `_`, and `-`. Default when empty on the server is `Return`. Response `{ "success": true, "action": "key" }`.

## POST /api/computers/{id}/scroll

```json
{ "direction": "down", "amount": 3 }
```

`direction` is `up` or `down` (anything other than `up` is down). `amount` is clamped to 1..20 (default 3). The agent view's dx/dy form converts dy: negative becomes `up`, positive becomes `down`, and amount is the rounded absolute value of dy (or of dx when dy is 0).

Response `{ "success": true, "action": "scroll" }`.

## POST /api/computers/{id}/bash

```json
{ "command": "uname -a", "timeoutMs": 60000 }
```

`cmd` is an alias of `command`. Missing command returns 400 `command required`. The handler calls computerLifecycle.exec and returns that result. The usual shape is:

```json
{ "exitCode": 0, "stdout": "Linux\n", "stderr": "" }
```

Some guests have no shell (n8n, WordPress, React CMS, Penpot, Inkbox, Railway, Composio, vscode server, Backup Cloudflare, saved prompts) and return 400 with an error string. The agent view prints stdout, stderr, and exit code in `pre#bashOutput`.

POST /api/computers/{id}/exec is the same exec path and requires `cmd` or `command`.

## GET /api/computers/{id}/backup-status

Only Backup Cloudflare computers (`provider` `restic` or template `t_backup_cloudflare`). Others return 404 `not a backup computer`.

```json
{
  "id": "c_backup",
  "name": "Backup Cloudflare",
  "host": "pve",
  "backup": {
    "ok": true,
    "frequency": "daily",
    "date": "2026-10-21",
    "size": "1G",
    "snapshotCount": 2,
    "lastJob": "ok",
    "error": null
  }
}
```

The agent view calls this once per computer and shows 404 as "not a backup computer" without treating it as a page error.

## POST /api/computers/{id}/stream

No body required. Response depends on the provider. Desktop providers return a stream URL and sometimes a VNC password:

```json
{ "streamUrl": "https://example.invalid/vnc.html", "externalId": null, "sandboxId": null, "password": null }
```

GET /api/computers/{id}/vnc-password returns `{ password, streamUrl }` from the same stream helper. The agent view links to the human canvas (`/app?view=human`) for the interactive noVNC session instead of embedding it.

## GET /api/workspace

```json
{
  "workspace": { "name": "Workspace" },
  "profile": {},
  "members": [],
  "templates": [{ "id": "t_blank", "name": "Ubuntu XFCE", "desc": "Ubuntu with XFCE.", "icon": "▣" }],
  "usage": {
    "computers": [1, 5],
    "ram": [2, 8],
    "storage": [4, 20],
    "vcpu": [0.5, 2],
    "hours": 0
  },
  "apiKeys": [{ "id": "k_abc123", "name": "key", "prefix": "opc_live_abcd••••wxyz", "created": "2026-10-21" }],
  "secrets": [],
  "e2bConfigured": "per_user"
}
```

Usage pairs are `[used, max]`. The agent billing page is read-only.

## GET /api/credits/balance

Session required (`req.auth.userId`).

```json
{ "usd": 0, "updatedAt": null, "packs": [10, 25, 50, 100] }
```

POST /api/credits/checkout body `{ "amount": 10 }` starts a Stripe checkout. The agent view does not call it.

## MCP

GET /api/mcp:

```json
{ "name": "openpc", "version": "0.1.0", "protocol": "openpc-mcp-http/0.1", "tools": [] }
```

POST /api/mcp body:

```json
{ "tool": "list_computers", "arguments": {} }
```

`name` may be sent instead of `tool`.

- `list_computers` → `{ computers: [{ id, name, status, templateId, sandboxId, streamUrl, ownerUserId }] }`
- `tools/list` → `{ tools }`
- `get_computer` arguments `{ id }` → `{ computer }`
- `exec` arguments `{ id, cmd, timeoutMs? }` → exec result
- `create_computer` arguments `{ name, templateId, provider, vcpu, memoryMb, diskGb }` → `{ computer }`

The legacy `/api/mcp` routes are unchanged.

## MCP server

Enabled only when MCP_ENABLED=1. Mounted at POST /mcp before requireAuth. The handler authenticates itself, then tools call the REST routes at `http://127.0.0.1:${PORT}` with the same Authorization header so ownership, credit, and capacity checks stay in the REST handlers.

URL: `https://app.cloudcomputerai.com/mcp`

Protocol versions: `2025-06-18`, `2025-03-26`, `2024-11-05`. initialize negotiates the client version when it is one of those, otherwise `2025-06-18`. capabilities are `{ "tools": {} }`. serverInfo is `{ "name": "cloudcomputerai", "version": "1.0.0" }`.

POST body is one JSON-RPC 2.0 object or a batch. Response content type is `application/json`. `notifications/*` returns 202 and no body. ping returns `{}`. Unknown methods return JSON-RPC `-32601`. GET /mcp and DELETE /mcp return 405.

Missing or invalid auth is HTTP 401:

`WWW-Authenticate: Bearer realm="cloudcomputerai", resource_metadata="https://app.cloudcomputerai.com/.well-known/oauth-protected-resource"`

GET `/.well-known/oauth-protected-resource` (only when MCP is enabled):

```json
{ "resource": "https://app.cloudcomputerai.com/mcp", "bearer_methods_supported": ["header"] }
```

If the Origin header is present it must be `https://app.cloudcomputerai.com`, `https://cloudcomputerai.com`, `http://localhost:*`, or `http://127.0.0.1:*`. Anything else is 403. A missing Origin is allowed.

Create the bearer token in human canvas Settings → Personal access tokens, or /agent → API & tokens. Header: `Authorization: Bearer ccai_pat_…`. A Clerk session JWT is also accepted on /mcp.

Tools:

- list_computers → GET /api/computers
- get_computer `{ id }` → GET /api/computers/{id}
- list_templates → GET /api/workspace, result `{ templates }`
- launch_computer `{ templateId, name? }` → POST /api/computers
- start_computer `{ id }` → POST /api/computers/{id}/start
- stop_computer `{ id }` → POST /api/computers/{id}/stop
- screenshot_computer `{ id }` → GET /api/computers/{id}/screenshot. Image bytes or a data URL become MCP image content (base64). Other results are text.
- delete_computer `{ id, confirm }` → DELETE /api/computers/{id} only when confirm equals exactly `DELETE <id>`. Otherwise the tool result has isError true and no REST call is made.
- click_computer `{ id, x, y, button? }` → POST /api/computers/{id}/click
- type_text `{ id, text }` → POST /api/computers/{id}/type
- press_key `{ id, key }` → POST /api/computers/{id}/key
- scroll `{ id, direction, amount? }` → POST /api/computers/{id}/scroll
- screen_text `{ id }` → GET /api/computers/{id}/screen-text when DESKTOP_OCR_ENABLED=1. readOnlyHint true. Omitted from tools/list when the flag is off.
- list_services `{ id? }` → GET /api/services, or GET /api/computers/{id}/services when id is set. Listed only when COMPOSE_SERVICES_ENABLED=1. readOnlyHint true.
- add_service `{ id, serviceId }` → POST /api/computers/{id}/services. Listed only when COMPOSE_SERVICES_ENABLED=1. Dependencies install first.

Tool results use `content: [{ "type": "text", "text": "<json>" }]` plus `structuredContent`. REST non-2xx sets `isError` true and puts the error text in content. A 403 `{ "error": "Only the owner or an admin can control this computer", "code": "not_owner" }` is surfaced as that error string with `isError: true`. Annotations include readOnlyHint, destructiveHint, and idempotentHint. delete_computer is destructive.

There is no `move_computer` tool. Positions are PATCH /api/computers/{id} `{ x, y }` on the shared computer record, and OWNER_LOCK applies to that update.

## Owner lock

When OWNER_LOCK_ENABLED=1, `requireComputerControl` runs after `findComputerForUser` and before any side effect on POST stop, start, click, type, key, scroll, exec, bash, ensure-template, railway, backup-restore, PATCH /api/computers/{id}, and DELETE /api/computers/{id}. Allowed when `req.auth.bypass`, or `computer.ownerUserId === req.auth.userId`, or the caller is a platform admin. Otherwise:

```json
{ "error": "Only the owner or an admin can control this computer", "code": "not_owner" }
```

HTTP 403. Screenshot, screen text, stream, and list stay available for shared computers.

## Retry-After

Every HTTP 429 from the API sets `Retry-After` (seconds) and includes the same number as `retryAfter` in the JSON body. `railway_daily_cap` is 3600. `railway_active_cap` is 300. Any other 429 is 60. This is always on.

Claude Code:

`claude mcp add --transport http cloudcomputerai https://app.cloudcomputerai.com/mcp --header "Authorization: Bearer ccai_pat_..."`

Claude Desktop `claude_desktop_config.json`:

```json
{"mcpServers":{"cloudcomputerai":{"command":"npx","args":["-y","mcp-remote","https://app.cloudcomputerai.com/mcp","--header","Authorization:${CCAI_TOKEN}"],"env":{"CCAI_TOKEN":"Bearer ccai_pat_..."}}}}
```

Cursor `~/.cursor/mcp.json`:

```json
{"mcpServers":{"cloudcomputerai":{"url":"https://app.cloudcomputerai.com/mcp","headers":{"Authorization":"Bearer ccai_pat_..."}}}}
```

Grok and any other streamable HTTP MCP client use the same URL and Authorization header.

OpenAPI 3.1 for these REST routes: GET /openapi.json.

## Errors

Failed routes respond with `{ "error": "message", "code": "optional_code" }` and an HTTP status from the handler (400, 401, 403, 404, 409, 429, 500, 501, 502, 503, 504). 403 `not_owner` means OWNER_LOCK_ENABLED blocked control. 429 includes `Retry-After` and `retryAfter`. 501 `ocr_unavailable` means screen text was requested and tesseract is not installed.

## Supabase

GET /api/integrations/supabase (signed in) returns JSON:

`{ "name": "Supabase", "pin": "v1.26.08", "studioUrl": "https://app.cloudcomputerai.com/supabase/", "apiUrl": "http://127.0.0.1:8000", "healthPath": "/auth/v1/health", "keysFile": "/opt/supabase-platform/.env", "publishableKey": "configured", "serviceRole": "server-only", "volume": "/opt/supabase-platform/volumes/db/data", "health": "ok", "checkedAt": "<iso>" }`

`volume` is the Postgres bind mount on gex44-apps. It is not a Docker named volume. `health` is `down` when the host status file is missing or older than three minutes, or when Auth health was not HTTP 200. The host check sends the anon key and does not write it into the status file. The response never includes the publishable key, the service-role key, the Postgres password, or the Studio password.

POST /api/computers with `templateId` `t_supabase` clones Proxmox VM 9014 unless `PROXMOX_TEMPLATE_VMID_SUPABASE` is set. Minimum size is 2 vCPU and 8192 MB. The guest install script is pinned to Supabase `v1.26.08`.

## Safety

- DELETE is destructive and requires an explicit user confirmation that names the computer.
- Do not embed session tokens, API key secrets, VNC passwords, or admin passwords in documents, status text, or screenshots' alt text.
- Pointer, keyboard, and bash actions affect the live guest. Treat them as user-requested only.