Skip to content
Docs menu

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.

View .md

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

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