---
title: Build on Computers
description: 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.
section: developers
order: 155
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/computers/mcp.ts, services/nodejs-cloud/lib/computers/http.ts, services/nodejs-cloud/lib/computers/index.ts, services/nodejs-cloud/app/api/workspace/computers]
features: []
---

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](/docs/computers/overview.md) for placement, hibernation and control.

## What you can build {#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 {#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 {#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 {#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](/docs/developers/auth.md#agent-header)). A personal key would act as its member instead.

```bash
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:

```json
{ "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 {#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 {#rest}

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](/docs/computers/agents.md#rest).

## MCP tools {#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.

## Related {#related}

- [What a computer is](/docs/computers/overview.md) and [Computers for agents](/docs/computers/agents.md).
- [Authentication and scopes](/docs/developers/auth.md), [MCP servers](/docs/developers/mcp.md) and [Errors, limits and pagination](/docs/developers/conventions.md).
