Sharing a computer
Let several agents use one browser so a site is logged into once, with turns on a shared tab, using WhatsApp Web as the example.
A computer is dedicated (one agent, the default) or shared (several agents use one browser). Share one when a site should be logged in once and every agent should use that login. WhatsApp Web is the usual case: it links at most four devices, and it allows one open tab per browser, so agents cannot each open their own. They take turns on one tab instead.
An agent can have both: its own dedicated computer, and membership in shared ones. It picks with the optional computer
argument of its browser tools (the default is its own).
Set it up (WhatsApp Web)
- Make a computer shared (
computers_seat_createorcomputers_seat_updatewithmode: shared; a person does this). - Add the agents that may use it (
computers_member_add,member: agent:<id>). - Start it, open the live view and take control. Open
web.whatsapp.comand scan the QR code with your phone. The login stays in the computer's browser profile. - Mark that tab shared (
computers_tab_share, or an agent does it withbrowser_tabsactionshare), then give control back. - Ask any member agent to send a message. It opens
browser_tabs, sees the tab marked[shared]and switches to it.
Agents on a shared computer share its logins and can use its shared tabs. Add only agents you would let send as that account.
What agents see
- Each agent sees only the tabs it opened itself and the shared tabs. It cannot see, attach to or close another agent's tab.
- A tab nobody owns, such as one restored when the browser starts or one you opened in the live view, is shared.
browser_tabsmarks shared tabs[shared], and[shared, in use by agent:x]while another agent has its turn.
Turns
A shared tab is used by one agent at a time, first come first served.
- A tool call that needs the tab waits for its turn on its own. The result says so ("Waiting for a turn on the shared tab (in use by agent:x), 2 in line") and carries on when it comes. After five minutes it gives up and says the tab stayed busy.
- The turn lasts one tool call, or one
browser_batch: the agent keeps it while the call runs and gives it back at the end. A turn also ends after 5 seconds with no command, or after 60 seconds in all, so a stuck agent cannot hold the tab. - When you take control in the live view you come first: the agents' turns are suspended and they wait, queued, until you give control back.
The computer is not hibernated while an agent holds or waits for a turn, or has a request running.
See who holds a tab
GET /api/workspace/computers/{id}/tabs and computers_tab_list give each shared tab with its URL, title, the agent that
has its turn now and how many wait, and whether a person has taken control.
Limits
- Turns serialize commands, not intent. An agent that navigates the shared tab away changes it for the next agent.
- A site that checks for a second tab sees none: only one tab of it is ever open, the shared one.
For operators and builders
The daemon sets the harness session's computers in its environment, never a tool argument:
VENOM_BROWSER_SEAT_NAMEnames the primary computer (defaultmain) andVENOM_BROWSER_SEAT_SHARED=1flags it shared.VENOM_BROWSER_SEATSis a JSON array of the others,[{"name","url","token","shared"}]: the shared computers the agent is a member of. With more than one computer the browser tools take acomputerargument naming one of them.
venom-seatd serves the console and the daemon on a shared seat (bearer token, internal network only):
GET /seats/{id}/tabslists the shared tabs with their holder and queue, and whether a person has control.POST /seats/{id}/tabs/{target}/sharemarks a tab shared on a person's say-so.POST /seats/{id}/controlwith{"held": true}tells the seat a person took control, andfalsegives it back.
Agents' own CDP clients use the same lease by the custom methods Venom.leaseTab, Venom.releaseTab, Venom.shareTab and
Venom.sharedTabs; a command on a shared tab without the lease fails with tab_leased (-32010). The design is in
ADR 0078 section 2a.