---
title: What a computer is
description: A computer is one agent's persistent browser on one of your daemons. How it is placed, started and stopped, who can see and control it, and what the cloud keeps about it.
section: computers
order: 10
audience: [user, operator, builder]
sources: [services/nodejs-cloud/lib/computers, services/nodejs-cloud/contracts/mesh-v1.schema.json, services/nodejs-cloud/migrations/0223_computers.sql, docs/adr/0078-venom-computers.md]
features: []
---

A **computer** (the code calls it a *seat*) is one agent's browser profile: cookies, logins, local storage and a files
directory, on one of your organisation's daemons. While the agent works, the computer is running a browser. When it is
idle, the browser closes and only the profile stays on disk, so a sleeping computer costs disk and nothing else.

The agent runs next to its computer, on the same daemon. Every click is a local call, the model calls go out through that
daemon's own gateway, and the cloud only starts, stops and watches. The cloud holds no connection open per agent.

## Dedicated and shared computers

- A **dedicated** computer belongs to one agent (its owner). An agent has one. The default.
- A **shared** computer is used by several agents on one browser profile, for example so WhatsApp Web is signed in once.
  An agent may have its own computer and also belong to shared ones. People add and remove the agents.

An agent sees and uses its own computer and the shared computers it belongs to, and no others. People see every computer
in the organisation.

## Placement

A new computer goes to the daemon of your organisation that reports it can host computers and has the most free seats
(its `max_seats` minus the computers it holds), among the daemons that are online and not draining. After that it stays
there, because its profile lives there. If no daemon has room, creating a computer answers `409 no_capacity`.

A daemon hosts computers when it runs with `VENOM_COMPUTERS=on` and Docker. It tells the cloud what it can hold in its
heartbeat (`capabilities.computers`; the contract is in `contracts/mesh-v1.schema.json`).

## States

| State | Meaning |
|---|---|
| `cold` | Never started, or stopped for good. Only the profile exists. |
| `starting` | The daemon is opening the browser. |
| `queued` | The daemon is full; the computer waits its turn and shows how many are ahead. |
| `active` | A browser is open and an agent is using it. |
| `idle` | A browser is open and nobody is using it. It hibernates after about ten minutes, unless someone is watching it. |
| `hibernating` | The browser is closed gracefully; logins stay. Starting it again resumes. |
| `needs_you` | The agent asked a person to take over. |

The daemon reports its computers' states in its heartbeat, so a computer it hibernated by itself, and every computer
after the daemon restarts, shows the right state within a heartbeat or two (about 10 to 20 seconds).

Starting is safe to repeat. Stopping keeps the profile. Archiving a computer removes its profile and files from the daemon,
and cannot be undone.

## Taking control

A person can **take control** of a computer for a login, a 2FA code, a CAPTCHA or a judgment call. Control is an exclusive
lease of five minutes that the viewer's page renews. While a person holds it, the agent's input tools wait; it may still
read the page. **Release** or expiry gives control back. An agent asks for a person with `computers_takeover_request`:
the computer shows **Needs you** and goes back to active when the person releases control. Agents never solve a CAPTCHA.

## What the cloud keeps

- The computers, their owner, members, daemon and state.
- An **activity** line per navigation (the host only), click, typing (how much, never what), shell command, download,
  approval, takeover, start and stop. Each is at most 200 characters, with anything that looks like a token, a password or
  a card number removed. Kept 30 days.
- The control lease. Short-lived thumbnails (under 40 KB, 60 seconds) when a person watches through the relay.

No page content, typed text or credential is stored in the cloud. The browser profile stays on your daemon.

## Who can do what

| Role | Computers |
|---|---|
| owner, admin | manage: everything, including archiving any computer and changing members |
| developer | create, start, stop, rename, take control; archive or change members of computers they created |
| billing, viewer | read |

An OAuth app needs `computers:read`, and `computers:write` to change anything. A read-only key only reads.

## The add-on

Computers is an add-on, `computers`, included in Team and up like the other products. While billing is off, or its price is
unset, every organisation has it. Without it every call answers `403 addon_required`.

## Limits

One dedicated computer per agent. At most 100 agents on a shared computer. A name is up to 80 characters. The reference
daemon (32 GiB, 8 vCPU) holds at least 100 computers, with at least 30 browsers open at once.
