# Kubi

> Give your AI agent its own Linux desktop that stays on. It sees the screen, clicks and types, runs commands and moves files through one API, a TypeScript SDK or a hosted MCP server. A person can watch live and take over at any time.

API base URL: `https://api.trykubi.com/v1`. Send `Authorization: Bearer $KUBI_API_KEY` on every request. OpenAPI file: https://docs.trykubi.com/openapi.json. Hosted MCP server: https://mcp.trykubi.com.

## Agent instructions

- Look, then act: take a screenshot, act with its `screenshot_id` and `"screenshot": "after"`, and you get the next screen in the same reply.
- Send an `Idempotency-Key` on every POST and resend with the same key after a lost reply. Never repeat an action after `504 OUTCOME_UNKNOWN`: look first.
- `409 STALE_OBSERVATION` means the screen changed since your screenshot, a person's input included: take a new screenshot before acting again, never repeat the action blind.
- Every call answers within 30 s; poll operations and commands with `wait_s=25`.

## Docs

- [Introduction](https://docs.trykubi.com/index.md): Always-on Linux desktops for AI agents. What a screen is and the three ways to drive one.
- [Quickstart](https://docs.trykubi.com/quickstart.md): From sign-up to your agent's first click in about five minutes.
- [Connect your agent](https://docs.trykubi.com/connect-your-agent.md): Add the hosted MCP server to Claude Code, claude.ai, Codex, Cursor or VS Code. No code, about two minutes.
- [Screens](https://docs.trykubi.com/concepts/screens.md): What a screen is, its two kinds, templates, snapshots, its states, and how power, delete and export work.
- [Billing and history](https://docs.trykubi.com/concepts/billing-and-history.md): How both kinds of screen are billed, usage credit, the screen cap, and the record of every call kept for 30 days.
- [The look and act loop](https://docs.trykubi.com/concepts/look-and-act.md): Screenshots, actions, coordinates, and how one call becomes one agent step.
- [People and agents](https://docs.trykubi.com/concepts/people-and-agents.md): One shared desktop. Watch live, take control, and how your agent reaches you.
- [Keys and permissions](https://docs.trykubi.com/concepts/permissions.md): API keys, the four permissions, and what MCP sign-in grants.
- [Commands and files](https://docs.trykubi.com/guides/commands-and-files.md): Run shell commands, follow long ones, and move files in and out.
- [Claude, OpenAI and Gemini](https://docs.trykubi.com/guides/models.md): How each model's computer-use actions map to ours, and which coordinates to send.
- [Run your agent inside a screen](https://docs.trykubi.com/guides/agent-inside-a-screen.md): Keep an agent going with your laptop closed, as a service on the screen.
- [Drive the browser with Playwright](https://docs.trykubi.com/guides/browser.md): Attach Playwright or Puppeteer to the Chromium already open on the screen, with its logins.
- [Errors](https://docs.trykubi.com/errors.md): Every error code, what it means and what to do.
- [Retries and idempotency](https://docs.trykubi.com/reference/retries.md): How to retry any call without clicking twice or paying twice.
- [Limits, lists and versions](https://docs.trykubi.com/reference/limits.md): Time limits, rate limits, sizes, pagination and how the API changes.
- [TypeScript SDK](https://docs.trykubi.com/sdk/typescript.md): Install, credentials, and every method next to its API call.
- [Changelog](https://docs.trykubi.com/changelog.md): What changed in the API, newest first.

## API

- `GET /screens`: List screens. Needs the `read` permission. Answers within 2 s.
- `POST /screens`: Create a screen. Needs the `power` permission. Answers within 5 s.
- `GET /screens/{screen_id}`: Get a screen. Needs the `read` permission. Answers within 2 s.
- `PATCH /screens/{screen_id}`: Rename, recolour or relabel a screen. Needs the `power` permission. Answers within 2 s.
- `DELETE /screens/{screen_id}`: Delete a screen. Needs the `power` permission. Answers within 5 s.
- `POST /screens/{screen_id}/start`: Start a screen. Needs the `power` permission. Answers within 5 s.
- `POST /screens/{screen_id}/stop`: Stop a screen. Needs the `power` permission. Answers within 5 s.
- `POST /screens/{screen_id}/restart`: Restart a screen. Needs the `power` permission. Answers within 5 s.
- `POST /screens/{screen_id}/convert`: Switch a screen's kind. Needs the `power` permission. Answers within 5 s.
- `GET /templates`: List templates. Needs the `read` permission. Answers within 2 s.
- `POST /templates`: Save a screen as a template. Needs the `power` permission. Answers within 5 s.
- `GET /templates/{template_id}`: Get a template. Needs the `read` permission. Answers within 2 s.
- `DELETE /templates/{template_id}`: Delete a template. Needs the `power` permission. Answers within 5 s.
- `GET /screens/{screen_id}/snapshots`: List snapshots. Needs the `read` permission. Answers within 2 s.
- `POST /screens/{screen_id}/snapshots`: Snapshot a screen. Needs the `power` permission. Answers within 5 s.
- `DELETE /screens/{screen_id}/snapshots/{snapshot_id}`: Delete a snapshot. Needs the `power` permission. Answers within 5 s.
- `POST /screens/{screen_id}/reset`: Reset a screen. Needs the `power` permission. Answers within 5 s.
- `GET /operations/{operation_id}`: Get an operation. Needs the `read` permission. Answers within 28 s.
- `GET /screens/{screen_id}/operations`: List a screen's operations. Needs the `read` permission. Answers within 2 s.
- `GET /screens/{screen_id}/screenshot`: Take a screenshot. Needs the `read` permission. Answers within 5 s.
- `GET /screens/{screen_id}/screenshot/image`: Take a screenshot (image bytes). Needs the `read` permission. Answers within 5 s.
- `POST /screens/{screen_id}/actions`: Run a batch of actions. Needs the `control` permission. Answers within 28 s.
- `POST /screens/{screen_id}/click`: Click. Needs the `control` permission. Answers within 10 s.
- `POST /screens/{screen_id}/type`: Type text. Needs the `control` permission. Answers within 28 s.
- `POST /screens/{screen_id}/press`: Press keys. Needs the `control` permission. Answers within 25 s.
- `POST /screens/{screen_id}/scroll`: Scroll. Needs the `control` permission. Answers within 10 s.
- `POST /screens/{screen_id}/drag`: Drag. Needs the `control` permission. Answers within 10 s.
- `POST /screens/{screen_id}/move`: Move the pointer. Needs the `control` permission. Answers within 10 s.
- `POST /screens/{screen_id}/exec`: Run a command. Needs the `exec` permission. Answers within 28 s.
- `GET /screens/{screen_id}/exec/{exec_id}`: Get a command's status and output. Needs the `exec` permission. Answers within 28 s.
- `POST /screens/{screen_id}/exec/{exec_id}/kill`: Stop a command. Needs the `exec` permission. Answers within 12 s.
- `PUT /screens/{screen_id}/files`: Upload a file. Needs the `exec` permission. Answers within 28 s.
- `GET /screens/{screen_id}/files`: Download a file. Needs the `exec` permission. Answers within 28 s.
- `GET /screens/{screen_id}/dir`: List a folder. Needs the `exec` permission. Answers within 5 s.
- `GET /screens/{screen_id}/clipboard`: Read the clipboard. Needs the `control` permission. Answers within 5 s.
- `PUT /screens/{screen_id}/clipboard`: Set the clipboard. Needs the `control` permission. Answers within 5 s.
- `POST /screens/{screen_id}/viewer`: Get a live-view link. Needs the `read` permission. Answers within 2 s.
- `GET /screens/{screen_id}/viewer`: Open the live view (WebSocket). No key needed. Answers within 5 s.
- `GET /screens/{screen_id}/history`: Read the screen's history. Needs the `read` permission. Answers within 28 s.
- `GET /screens/{screen_id}/screenshots/{screenshot_id}`: Get a saved screenshot. Needs the `read` permission. Answers within 5 s.
- `GET /me`: Who am I. Needs the `read` permission. Answers within 2 s.
- `GET /openapi.json`: This spec. No key needed. Answers within 2 s.
- `GET /secrets`: List secrets. Needs the `read` permission. Answers within 2 s.

## Optional

- [Full docs in one file](https://docs.trykubi.com/llms-full.txt)