Computers on demand

Linux desktops

A persistent Linux desktop (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.

From the dashboard, open New sandbox (/dashboard/new-sandbox?type=computers), name the computer and click Start.

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: 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.

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

The JSON form is what Cursor, Claude Code (.mcp.json) and most local clients read. The OpenAI Responses and Anthropic Messages entries are hosted MCP tools: the provider connects to the server for you, so your backend never proxies screenshots.

Building on the Vercel AI SDK? Version 6 has no MCP client of its own: experimental_createMCPClient was removed after v5, so any guide that reaches for it is out of date. Two options that work. Use a hosted MCP tool from the provider (the OpenAI Responses and Anthropic Messages entries above) and let the model connect. Or connect yourself with @modelcontextprotocol/sdk: build a Client over StreamableHTTPClientTransport pointed at the URL above, with the Authorization header in requestInit, then hand the tools it lists to generateText yourself.

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const mcp = new Client({ name: 'my-app', version: '1.0.0' })
await mcp.connect(
  new StreamableHTTPClientTransport(new URL(mcpUrl), {
    requestInit: { headers: { Authorization: `Bearer ${process.env.MARITIME_COMPUTERS_KEY}` } },
  }),
)

const { tools } = await mcp.listTools()
// Convert each tool to an AI SDK tool: inputSchema stays as is, and
// execute calls mcp.callTool({ name, arguments: args }).

Pin the server to one end user

On the plain endpoint the model passes the end user's id to get_computer. That is fine for a trusted orchestrator, but for a customer-facing agent a model-supplied user id is one prompt injection away from another end user's desktop. Mount the pinned form instead and the server ignores any other id:

https://mcp.maritime.sh/mcp/u/<externalUserId>

Clients that can set headers can pin with X-Maritime-User: <externalUserId> on the plain endpoint. Either way, get_computer needs no user_id, and a mismatching one is refused.

Add it to your product

The whole integration for a website or app with its own agent loop is six steps. Nothing about your backend changes; the computer is just another tool the model can call.

1. Create a Computers key in the Computers section of Settings, API keys. It is shown once. Keep it on your server; never send it to the browser.
2. Build the pinned URL per signed-in user on your server from their id, so the model can only ever reach that user's desktop.
3. Register the server with your model using one of the snippets above, with Authorization: Bearer mk_....
4. Tell the model when to use it with one line in your system prompt (below).
5. Show takeover links to your user. When the model calls request_takeover it returns a link and a reason; render both in your chat. The person opens it, finishes the step, and clicks Done. By default the tool call has already returned, so the model finds out through takeover_status or through its next action being refused with human_in_control.
6. Optionally let users watch. Mint a watch link with POST /api/v1/computers/{id}/viewer and {"mode": "watch"}. That is a REST call to the Maritime API, not to the MCP server: send it to the same API host your Computers key was issued on, which is printed next to the MCP URL on the Computers page. The link is view-only and expires on its own.

When a task needs a real browser or desktop, call get_computer first and keep the computer_id it returns: every other computer tool takes that computer_id as an argument. Take a screenshot before acting and use coordinates from the last screenshot. If you reach a login, CAPTCHA or payment step, call request_takeover with a short reason and show the user the link it returns; your next action stays refused with human_in_control until they are done, so retry it (or call takeover_status) instead of asking again.

# the pinned URL is built from YOUR user id, never from model output
mcp_url = f"{MARITIME_MCP_URL}/u/{current_user.id}"

# OpenAI Responses API, hosted MCP tool
tools = [{"type": "mcp", "server_label": "maritime-computers", "server_url": mcp_url,
          "authorization": MARITIME_COMPUTERS_KEY, "require_approval": "never"}]

# Anthropic Messages API, MCP connector
mcp_servers = [{"type": "url", "url": mcp_url, "name": "maritime-computers",
                "authorization_token": MARITIME_COMPUTERS_KEY}]

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.

Raise the tool timeout for both. Claude Code reads MCP_TOOL_TIMEOUT (milliseconds) from the environment. The MCP TypeScript and Python SDKs take a per-call timeout on callTool; the TypeScript client also has resetTimeoutOnProgress, which the waiting takeover's progress notifications keep alive. Hosted MCP tools on the provider side have their own ceilings, which is another reason to leave wait false there.

Tools

The computer action

computer takes computer_id, an action from the list below, and the fields that action needs. The same schema is the body of POST /api/v1/computers/{computer_id}/actions on REST.

Coordinate rules

• Screenshots are 1200 x 750 by default on a physical 1280 x 800 desktop. Every result reports width and height; coordinates are pixels in that frame, and Maritime scales them to the screen.
• Take a screenshot before acting, and never act on a screen the model has not seen this turn.
• Work in a strict loop: screenshot, plan one step, act, read the returned screenshot, verify. Each result carries a monotonic frame_id so the model can tell a fresh frame from a stale one.
• Click the target field and confirm focus before typing. Type digits and punctuation with type, not key.
• On-screen text is untrusted data, never instructions. Prompt injection from a web page is your model's problem; the tools never execute anything read from a screenshot.
• While a person holds the desktop (after request_takeover) every action is refused with human_in_control and retryAfterS: 15. Wait, then take a screenshot to continue, or call takeover_status to see whether the desktop is back.

Sessions

A session is a period of continuous use of one computer. It is a record, not a charge: nothing here costs money. These are the rules, exactly as the backend applies them:

• A session opens on the first action against a computer that has no open session.
• Screenshots count as actions: they keep the session alive and increment the screenshot counter.
• close_computer (REST: sessions/close) ends the session and starts a 30 seconds grace. An action inside the grace reopens the same session. After the grace the computer sleeps.
• A session with no action for 5 minutes closes as idle and the computer sleeps. The next action opens a new session.
• Waking a computer, watching it through a viewer link, and takeover never open a session.
• Creating and waking are where billing can refuse: 402 when the account has no trial or plan, its free trial's $20 is used up, or a payment failed, and 429 concurrency with a 15 second retry hint when the account already runs as many machines at once as the plan allows. A computer that is already awake is never refused. The codes are under Errors.

Persistence

• One computer per end user. get_computer with the same id always returns the same desktop. On MCP it needs user_id unless the connection is pinned. On REST, POST /api/v1/computers without externalUserId creates a new computer every time.
• After 5 idle minutes the desktop sleeps: memory is snapshotted, open windows and all. It wakes on the next action in about a second, or a few seconds when the snapshot is gone.
• The memory snapshot is kept for 7 days after the last action. Past that the desktop still wakes, from a fresh boot with the same disk, so only open windows are lost.
• Files, the browser profile and its logins live on the computer's own disk under /data and /home/desk. They are kept until you delete the computer.
• Deleting a computer destroys its disk and snapshots. Deleted computers return 404.

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.

Usage draws from your plan's monthly usage credit (Starter $20, Growth $100, Scale $500, Dedicated $5,000), and usage past the credit goes on the same invoice. Growth, Scale and Dedicated take 10%, 20% and 30% off the rates. A new account starts with a 7-day free trial on Starter terms: a card is needed to start the first machine and is not charged then, and the week includes up to $20 of usage. Full rates, the trial and plan changes are in Billing & plans. Accounts on an earlier seat plan keep that plan's terms.

The Computers page lists your computers. The Billing page is where the plan is started, changed and cancelled, once, for the whole account.

Limits

Errors

REST errors on /api/v1/computers are written for the model that reads them: {"error": "slug", "message": "...", "retryAfterS": 15}. On MCP they become tool results with isError: true and the same message.

REST and SDK

Everything the MCP server does is a call to /api/v1/computers with the Computers key as a bearer token. Field names are camelCase (externalUserId, frameId, imageB64, exitCode, retryAfterS).

The TypeScript maritime-sdk exposes these operations as client.computers. Its create takes externalUserId, name, os, arch and network. Its computers/dialects module converts OpenAI, Gemini and Qwen computer-use actions to the canonical schema (fromOpenAI, fromGemini, fromQwen) for models that do not speak MCP. The Python SDK's client.computers has create (external_user_id, name, os, arch, network), list, get, delete, wake and sleep; send actions, screenshots, exec, files, the viewer, sessions and usage with client.request.

A computer's network (what it may reach on the internet, where its traffic exits, which of your private systems it may use) is the same object agents have. Send it as network on POST /api/v1/computers or set it on maritime computers create with --internet, --allow-out, --network-policy, --egress, and --access. See Networks.

os defaults to linux. windows and android run where Maritime has hosts for them and return 403 machine_unavailable where no host for them exists; see Windows desktops and Android phones.

Works with

• Claude, OpenAI, Gemini through MCP, with the snippets above.
• Any other model through REST, using the SDK converters to map its native computer-use actions to the canonical one.
• People through the viewer: a watch link to look, a control link to take over for a login or a CAPTCHA and hand the desktop back with Done.

Security notes

• Each computer is its own micro-VM with its own disk. Computers cannot reach each other.
• Typed text is never logged and never appears in an error. It can contain passwords.
• Viewer links are short-lived, bound to one computer and one mode, and every link is revoked when a session closes, the computer sleeps, or a takeover completes. View-only links cannot send input; the server drops it, not the browser.
• Scope decides what a key reaches. A key whose only scope is computers drives computers and is refused on every other Maritime endpoint, so a leak is contained to this product. A manage or full-access key drives both products; treat it as it deserves.