Computers

Computers let agents see and operate a graphical desktop. The Control Plane and the relay serve them in every deployment; this page covers what an operator turns on around that.

Turn on the consoleCopy Anchor Link

The console hides everything about Computers until its computer-use feature is on: the Computers section of Infra, a computer's page, the Computers card on an agent's Tools tab, and computer usage in Analytics.

Helm:

features:
  computerUse: true

Docker Compose: add computer-use to FEATURE_FLAGS in compose.env, then recreate web:

FEATURE_FLAGS=computer-use

docker compose --env-file compose.env up -d --force-recreate web

FEATURE_FLAGS is a comma-separated list, so keep the entries it already has.

What a desktop must reachCopy Anchor Link

A desktop only dials out. Whether it is a person's machine or a container, it needs:

These are the addresses a daemon uses: AGENTCONNECT_PUBLIC_CP_URL and AGENTCONNECT_RELAY_DAEMON_URL in the Compose stack. A stack that publishes them as localhost is reachable only from its own host, so publish it under an address other machines reach, as in Network and public URLs, before adding a desktop elsewhere.

Run a desktop containerCopy Anchor Link

The computer image is a Linux desktop with Chromium, LibreOffice and common language toolchains, running the same desktop daemon as a person's machine. It needs Docker on amd64 or arm64, about 2 GB of disk, and 1 to 3 GB of memory.

The quickest start is the docker run command on the Docker tab of Add computer; see Add a computer. Docker Compose keeps the settings in a file and makes upgrades one command:

mkdir agentconnect-computer && cd agentconnect-computer
base=https://raw.githubusercontent.com/agentconnect-md/agentconnect/main/packages/computer/docker
curl -fsSLO "$base/compose.yaml"
curl -fsSL "$base/compose.env.example" -o .env

Create a token with Add computer in the console, then set the two required values in .env:

AGENTCONNECT_CP_URL=https://cp.example.com
AGENTCONNECT_REGISTER_TOKEN=<one-time token>

docker compose up -d
docker compose ps        # STATUS turns (healthy) once the daemon passes its own checks

The volume holds the computer's key, its browser profile and its files:

• Upgrade. Set AGENTCONNECT_VERSION, then docker compose pull && docker compose up -d.
• Register again. After a revoke, put a new token in .env and run docker compose up -d.
• Remove. Delete the computer in the console, then docker compose down -v.
• Several desktops on one server. Give each its own directory, token and UDP range.

docker inspect shows a container's environment, so prefer AGENTCONNECT_REGISTER_TOKEN_FILE where that matters. The token is useless once spent.

The repository's desktop container guide covers secret files, host networking, and evaluating on the stack's own host.

Viewer videoCopy Anchor Link

Watching a computer needs nothing published: signaling and screenshots go through the relay over the desktop's outbound link. Without anything more, the viewer shows Screenshots, a few frames a second. Live video needs a path between the browser and the desktop:

STUN on the relay. Set the address browsers and desktops reach the host on, add the overlay, and open that UDP port:

AGENTCONNECT_STUN_HOST=203.0.113.10
# AGENTCONNECT_STUN_PORT=3479

docker compose --env-file compose.env -f compose.yaml -f compose.stun.yaml up -d

Peer to peer shows the desktop's public IP address to the viewer's browser, so each computer's Peer-to-peer viewing policy decides whether it is used.

TURN on the relay. Open the port for UDP and TCP; there is no secret to set and no port range:

AGENTCONNECT_RELAY_TURN_HOST=203.0.113.10
# AGENTCONNECT_RELAY_TURN_PORT=3480

docker compose --env-file compose.env -f compose.yaml -f compose.relay-turn.yaml up -d

The Control Plane mints short-lived credentials per viewer and per desktop, and the relay forwards video only between its own allocations. For networks that let only port 443 out, the relay can also serve TURN over TLS.

An external TURN server. compose.turn.yaml adds coturn and points the Control Plane at it:

AGENTCONNECT_TURN_SECRET=<openssl rand -hex 32>
AGENTCONNECT_TURN_EXTERNAL_IP=203.0.113.10

Open UDP and TCP 3478 and UDP 49160-49199 on that host, and run no other UDP service on that address. For Cloudflare Realtime TURN, set COMPUTER_TURN_CLOUDFLARE_KEY_ID and COMPUTER_TURN_CLOUDFLARE_API_TOKEN instead, without the overlay.

In the Helm chart, relay.stun and relay.turn each add one Service per relay pod and need a public host for it; the chart README lists every value.

Store screenshotsCopy Anchor Link

By default the screenshots agents take reach the model and are not kept. With storage on, the session timeline shows them, each computer's Keep screenshots policy sets how long, and the bytes go straight from the desktop to the bucket on signed URLs. The Control Plane signs and keeps metadata only.

Helm, with a Source Cache bucket configured:

computerScreenshots:
  enabled: true
  retentionDays: 30     # for a computer whose policy sets none
  maxRetentionDays: 365 # the most a computer's policy may ask for

Docker Compose: set AC_COMPUTER_SCREENSHOTS in compose.env to a one-line JSON document with the same bucket fields as AC_FILE_TRANSFER, plus an optional retention object with defaultDays and maxDays.

Expired screenshots are deleted by the Control Plane, so the bucket needs no lifecycle rule for them.

Cloud computers on KubernetesCopy Anchor Link

With the chart's daemon pool, the deployment can also create desktops itself. They appear in the console as Cloud computers: a member adds a shared one, or an agent gets one for each session or one of its own. See Cloud computers.

computerPool:
  enabled: true

It needs daemonPool.enabled and a public Control Plane URL (apiHost or publicUrl), because desktop pods register there.

A cloud computer's pod has no UDP port a browser can reach, so watching one uses TURN. Turn on relay.turn or computerViewer.turn for live video; without it the viewer shows screenshots.

Without your own limits, an organization may run 3 cloud computers at once, hold 10, and use 300 desktop hours a month. Usage appears under Analytics.