# Raster

> Docs for the Raster API and SDK: a persistent Linux machine for agents and people.

## Docs

- [Raster](https://raster.sh/docs): A machine is a persistent Linux computer. You create one, it boots, and it keeps its disk until you delete it.

## Tutorial

- [Create your first machine](https://raster.sh/docs/tutorial/create-your-first-machine): Install an SDK, boot a machine, and drive it — from nothing to a running, driven computer.

## How-to guides

- [Take input control](https://raster.sh/docs/how-to/take-input-control): Hand the keyboard from an agent to a person, and back, without the two interleaving.
- [Connect the live desktop](https://raster.sh/docs/how-to/connect-the-live-desktop): Ask the API for a connect ticket, then open the websocket gateway with it.

## Reference

- [Reference](https://raster.sh/docs/reference): Every capability the product ships, and the limits on each.
- [Machines](https://raster.sh/docs/reference/machines): The core resource — sizes, states, the lifecycle, and the event log.
- [The desktop](https://raster.sh/docs/reference/desktop): Screenshots, pointer, keyboard, clipboard, and the display geometry every coordinate is in.
- [The terminal](https://raster.sh/docs/reference/terminal): One-shot commands as argv, interactive ptys, and why a non-zero exit code is a success.
- [Files](https://raster.sh/docs/reference/files): List, read, write, upload and download — with an encoding you name rather than one that is guessed.
- [The browser](https://raster.sh/docs/reference/browser): Open a URL, enumerate tabs, and drive the rest of it as a desktop.
- [Sessions and input control](https://raster.sh/docs/reference/sessions): One holder of the keyboard at a time, and how a person takes it back from an agent.
- [Snapshots, forks and templates](https://raster.sh/docs/reference/persistence): Captured disks, branched machines, and named starting states.
- [Published ports](https://raster.sh/docs/reference/ports): A guest port at its own https hostname — private by default, and the credential shown once.
- [Secrets](https://raster.sh/docs/reference/secrets): Values delivered into tmpfs inside a machine, and never readable back out.
- [The realtime gateway](https://raster.sh/docs/reference/realtime): Live screen, input, terminal and event channels over one websocket protocol.
- [Organizations, members and keys](https://raster.sh/docs/reference/organizations): Roles, permissions, API key scopes, and how the two intersect.
- [Plans, usage and billing](https://raster.sh/docs/reference/billing): Entitlements, meters, rates, and the current-period summary.
- [API conventions](https://raster.sh/docs/reference/api-conventions): Auth, ids, idempotency, pagination, versioning and retries — the things every operation assumes.
- [Errors](https://raster.sh/docs/reference/errors): The closed set of codes, their HTTP statuses, and which are worth retrying.

## Explanation

- [How machines behave](https://raster.sh/docs/explanation/how-machines-behave): The reasoning behind sizes, readiness, coordinates, and exit codes.

## Api

- [Computer API](https://raster.sh/docs/api)

### api-keys

- [create an api key, returning the secret once](https://raster.sh/docs/api/api-keys/apikeys-create)
- [list api keys](https://raster.sh/docs/api/api-keys/apikeys-list)
- [revoke an api key](https://raster.sh/docs/api/api-keys/apikeys-revoke)

### auth

- [change the active organization](https://raster.sh/docs/api/auth/auth-switchorganization)
- [create a user and their personal organization](https://raster.sh/docs/api/auth/auth-signup)
- [list browser sessions](https://raster.sh/docs/api/auth/auth-listsessions)
- [revoke a browser session](https://raster.sh/docs/api/auth/auth-revokesession)
- [revoke the current browser session](https://raster.sh/docs/api/auth/auth-logout)
- [start a browser session](https://raster.sh/docs/api/auth/auth-login)
- [the authenticated principal and its active organization](https://raster.sh/docs/api/auth/auth-me)

### billing

- [open the customer portal](https://raster.sh/docs/api/billing/billing-portal)
- [start a checkout](https://raster.sh/docs/api/billing/billing-checkout)
- [the organization's billing account](https://raster.sh/docs/api/billing/billing-getaccount)
- [usage summary for the current period](https://raster.sh/docs/api/billing/billing-usagesummary)

### computer

- [capture the machine's screen](https://raster.sh/docs/api/computer/computer-screenshot)
- [click the pointer](https://raster.sh/docs/api/computer/computer-mouseclick)
- [close a terminal](https://raster.sh/docs/api/computer/computer-closeterminal)
- [drag the pointer](https://raster.sh/docs/api/computer/computer-mousedrag)
- [list a directory on the machine](https://raster.sh/docs/api/computer/computer-listfiles)
- [list the browser's open tabs](https://raster.sh/docs/api/computer/computer-browsertabs)
- [list the machine's terminals](https://raster.sh/docs/api/computer/computer-listterminals)
- [mint a short-lived ticket for a realtime connection](https://raster.sh/docs/api/computer/computer-connect)
- [move the pointer](https://raster.sh/docs/api/computer/computer-mousemove)
- [open a terminal on the machine](https://raster.sh/docs/api/computer/computer-openterminal)
- [open a url in the machine's browser](https://raster.sh/docs/api/computer/computer-openbrowser)
- [press a key combination](https://raster.sh/docs/api/computer/computer-hotkey)
- [press one key](https://raster.sh/docs/api/computer/computer-presskey)
- [read a file from the machine](https://raster.sh/docs/api/computer/computer-readfile)
- [read the machine's clipboard](https://raster.sh/docs/api/computer/computer-getclipboard)
- [resize the machine's display](https://raster.sh/docs/api/computer/computer-resizedisplay)
- [run a command on the machine](https://raster.sh/docs/api/computer/computer-exec)
- [scroll the wheel](https://raster.sh/docs/api/computer/computer-mousescroll)
- [the machine's current display geometry](https://raster.sh/docs/api/computer/computer-display)
- [type text](https://raster.sh/docs/api/computer/computer-typetext)
- [write a file to the machine](https://raster.sh/docs/api/computer/computer-writefile)
- [write the machine's clipboard](https://raster.sh/docs/api/computer/computer-setclipboard)

### images

- [list machine images](https://raster.sh/docs/api/images/images-list)

### machines

- [create a machine](https://raster.sh/docs/api/machines/machines-create)
- [delete a machine](https://raster.sh/docs/api/machines/machines-delete)
- [fork a running machine](https://raster.sh/docs/api/machines/machines-fork)
- [get a machine](https://raster.sh/docs/api/machines/machines-get)
- [list a machine's events](https://raster.sh/docs/api/machines/machines-events)
- [list machines](https://raster.sh/docs/api/machines/machines-list)
- [start a stopped machine](https://raster.sh/docs/api/machines/machines-start)
- [stop a machine, keeping its files](https://raster.sh/docs/api/machines/machines-stop)
- [stop and start a machine](https://raster.sh/docs/api/machines/machines-restart)
- [update a machine](https://raster.sh/docs/api/machines/machines-update)

### members

- [accept an invitation](https://raster.sh/docs/api/members/invitations-accept)
- [change a member's role](https://raster.sh/docs/api/members/members-update)
- [invite someone to the organization](https://raster.sh/docs/api/members/invitations-create)
- [list members of the active organization](https://raster.sh/docs/api/members/members-list)
- [list pending invitations](https://raster.sh/docs/api/members/invitations-list)
- [remove a member](https://raster.sh/docs/api/members/members-remove)
- [revoke an invitation](https://raster.sh/docs/api/members/invitations-revoke)

### organizations

- [create an organization](https://raster.sh/docs/api/organizations/organizations-create)
- [get an organization](https://raster.sh/docs/api/organizations/organizations-get)
- [organizations the user belongs to](https://raster.sh/docs/api/organizations/organizations-list)

### plans

- [get a plan](https://raster.sh/docs/api/plans/billing-getplan)
- [list plans](https://raster.sh/docs/api/plans/billing-listplans)

### ports

- [get a published port](https://raster.sh/docs/api/ports/ports-get)
- [list a machine's published ports](https://raster.sh/docs/api/ports/ports-list)
- [list published ports](https://raster.sh/docs/api/ports/organizationports-list)
- [publish a port on the machine at its own https url](https://raster.sh/docs/api/ports/ports-expose)
- [stop publishing a port](https://raster.sh/docs/api/ports/ports-unexpose)

### secrets

- [list a machine's secret names](https://raster.sh/docs/api/secrets/secrets-list)
- [list secret names](https://raster.sh/docs/api/secrets/organizationsecrets-list)
- [revoke a secret](https://raster.sh/docs/api/secrets/secrets-delete)
- [store a secret for the machine](https://raster.sh/docs/api/secrets/secrets-set)

### sessions

- [acquire or renew the input lease](https://raster.sh/docs/api/sessions/inputleases-acquire)
- [close a session](https://raster.sh/docs/api/sessions/sessions-close)
- [list sessions](https://raster.sh/docs/api/sessions/sessions-list)
- [open a session on a machine](https://raster.sh/docs/api/sessions/sessions-create)
- [read the current input lease](https://raster.sh/docs/api/sessions/inputleases-get)
- [release the input lease](https://raster.sh/docs/api/sessions/inputleases-release)

### snapshots

- [capture a machine's disk](https://raster.sh/docs/api/snapshots/snapshots-create)
- [delete a snapshot](https://raster.sh/docs/api/snapshots/snapshots-delete)
- [get a snapshot](https://raster.sh/docs/api/snapshots/snapshots-get)
- [list snapshots](https://raster.sh/docs/api/snapshots/snapshots-list)
- [restore a machine from a snapshot](https://raster.sh/docs/api/snapshots/snapshots-restore)

### templates

- [create a template](https://raster.sh/docs/api/templates/templates-create)
- [delete a template](https://raster.sh/docs/api/templates/templates-delete)
- [get a template](https://raster.sh/docs/api/templates/templates-get)
- [list templates](https://raster.sh/docs/api/templates/templates-list)

### usage

- [list usage records](https://raster.sh/docs/api/usage/usage-list)
- [usage totals bucketed over a window](https://raster.sh/docs/api/usage/usage-series)

## Integrations

- [Integrations](https://raster.sh/docs/integrations): Four ways to hand a machine to an agent, one model-agnostic toolkit underneath them, and a catalogue of agents that run on the machine itself.
- [Anthropic](https://raster.sh/docs/integrations/anthropic): The computer toolset for Claude — one tool entry, one handler, and your own loop.
- [OpenAI](https://raster.sh/docs/integrations/openai): Two surfaces over one translation — the Responses API's computer tool, and the Agents SDK's Computer.
- [MCP](https://raster.sh/docs/integrations/mcp): A stdio MCP server any client can launch, with eleven tools over one API key.
- [opencode](https://raster.sh/docs/integrations/opencode): A plugin that gives an opencode session a real desktop, a mouse and a shell.
- [OpenClaw](https://raster.sh/docs/integrations/openclaw): Running a persistent agent daemon on a machine, with credentials that survive a restart and never enter a snapshot.

## SDKs

- [SDKs](https://raster.sh/docs/sdk): TypeScript and Python over one API — installation, configuration, and where the two differ.
- [Client](https://raster.sh/docs/sdk/client): Construction, options, resource groups, and the generated contract client underneath.
- [Machines](https://raster.sh/docs/sdk/machines): Create, get and list machines; drive their lifecycle; wait for a desktop; read the event log.
- [Screen](https://raster.sh/docs/sdk/screen): Screenshots, display geometry, and resizing the coordinate space.
- [Input](https://raster.sh/docs/sdk/input): Mouse, keyboard, clipboard, and the single lease that governs all three.
- [Terminal](https://raster.sh/docs/sdk/terminal): One-shot commands as argv, interactive ptys, and why a non-zero exit code is a success.
- [Files](https://raster.sh/docs/sdk/files): List, read, write, upload and download — with an encoding you name rather than one that is guessed.
- [Browser](https://raster.sh/docs/sdk/browser): Open a URL, enumerate tabs, and drive the rest of it as a desktop.
- [Ports](https://raster.sh/docs/sdk/ports): Publish a guest port at its own https hostname — private by default, credential shown once.
- [Secrets](https://raster.sh/docs/sdk/secrets): Store values that reach the machine but never come back, and that a captured disk never carries.
- [Snapshots](https://raster.sh/docs/sdk/snapshots): Capture a disk, restore onto it, fork a machine from it, or name it as a template.
- [Streams](https://raster.sh/docs/sdk/streams): Live frames and pty bytes over the websocket gateway.
- [Tools](https://raster.sh/docs/sdk/tools): The model-agnostic toolkit — eight JSON-schema tools and a dispatcher, with no vendor package in it.
- [Errors and retries](https://raster.sh/docs/sdk/errors): RasterError, the closed code set, idempotency, retries and pagination.
- [CLI](https://raster.sh/docs/sdk/cli): raster — the SDK with a terminal in front of it.