# Linux desktops

A Maritime Linux desktop is a persistent computer (XFCE, Chromium, LibreOffice) for each of your end users, driven by your model. You connect the Maritime MCP server to whatever agent you already run; the model calls `get_computer` once per end user and then `computer` in a screenshot, act, verify loop. Maritime creates the desktop, keeps it warm, sleeps it when idle, wakes it on the next action, and keeps its files and logins between sessions. There is no lifecycle for you to manage.

## At a glance

### What it is
A persistent Linux desktop (XFCE, Chromium, LibreOffice) per end user, which your model drives over MCP or REST.

### Use it for
Websites and apps with no API, browser logins, work a person can take over by link.

### Use something else when
- No screen needed: [Agent box](/content/docs/persistent-sandboxes/index.html)
- Windows-only software: [Windows desktop](/content/docs/windows-desktops/index.html)
- A mobile app: [Android phone](/content/docs/phones/index.html)

### Start it
`POST /api/v1/computers` with `externalUserId`, `get_computer` over MCP, or New sandbox (`?type=computers`).

### Lifecycle
Sleeps after 5 idle minutes with its memory saved and wakes in about a second. The memory snapshot is kept 7 days; the disk until you delete the computer.

### Price
$0.12 an hour awake, per second, for 2 vCPU and 4 GB with the desktop, streaming and takeover. Asleep: $0.08 per GB-month of disk.

### Limits
- 1200 x 750 model screenshots
- 50 actions per batch
- `run_shell` 30 seconds
- 8 MiB per file read or write.

## In sixty seconds

1. Use the key you already have. A `manage` or full-access Maritime key drives computers and agents alike, so the MCP server takes the same bearer token as the rest of the API. To hand out a key that reaches computers and nothing else, create a **Computers key** in the Computers section of [Settings, API keys](/content/settings/api-keys#computers/index.html): a key whose only scope is `computers` is refused on every other Maritime endpoint. Dashboard sessions cannot reach `/api/v1/computers`; that surface takes an API key.
2. Add the MCP server to your agent with one of the snippets below.
3. Your model calls `get_computer` with the end user's id, gets a `computer_id`, then drives it with `computer`. The first call creates the desktop; every later call for the same end user returns the same one.

## Connect your model

The server speaks Streamable HTTP and authenticates with your Computers key as a bearer token. Replace `mk_...` with the key; the exact endpoint for your deployment is shown on the Computers page.

### Copy MCP config

```json
{
  "mcpServers": {
    "maritime-computers": {
      "type": "http",
      "url": "https://mcp.maritime.sh/mcp",
      "headers": {
        "Authorization": "Bearer mk_..."
      }
    }
  }
}
```

### Tool timeouts
Most MCP clients cut a tool call off after 60 seconds. Two calls here can pass that, and both need the limit raised, not just the takeover:
- `get_computer` on first use creates the desktop: 3 to 8 seconds normally, up to 60 on a cold placement. Later wakes take about 3 seconds.
- `request_takeover` with `wait: true` holds until the person clicks Done or Failed, which is minutes. Leaving `wait` at its default returns at once and needs no extra time.

## Tools

| Tool            | What it does |
|-----------------|--------------|
| get_computer    | One computer per end user. `user_id` (unless pinned), optional `name`, `os` (`linux` by default, `windows` or `android`), `arch` (Android only, `x86_64` or `arm64`), and `screen` (Linux only, `{width, height}`). Returns `computer_id`, status, screen size and a coordinate hint. Idempotent. |
| computer        | One canonical action (schema below). Returns the post-action screenshot as an image block plus a text block with `action`, `frame_id`, `width`, `height` and any detail. |
| computer_batch  | Up to 50 actions in order; stops at the first failure. Each step's text is prefixed `[i]`; only the final step carries an image unless a step sets `no_screenshot: false`. |
| run_shell       | Runs a command inside the desktop as the desktop user. `timeout` up to 30 s. Returns exit code, stdout and stderr. |
| read_file       | Reads a file under `/data` or `/home/desk`. Text when UTF-8, otherwise base64 with a `mime` note. 8 MiB cap. |
| write_file      | Writes a file under the same roots. `encoding` is `utf8` (default) or `base64`. |
| request_takeover | For logins, 2FA, CAPTCHAs and payments. Mints a control link and returns it as text. |
| takeover_status  | Where a takeover stands: `mode` (`human` while the person holds the desktop, `agent` once it is back), when it expires, and how the last one ended. |
| close_computer   | Ends the current session now. The desktop sleeps 30 seconds later unless another action arrives (see sessions). |

## Billing
A computer is billed per second while it is awake, at **$0.12 an hour**, with no minimum. Asleep, it is billed only for its disk, $0.08 per GB-month. Nothing is counted per action or per session. Windows desktops are $0.18 an hour and Android phones $0.15 an hour, on the same terms.

The [Computers page](/content/computers/index.html) lists your computers. The [Billing page](/content/billing/index.html) is where the plan is started, changed and cancelled, once, for the whole account.

## Limits

| What               | Limit |
|--------------------|-------|
| Idle sleep          | 5 minutes without an action |
| Close grace         | 30 seconds after close before the computer sleeps |
| Batch               | 50 actions per computer_batch |
| run_shell           | 30 seconds per command |
| Files               | 8 MiB per read or write, absolute paths under /data or /home/desk, no .. |
| Viewer links        | 10 minutes by default, 1 hour at most; a new control link revokes the previous one |
| Rate limits         | 30 creates, 300 actions and 30 viewer links per minute per key |
| Screenshot          | 1200 x 750 model frame on a 1280 x 800 desktop by default; Linux screens 640 to 1920 a side |

## Errors

| Slug                   | Meaning |
|------------------------|---------|
| trial_required          | 402. The account has no trial or plan yet. A person must add a card on the Billing page to start the free trial. |
| trial_cap_reached      | 402. The free trial's $20 of usage is used up. A person must start the plan on the Billing page. |
| payment_required        | 402. The last payment failed. A person must update the card on the Billing page. |