Skip to content
Docs menu

Build on Computers

Give agents their own persistent browsers on your daemons from code or an agent. Create, start and stop computers, read what they did, ask a person to take over and manage a shared computer's agents over MCP.

View .md

A computer is one agent's browser profile (cookies, logins, local storage and a files directory) on one of your organisation's daemons. The cloud starts, stops and watches computers; the agent and its browser run on the daemon. See What a computer is for placement, hibernation and control.

What you can build

  • An agent that brings its own browser. On first run the agent calls computers_seat_create for its own computer, then computers_seat_start before each job and computers_seat_stop when it is done. Logins survive the stop.
  • A shared inbox browser. Create a shared computer, sign in to WhatsApp Web or a supplier portal once, and add the agents that need it with computers_member_add.
  • A hand-off for logins and 2FA. When the agent meets a login, a 2FA prompt or a CAPTCHA it calls computers_takeover_request; the computer shows Needs you and its owner is told.
  • An audit view. Read computers_activity_list (navigations by host, clicks, how much was typed but never what, downloads, takeovers) into your own log store. Activity is kept 30 days.

At a glance

Generated from the code on every docs build.

MCP endpoint https://cloud.usevenom.dev/workspace/mcp/computers, server name venom-computers
Connect claude mcp add --transport http venom-computers https://cloud.usevenom.dev/workspace/mcp/computers
MCP tools 36 (15 read, 21 write)
OAuth scopes computers:read computers:write
REST twin none yet
Webhook events none yet

Authentication and scopes

Computers needs the computers add-on (the Team plan and up). Without it every call answers 403 addon_required with an upgrade_url.

  • A personal API key or an OAuth grant acts as the member, with their org role's rights. OAuth apps need computers:read for the read tools and computers:write for the rest.
  • A team key bound to a service agent, or a key naming an agent with x-venom-agent, acts as that agent. It sees and uses its own computer and the shared computers it belongs to, creates its own computer only, and cannot archive a computer or change members.
  • A team key with no agent only reads.

Archiving a computer and changing a shared computer's agents need an org admin or the person who created it.

Worked example

An agent creates and starts its own computer, then asks for help at a login. $VENOM_TEAM_KEY is a team key (not marked "This key is mine"), and x-venom-agent names the agent it acts as (Naming agents on a shared key). A personal key would act as its member instead.

curl -X POST "$VENOM_CLOUD/workspace/mcp/computers" \
  -H "Authorization: Bearer $VENOM_TEAM_KEY" -H 'x-venom-agent: invoice-bot' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "computers_seat_create", "arguments": {"name": "Invoice bot", "format": "json"}}}'

Then, with the computer's id from that answer:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "computers_seat_start", "arguments": { "seat_id": "<seat-id>" } } }

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "computers_takeover_request",
              "arguments": { "seat_id": "<seat-id>", "reason": "Sign in to the supplier portal; it asks for a 2FA code." } } }

computers_seat_start answers the state the computer has: active, starting while the daemon has not answered, or queued with how many are ahead when the daemon is full. Read it again with computers_seat_get until it is active. After a takeover, wait until it is active again, then read the page and carry on. Never put passwords or codes in reason.

Errors worth handling: 409 no_capacity (no daemon has room for another computer), 409 seat_exists (the agent already has one: list it instead), daemon_offline and seat_archived.

Events

This product sends no org webhook events yet. Follow its changes with workspace_change_list where it has a change feed, or poll its list routes.

To follow a computer, poll computers_seat_get for its state or computers_activity_list with the previous page's before cursor.

REST routes

No REST routes yet: use the MCP tools.

The console's own API under /api/workspace/computers mirrors the tools for the signed-in browser session; it does not take API keys. Its routes are listed in Computers for agents.

MCP tools

36 tools: 15 read, 21 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.

Tool Title Access Scope REST route
computers_activity_list List a computer's activity read computers:read
computers_agent_get Read whether an agent uses a computer read computers:read
computers_agent_set Give an agent a computer write computers:write
computers_approval_decide Answer an approval or a takeover write computers:write
computers_approval_list List what agents wait on a person for read computers:read
computers_credential_create Save a login or card write computers:write
computers_credential_delete Revoke a saved login write (destructive) computers:write
computers_credential_list List saved logins read computers:read
computers_daemon_disable Disable Computers on a daemon write computers:write
computers_daemon_enable Enable Computers on a daemon write computers:write
computers_daemon_list List daemons and their Computers setup read computers:read
computers_member_add Add an agent to a shared computer write computers:write
computers_member_list List a shared computer's agents read computers:read
computers_member_remove Remove an agent from a shared computer write (destructive) computers:write
computers_routine_create Create a routine write computers:write
computers_routine_delete Delete a routine write (destructive) computers:write
computers_routine_get Read a routine read computers:read
computers_routine_list List routines read computers:read
computers_routine_rotate_secret Rotate a routine's secret write computers:write
computers_routine_run_get Read a routine run read computers:read
computers_routine_run_list List routine runs read computers:read
computers_routine_run_now Run a routine now write computers:write
computers_routine_update Change a routine write computers:write
computers_run_list List agents' runs on computers read computers:read
computers_run_stop Stop an agent's run write (destructive) computers:write
computers_seat_create Create a computer write computers:write
computers_seat_delete Archive a computer write (destructive) computers:write
computers_seat_get Read a computer read computers:read
computers_seat_list List computers read computers:read
computers_seat_start Start a computer write computers:write
computers_seat_stop Stop a computer write computers:write
computers_seat_update Rename or change a computer write computers:write
computers_tab_list List a shared computer's shared tabs read computers:read
computers_tab_share Mark a tab as shared write computers:write
computers_takeover_request Ask a person to take over write computers:write
computers_thumbnail_get See a computer's screen read computers:read

Every tool takes format: "json" for structured content and refuses arguments it does not list.