---
title: Computers for agents
description: The computers_* MCP tools and the REST API behind them, who a call acts as, and what an agent may do with its own computer and the shared ones it belongs to.
section: computers
order: 20
audience: [agent, builder]
sources: [services/nodejs-cloud/lib/computers/mcp.ts, services/nodejs-cloud/lib/computers/credentials-http.ts, services/nodejs-cloud/lib/computers/http.ts, services/nodejs-cloud/app/api/workspace/computers, docs/adr/0078-venom-computers.md]
features: []
---

Connect the Computers server with `claude mcp add --transport http venom-computers https://<your cloud>/workspace/mcp/computers`
(or any MCP client; the scopes are `computers:read` and `computers:write`). The tools are also listed in
[Workspace MCP](/docs/cloud/workspace-mcp.md).

## Who a call acts as

- A **personal key or an OAuth grant** acts as the member, with their role's rights ([What a computer is](/docs/computers/overview.md)).
- A **team key bound to a service agent**, or a daemon or session named with `x-venom-agent`, acts as that agent. It sees
  and uses its own computer and the shared computers it belongs to. It creates its own computer only, cannot take control,
  archive a computer or change members.
- A **team key with no agent** only reads.

## Tools

| Tool | Does |
|---|---|
| `computers_seat_list` | The computers you can see, with state, daemon, members and who controls each. Filters: `state`, `daemon_id`, `include_archived`. |
| `computers_seat_get` | One computer. |
| `computers_seat_create` | `name`, optional `kind` (`browser`), `mode` (`dedicated` or `shared`), `private`, `agent_ref`. An agent gets its own. `409 no_capacity` when no daemon has room, `409 seat_exists` when the agent already has one. |
| `computers_seat_update` | Rename. A person may also change `mode`, `private` and `agent_ref`. A shared computer with members cannot become dedicated. |
| `computers_seat_delete` | Archive and have the daemon remove the profile. Admins, or the person who created it. |
| `computers_seat_start` | Wake a computer. Answers the state it has: `active`, `starting` (the daemon has not answered yet) or `queued` with how many are ahead. |
| `computers_seat_stop` | Hibernate; the profile and logins stay. |
| `computers_activity_list` | What it did, newest first. `limit`, `before` (the previous page's cursor), `kind`. |
| `computers_takeover_request` | Ask a person to take over: `reason` in one line, no passwords or codes. The computer shows Needs you. |
| `computers_tab_list`, `computers_tab_share` | The shared tabs of a running shared computer, who has each one's turn and how many wait; mark a tab shared ([Sharing a computer](/docs/computers/sharing.md)). |
| `computers_credential_list` | The saved logins, cards and texts you can use: label, kind, scope, origins and handles (`{{secret:github.password}}`), never a value. |
| `computers_credential_create` | `label`, `kind` (`login`, `card`, `text`), `origins`, `values`, optional `scope`. Sealed and write-only. Org admins, an agent's owner for its logins, the person who made a computer for its own; never an agent. |
| `computers_credential_delete` | Revoke one at once. Same right as saving it. |
| `computers_member_list`, `computers_member_add`, `computers_member_remove` | The agents of a shared computer (`member` is `agent:<id>`). Admins, or the person who created it. |
| `computers_approval_list`, `computers_approval_decide` | The asks of agents running on computers (approvals and takeovers), and answering one. See [Agents on computers](/docs/computers/agents-on-computers.md). |
| `computers_agent_get`, `computers_agent_set` | Whether a Chat channel's agent or a Tasks agent uses a computer, and its daily cap. |
| `computers_run_list`, `computers_run_stop` | The agents' runs on computers, and stopping one. |

Every tool takes `format: "json"` for structured content. Arguments the tool does not list are refused.

## Working a login

1. `computers_seat_start` and wait for `active` (or read it again if it says `starting`).
2. Use the browser tools on that computer. Read pages as text first.
3. At a login with a saved login (`computers_credential_list` shows the handles), type `{{secret:label.username}}` and
   `{{secret:label.password}}` with `browser_type`; you never see the values. At a login without one, a 2FA prompt or a CAPTCHA, call `computers_takeover_request` with what the person needs to do, then wait.
   When the computer is `active` again, read the page and carry on.

## REST

The console's API mirrors the tools. It is for the browser session and answers JSON.

| Route | Tool |
|---|---|
| `GET`, `POST /api/workspace/computers` | `computers_seat_list`, `computers_seat_create` |
| `GET`, `PATCH`, `DELETE /api/workspace/computers/{id}` | `computers_seat_get`, `computers_seat_update`, `computers_seat_delete` |
| `POST /api/workspace/computers/{id}/start`, `/stop` | `computers_seat_start`, `computers_seat_stop` |
| `GET /api/workspace/computers/{id}/activity` | `computers_activity_list` |
| `POST /api/workspace/computers/{id}/takeover` | `computers_takeover_request` |
| `GET /api/workspace/computers/{id}/thumbnail` | `computers_thumbnail_get` |
| `POST /api/workspace/computers/{id}/screen`, `GET .../frame`, `POST .../takeover/resolve` | a person's live view and answers; see [Watch a computer](/docs/computers/watch-and-control.md) |
| `GET`, `POST`, `DELETE /api/workspace/computers/{id}/members` | `computers_member_list`, `_add`, `_remove` |
| `GET`, `POST /api/workspace/computers/credentials`, `DELETE /api/workspace/computers/credentials/{id}` | `computers_credential_list`, `_create`, `_delete` ([Saved logins and cards](/docs/computers/saved-logins.md)) |
| `POST`, `DELETE /api/workspace/computers/{id}/control` | a person takes, renews or releases control; there is no tool for it |
| `GET /api/workspace/computers/approvals`, `POST …/approvals/{id}` | `computers_approval_list`, `computers_approval_decide` |
| `GET`, `PUT /api/workspace/computers/agents` | `computers_agent_get`, `computers_agent_set` |
| `GET /api/workspace/computers/runs`, `DELETE …/runs/{id}` | `computers_run_list`, `computers_run_stop` |
