Computers for agents
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.
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.
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).
- 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). |
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. |
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
computers_seat_startand wait foractive(or read it again if it saysstarting).- Use the browser tools on that computer. Read pages as text first.
- At a login with a saved login (
computers_credential_listshows the handles), type{{secret:label.username}}and{{secret:label.password}}withbrowser_type; you never see the values. At a login without one, a 2FA prompt or a CAPTCHA, callcomputers_takeover_requestwith what the person needs to do, then wait. When the computer isactiveagain, 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 |
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) |
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 |