Skip to content
Docs menu

Agents on computers

Give a Chat agent or a Tasks agent a computer. Its mentions and delegations then run on its own browser on your daemon, ask you before risky actions, call you in for a login or a CAPTCHA, and stop at their daily limit.

View .md

Without a computer, a Chat agent or a Tasks agent works in the cloud: it reads, calls the model and answers. With Use a computer on, the same mention or delegation runs as a Venom session on the daemon that holds the agent's computer, next to its browser. The agent signs in once, stays signed in, and works while your laptop is closed. Agents without a computer run in the cloud exactly as before.

Turn it on

  • Chat. A channel owner opens the channel's details, Venom agent, and ticks Use a computer. The agent in that channel gets its own computer (named "Venom in #channel"), so a private channel's logins stay in that channel.
  • Tasks. An org admin gives a service agent a computer (computers_agent_set with kind: "tasks"). Delegating an issue to it then starts a run on its computer.

Turning it off keeps the computer and its logins; turning it on again attaches the same one. Archive the computer from Computers to remove the profile. If no daemon has room, turning it on answers 409 no_capacity like creating a computer does.

What starts a run

  • A Chat mention. The Working… reply appears in the thread and shows each step as a plain line ("opened example.com", "read the page", "typed 12 characters"). Typed text is never shown. The reply becomes the answer. Stop and Re-run work as for any agent reply, and editing your message runs it again.
  • A Tasks delegation. When an issue is created with, or changed to, a delegate that has a computer, the agent starts with the issue and its recent comments as context. Its questions and its result are comments by the agent. It holds the issue's claim while it works and lets go when it ends. An agent that claims an issue itself over MCP does not start a second run.
  • Routines (schedules, email, webhooks) start the same kind of run through one entry point, startComputerRun.

Runs on one computer go one after another, because it is one browser. A run waits up to ten minutes for a computer that is starting or busy, and up to ten for an offline daemon, then says why it could not start.

It asks before it acts

The browser has a policy that asks a person before the first action on a site, on a credential or payment field, on a form submit that sends something, and on foreign frames, uploads and downloads. In a run that was started from the cloud, each of those becomes an approval shown where you asked: in the Chat thread, on the issue (Waiting for you), and in the bell.

Button What happens
Allow once This action goes ahead.
Allow on example.com This action goes ahead, and the site is remembered for this computer's later runs. Offered only when the browser offers a rule for it: a payment, a password, a submit that sends something and an upload always ask again.
Decline The agent is told a person declined. It does not retry the action; it takes another way or says it could not.

An ask nobody answers in 30 minutes counts as a decline (sooner if the browser gives up first), and the agent carries on without it. The person who asked for the run, or anyone who may use the computer, can answer; an agent never answers its own asks.

Needs you

When the agent hits a login, a 2FA code, a CAPTCHA or a judgment it cannot make, it asks for a person and waits. The computer shows Needs you, the thread or issue shows the reason, and the bell has a row. Take control of the computer in its live view, do the step, then press I'm done (or Skip to leave that part). The agent reads the page again and carries on. Agents never solve a CAPTCHA themselves. A takeover nobody answers in 30 minutes is skipped.

The 30 minutes is the cloud's bound. The daemon's venom serve gives up on an ask sooner: after 10 minutes with its default settings (--approval-timeout, capped at 10 minutes unless the daemon raises it).

Bots

A bot with a computer of its own runs its routines here too, with three differences:

  • Its autonomy applies. With Act without asking, ordinary approvals in its run are answered for it (a run started by a schedule, by hand or by an event, or by an email or a webhook whose routine trusts what arrives), at most 20 a run, each listed in the run's steps as approved by autonomy. Ordinary means a plain browser step on the site the ask names (opening a page, a click, typing, a form that sends) or a call to Venom's own tools; anything else waits for its owner: a takeover, password and code fields, payment forms, uploads, downloads, files, a shell command, another server's tool, or an ask Venom can't place. With Ask me first, everything waits for the owner, as for any agent.
  • Its owner hears of every ask by push notification.
  • A run nobody came for is parked, not lost: the computer run ends with what it could do, and the bot's run waits under Needs you on the bot's page for up to 12 hours. Continue starts a fresh computer run told what happened. See Bots → A bot with its own computer.

A bot can also send messages from WhatsApp Web or LinkedIn logged in on its computer: see Bots that reach out.

Cost

A computer run counts toward a daily limit per agent: the agent's own (daily_cap_usd, set next to Use a computer), else the organisation's limit for Chat agents (chat_ai_daily_cap_usd, default $1, changed on the AI spend page, which also counts every agent's spend today). The cost is what the session's model calls report. When the limit is reached the run stops and the thread or issue says so; a run started after that is skipped with the same words. A limit of 0 stops every run.

What is stored

A run keeps its prompt, the steps (a host and a verb each), the answer and the cost. An approval keeps the action as the browser described it, scrubbed of anything that looks like a secret. The computer's activity feed gets a line for each approval and takeover. Nothing typed into a page is stored.

For agents and scripts

Tool REST Does
computers_agent_get, computers_agent_set GET, PUT /api/workspace/computers/agents Whether an agent uses a computer (kind chat with ref the channel id, or tasks with the agent id), its daily_cap_usd, the cap in force and today's spend.
computers_approval_list GET /api/workspace/computers/approvals Pending asks first. Filters status (pending or all), seat_id, run_id, issue_id.
computers_approval_decide POST /api/workspace/computers/approvals/{id} decision: allow_once, allow_site, decline for an approval; done, skip for a takeover. 409 expired after 30 minutes.
computers_run_list GET /api/workspace/computers/runs Runs, newest first, with status, steps, answer and cost.
computers_run_stop DELETE /api/workspace/computers/runs/{id} Stop a run: the agent is aborted and its pending asks are cancelled.

A run's status is queued, working, needs_you, done, failed, stopped or skipped.

For builders

startComputerRun({tenant, agentRef, prompt, context, requestedBy, source, dedupeKey}) in lib/computers/agent-runs.ts is the one entry point: "run this agent with this prompt and this context". source says where progress and the result go, through a sink registered with registerRunSink(kind, sink) (progress(view) and finish(view, outcome)); Chat and Tasks are built in, and a routine registers its own. dedupeKey makes a trigger idempotent. The cloud never holds a request open per agent: the run is a row, and a driver advances it from the request that queued it and from the minute cron computer-runs.

The session is created on the seat's daemon with computer: {seat_id} and no cwd: the daemon roots it in the seat's work directory, runs it in default mode, and passes the seat's address to the harness in its environment (VENOM_BROWSER_CDP, VENOM_BROWSER_CDP_TOKEN, VENOM_BROWSER_CLIENT_ID; the mesh contract is docs/cloud-mesh.md §6.9 in the repository). Approvals are the session's approval_request events, answered through POST /v1/sessions/{id}/approvals/{approvalId}; a takeover is the agent's ask_user with the header "Needs you", answered through …/questions/{questionId}.