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.
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_createfor its own computer, thencomputers_seat_startbefore each job andcomputers_seat_stopwhen it is done. Logins survive the stop. - A shared inbox browser. Create a
sharedcomputer, sign in to WhatsApp Web or a supplier portal once, and add the agents that need it withcomputers_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:readfor the read tools andcomputers:writefor 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.