REST API

holmd serves the REST API under /v1. The wire types are in the holm-api crate, and holm-client is a Rust client for it.

To start the server and set a token, see The server.

Conventions

Base URL. http://127.0.0.1:8080 unless HOLM_SERVER_ADDR changes it.

Authentication. When the server has a token, send Authorization: Bearer <HOLM_SERVER_TOKEN> on each request, or a workspace token or API key (holm_sk_…) from a console. See Workspaces. These endpoints need no bearer token:

• GET /v1/health
• The viewer socket, which takes a short-lived token in the query
• The /v1/cdp/{token}/… proxy, which takes a short-lived token in the path

Bodies. Requests and responses are JSON. Request bodies refuse unknown keys, so a misspelled key gives an error.

Screens. {screen} is the screen number, from 0.

Tabs. tab is a tab ID or label, from GET /v1/boxes/{id}/pages or an open_url action. With no tab, the endpoint uses the page at the front.

Points. A point is {"x": 640, "y": 400}, in device pixels. (0, 0) is the top-left corner.

Idempotency. POST /v1/boxes, POST …/actions, and POST …/fork accept an idempotency-key header. The same key with the same body returns the first result, and does not do the work again. The server keeps keys in memory.

Errors

All errors have this body:

{ "code": "denied", "message": "…", "retryable": false }

retryable tells you if the same request can succeed later.

Endpoints

Health

Boxes

A box in a response:

{
  "id": "box_9cf78792…",
  "runtime": "docker",
  "spec_digest": "…",
  "state": "ready",
  "screens": 1,
  "width": 1280,
  "height": 800,
  "viewer_url": "…",
  "devtools_url": "…",
  "created_at_ms": 1790000000000,
  "expires_at_ms": 1790003600000,
  "owner": "ws_…",
  "spec": { "desktop": { … }, "apps": { … }, "policy": { … } },
  "placement": { "runtime": "docker", … }
}

state is ready, paused, stopped, unreachable, gone, starting, or failed. reason is present when the state needs an explanation. When the server queues its jobs (HOLM_SERVER_JOBS=queue), POST /v1/boxes answers 202 with a box in the starting state. Read the box until it is ready or failed. POST /v1/boxes/{id}/fork answers 202 in the same way, with an empty replay report. A box that is starting or failed refuses other calls with 409, and a failed box stays until it is deleted. owner is the workspace that launched the box, and is absent for a box launched with the server token. spec and placement are what the box was launched with, so the same box can be launched again.

Screen

frame query parameters:

A frame in a response:

{ "hash": "…", "unchanged": false, "png_base64": "…" }

Windows

arrange bodies:

{ "how": "at", "to": { "x": 0, "y": 0 } }
{ "how": "size", "width": 800, "height": 600 }
{ "how": "maximise" }
{ "how": "minimise" }
{ "how": "restore" }

Human control

See Human control.

Files and commands

grep and glob return cut: true when they stop at the limit.

Pages

These endpoints use Chrome DevTools. On remote runtimes, see Control modes.

Browser state

Set cookies:

{
  "url": "https://example.com",
  "cookies": [
    { "name": "session", "value": "…", "http_only": true, "secure": true, "same_site": "Lax", "expires": 1790000000 }
  ]
}

domain and path are also accepted on each cookie.

Chrome DevTools

Give url to Playwright connectOverCDP or browser-use cdp_url. Give ws_url to a library that needs the WebSocket address.

History

Runtimes and images

Add a vendor:

{ "name": "cloud", "provider": "e2b", "fields": { "max_lifetime_secs": 86400 }, "secrets": { "api_key": "…" } }

The server encrypts secrets before it stores them and never returns them. See Runtimes.

Events

The server keeps a log of what happens to boxes, screens and images, for usage and for webhooks.

Each event has seq, at_ms, kind, and, when they apply, owner, box_id, runtime and data. A workspace reads its own events. The server token reads all of them. An event shows about two seconds after it happens, and the server keeps events for 7 days.

Scheduled work

For a server that cannot keep a loop alive, such as a serverless function. Set HOLM_SERVER_SCHEDULE=external, and call these routes from a scheduler. Each accepts GET and POST, with the server token or CRON_SECRET as the bearer token.

When HOLM_PUBLIC_URL and CRON_SECRET are set, the server calls its own /v1/jobs/run when it queues a job, so a job does not wait for the scheduler. On Vercel, the schedule goes in vercel.json:

{
  "crons": [
    { "path": "/v1/jobs/run", "schedule": "* * * * *" },
    { "path": "/v1/jobs/reap", "schedule": "* * * * *" },
    { "path": "/v1/jobs/prune", "schedule": "0 * * * *" }
  ]
}

MCP

/mcp serves MCP over Streamable HTTP, with the same bearer token. See the MCP tools reference.

Create a box

POST /v1/boxes

{
  "spec": {
    "desktop": {
      "server": "x11",
      "width": 1280,
      "height": 800,
      "screens": 1,
      "features": ["wide_fonts", "video", "dock", "accessibility", "audio"],
      "packages": ["jq"]
    },
    "policy": { "network": true }
  },
  "placement": {
    "runtime": "docker",
    "memory": "2g",
    "cpus": "2",
    "expires_after_secs": 3600,
    "idle_timeout_secs": 900,
    "profile": "work"
  }
}

All fields are optional. {} creates a box with the defaults.

spec.desktop:

spec.policy:

spec.apps defines applications that are not in the catalog.

placement:

The response is the box.

Actions

POST /v1/boxes/{id}/screens/{screen}/actions

A batch holds the screen for all its actions and returns one result.

{
  "actions": [
    { "type": "open_url", "url": "https://example.com" },
    { "type": "wait_still", "settle_ms": 400, "within_ms": 10000 },
    { "type": "click", "at": { "x": 640, "y": 81 } }
  ],
  "want": ["frame", "cursor"],
  "settle_ms": 400,
  "have_frame": "…",
  "keep_going": false
}

The result:

Action types

Each action has a type. Pointer actions accept motion (instant, smooth, human) and seed. button is left (default), right, or middle. held is a list of shift, ctrl, alt, and super.

Input

With no at, a click or button action occurs at the pointer. The server releases a button or key after hold_ms (default 10 seconds, maximum 60), when the batch ends, or when a person takes control.

Waits

Screen and windows

Pages

Native widgets

Files and commands

Element operations

The body of POST /v1/boxes/{id}/page/element, and the what of an on_page action. Each has an op.

{ "op": "fill", "query": "Email", "text": "[email protected]" }

The result includes the element, the URL, whether the page navigated, and the controls that changed.

Native widgets

The body of POST /v1/boxes/{id}/screens/{screen}/desktop/node, and the what of an on_node action. Needs a box with the accessibility feature.

node is a query: {"query": "Street", "role": "text"}.

Fork

POST /v1/boxes/{id}/fork

{ "mode": "replay", "up_to": 40, "placement": { "expires_after_secs": 1800 } }

The result is {"box": {…}, "replay": {attempted, ok, stopped_at, truncated, skipped}}. Each entry in skipped has seq, kind, and why.

Example

BASE=http://127.0.0.1:8080

BOX=$(curl -fsS "$BASE/v1/boxes" \
  -H 'content-type: application/json' \
  -H 'idempotency-key: create-demo-1' \
  -d '{"spec": {"desktop": {"width": 1280, "height": 800}}, "placement": {"expires_after_secs": 3600}}' |
  python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')

curl -fsS "$BASE/v1/boxes/$BOX/screens/0/actions" \
  -H 'content-type: application/json' \
  -d '{
    "actions": [
      { "type": "open_url", "url": "https://example.com" },
      { "type": "on_page", "what": { "op": "wait_for", "query": "Example Domain" } },
      { "type": "on_page", "what": { "op": "click", "query": "More information" } }
    ],
    "want": ["frame"]
  }'

curl -fsS -X DELETE "$BASE/v1/boxes/$BOX" -H 'x-holm-confirm-delete: true'