#Cloud Computer API

Cloud Computer API belongs under AI, not the low-level Cloud deployment API. Web, Mobile, the community desktop, and SDKs use cloud computer objects to access files, terminal, browser, desktop, Buddies, workspace mounts, and backups.

A cloud computer may reuse Cloud deployments, namespaces, PVCs, exposures, backups, and cloud workers behind the scenes. Clients should not handle those infrastructure objects directly; Pod details, logs, pause/resume operations, and deployment internals stay in Cloud developer options.

A cloud computer represents one deployed cloud runtime environment. It is not a Buddy list item. A Buddy is the Shadow AI identity; when a Buddy is added to a cloud computer, the platform wires the internal runner runtime, connector binding, and Buddy identity into the same environment.

#Product Model

Cloud Computer
  -> files
  -> terminal
  -> browser
  -> desktop
  -> workspace mounts
  -> buddies[]
  -> backups[]
  -> developer deployment details

Clients should treat cloud computers as community objects, not raw deployments. Developer options can drill into deployments, Pods, logs, template snapshots, and costs.

#Developer Quick Start

Use this page when you are integrating cloud computers in a community surface. If you only need lower-level deployment primitives, use Cloud SaaS Runtime instead.

For local development:

pnpm dev

Then open:

• Web: /app/cloud-computers
• Community desktop: /app/space, then open the built-in Cloud Computers app
• Mobile: /(main)/cloud-computers
• API: GET /api/cloud-computers?limit=100&offset=0

Cloud computer development needs the normal Shadow space plus the Cloud worker/Kubernetes capability configured for your environment. In a lightweight dev environment without a working cluster, the UI should still render list, empty, loading, error, and repair states; runtime actions such as terminal, desktop, browser, backups, and workspace mounts will return configuration or pod errors until Cloud is available.

Common development environment knobs:

#SDK Shape

The TypeScript SDK exposes the AI cloud computer routes directly:

const computers = await client.listCloudComputers({ limit: 100 })
const computer = await client.createCloudComputer({ name: 'Studio Computer' })
await client.updateCloudComputer(computer.id, { name: 'Research Runtime' })
await client.createCloudComputerBackup(computer.id, { label: 'Before browser login' })

Browser, desktop, workspace mount, backup, and Cloud Buddy helpers are also available through client.*CloudComputer* methods. Prefer these methods in clients instead of calling /api/cloud-saas/deployments/* directly.

#Lifecycle And Status

Cloud computer cards should be written defensively because a single card summarizes several underlying resources: deployment row, Kubernetes namespace, pod, PVC, optional browser, optional desktop, optional Cloud Buddy runner, and backups.

Do not infer capabilities from status alone. Always read the capabilities object in the list/detail response.

#Authorization Model

Every route requires Shadow authentication and resolves an explicit Actor through the standard auth middleware.

OAuth/PAT scope is not sufficient on its own. The space also checks deployment owner access, space membership, Buddy ownership, workspace mount policy, backup ownership, and root path policy.

#List Cloud Computers

GET /api/cloud-computers?limit=100&offset=0

Response:

[
  {
    "id": "cc_stable-environment-id",
    "name": "Team Runtime",
    "status": "deployed",
    "agentCount": 2,
    "createdAt": "2026-06-27T00:00:00.000Z",
    "updatedAt": "2026-06-27T00:00:00.000Z",
    "lastActiveAt": "2026-06-27T00:00:00.000Z",
    "capabilities": {
      "files": true,
      "terminal": true,
      "browser": true,
      "desktop": true,
      "buddies": true,
      "backups": true
    }
  }
]

Use includeHistory=1 to include destroyed or historical deployments.

#Create And Update

POST /api/cloud-computers
Content-Type: application/json

{
  "name": "My Cloud Computer"
}

Create selects a deployable cloud computer template and runs the same validated Cloud SaaS deployment pipeline. Template, namespace, and resource tier are internal details.

PATCH /api/cloud-computers/:id
Content-Type: application/json

{
  "name": "Studio Computer"
}

Update currently changes the display name. It updates the underlying Cloud deployment row and does not create a separate Cloud Computer record.

#Files

GET    /api/cloud-computers/:id/files/tree
GET    /api/cloud-computers/:id/files/stats
GET    /api/cloud-computers/:id/files/files/search?searchText=app
POST   /api/cloud-computers/:id/files/folders
PATCH  /api/cloud-computers/:id/files/folders/:folderId
DELETE /api/cloud-computers/:id/files/folders/:folderId
POST   /api/cloud-computers/:id/files/files
GET    /api/cloud-computers/:id/files/files/:fileId
PATCH  /api/cloud-computers/:id/files/files/:fileId
DELETE /api/cloud-computers/:id/files/files/:fileId
POST   /api/cloud-computers/:id/files/files/:fileId/clone
POST   /api/cloud-computers/:id/files/upload
POST   /api/cloud-computers/:id/files/nodes/paste

Rules:

• Root uses CLOUD_COMPUTER_FILE_ROOT when configured, otherwise the first available path from /workspace, /workspaces, /home/shadow, /state, and /tmp.
• Node ids are opaque cf_... values; clients must not parse them.
• Paths stay under the resolved root. .., control characters, root deletion, and names containing / are rejected.
• Upload and text save write to the running pod through Kubernetes exec.
• Tree traversal has node, depth, and file-size limits.
• Preview uses short-lived signed URLs so browsers do not receive Kubernetes, VNC, CDP, MinIO, or user tokens.

GET /api/cloud-computers/:id/files/files/:fileId/media-url?disposition=inline

#Terminal

Terminal uses the authenticated Socket.IO connection:

• cloud-computer:terminal:start
• cloud-computer:terminal:input
• cloud-computer:terminal:resize
• cloud-computer:terminal:stop
• Space events: cloud-computer:terminal:data, cloud-computer:terminal:exit

The backend wraps kubectl exec -it with node-pty, so TUI programs, resize, Ctrl+C/Ctrl+D, and normal shell behavior work. Interactive terminal access requires a user session; agent tokens cannot open a shell as the user.

#Browser

POST /api/cloud-computers/:id/browser/session
POST /api/cloud-computers/:id/browser/screenshot
POST /api/cloud-computers/:id/browser/navigate
POST /api/cloud-computers/:id/browser/click
POST /api/cloud-computers/:id/browser/type
POST /api/cloud-computers/:id/browser/key
POST /api/cloud-computers/:id/browser/repair

The browser is a browser-native CDP surface. The user operates a real Chrome/Chromium profile through screenshot, navigation, click, text, and key APIs. It is for manual login, MFA, and human verification, not CAPTCHA solving or bypassing third-party controls.

#Desktop

POST /api/cloud-computers/:id/desktop/session
POST /api/cloud-computers/:id/desktop/repair
GET  /api/cloud-computers/:id/desktop/ws?token=...

The web client uses noVNC. The space verifies the short-lived session token and bridges to the namespace-local VNC service through kubectl port-forward. The VNC service must stay ClusterIP/internal-only.

#Workspace Mounts

POST /api/cloud-computers/:id/workspace-mounts
Content-Type: application/json

{
  "serverId": "server-id-or-slug",
  "rootId": "optional-workspace-folder-node-id",
  "mountPath": "/workspace/server-workspaces/server-id",
  "readOnly": true
}

Mounts use the shadowob workspace webdav runtime, keeping authorization behind Shadow workspace APIs and avoiding direct object-storage mounts. Responses never return a full user token; the runtime receives only a Kubernetes Secret reference.

#Buddies

GET  /api/cloud-computers/:id/buddies
POST /api/cloud-computers/:id/buddies
POST /api/cloud-computers/:id/buddies/:buddyId/start
POST /api/cloud-computers/:id/buddies/:buddyId/stop

These routes manage only Cloud Buddies in the selected cloud computer. Creating a Buddy appends the Buddy identity, internal runner runtime, and connector binding to the underlying deployment config, then runs Cloud SaaS redeploy. It does not create a second cloud computer.

#Backups And Recovery

GET  /api/cloud-computers/:id/backups
POST /api/cloud-computers/:id/backups
POST /api/cloud-computers/:id/restore
POST /api/cloud-computers/:id/runtime/repair

Cloud computer UI should use these routes. /api/cloud-saas/deployments/* remains for Cloud developer options. Backups may use CSI VolumeSnapshot or object archive fallback depending on cluster capability and configuration.

#Frontend Integration Checklist

• Treat cloud computers as community objects, not raw deployment records.
• Route from the community desktop and the standalone page to the same Cloud Computers UI.
• Use short-lived session URLs for desktop and browser surfaces; never store VNC, CDP, Kubernetes, MinIO, or user tokens in client state.
• Keep files, terminal, browser, desktop, Buddies, backups, and workspace mounts independently recoverable. One failed component should not blank the whole page.
• Mobile can expose list, create, repair, Buddies, backups, workspace mounts, files, browser actions, and desktop session entry, but should keep terminal and desktop controls compact.

#Seeded Docs Screenshots

Product documentation screenshots should be generated from a stable, business-realistic seed instead of hand-maintained throwaway data.

DOCS_SCREENSHOT_SEED=shadow-docs-v1 pnpm e2e:docs-screenshots:local

The seed flow creates an independent docs scenario with stable users, avatars, space branding, wallpaper, channels, workspace files, Buddies, Buddy Inbox, shop data, cloud computers, and desktop layout. The Playwright pass refreshes community desktop screenshots:

• docs-desktop-travel-home.png
• docs-desktop-gaming-channel.png
• docs-desktop-family-file.png
• docs-desktop-art-cloud-computer.png
• docs-desktop-music-buddy-inbox.png

When cloud computer UI changes, update the faker scenario in scripts/e2e/docs-screenshot-faker.mjs and regenerate the screenshots instead of editing the PNGs manually.

• Spaces
• Workspace
• Cloud
• Space Apps