Machines, desks and the sidecar
Three words name three different things in the factory. Mixing them up is the most common reason a check reads the wrong field.
machine ── the physical Linux host one machine_id
├─ desk A ── one sidecar, one place to work env_id A
└─ desk B ── a second sidecar on the same host env_id BMachine
The Linux host you own or rent. OPVS does not provision servers; you bring the host and the installer joins it. Two desks on one host report the same machine_id and different env_ids. opvs machines list shows this workspace's machines.
Desk
One environment on a machine: one sidecar, one id, one token, one place an agent works. The dashboard and the API also call it a workstation; the workstation id and the desk's environment id are the same value. Hiring a builder gives it a dedicated desk, so you rarely order one by hand.
A desk has a runtime, the agent program a person watches in its terminal: claude_code, codex or custom (custom launches nothing for you). The runtime is not the same as the harness a card is built with; a desk on one runtime can build cards pinned to another harness. See Builders and engines.
The dashboard terminal for a desk attaches to a session on the desk itself. Closing the browser tab does not end that session; opening the terminal again reattaches.
Sidecar
The OPVS program on each desk. It joins a private WireGuard network with OPVS, so no port on your host is opened to the internet. OPVS reaches the desk over that network; the sidecar listens on port 7682 inside it.
GET /health is the sidecar's only route that needs no token. OPVS polls it, and a desk becomes ready once it answers. Its main fields:
Field | What it tells you |
|---|---|
|
|
| This desk |
| The host. Empty means OPVS cannot place the host, and project secrets are withheld from the desk |
| The sidecar's version string |
| A fingerprint of the code this process is running. Two desks can share a version and differ here |
| The desk image: |
| The build loop: |
| Whether the desk's sign-in can be refreshed by OPVS, and when it expires. Never the token itself |
| CPU, memory and disk. Any field it cannot read is |
Desk states
State | Means |
|---|---|
| Ordered; waiting for the installer, or resumed after a pause |
| The sidecar answers the health check |
| Three health checks in a row were missed |
| Paused by you. Health polling stops and the desk keeps its place in your limit |
A desk OPVS has not heard from for more than two weeks is marked dormant. It stays in the list and no longer counts toward your workstation limit. A suspended desk is never dormant.
Scheduled prompts on a desk
opvs env routines schedules prompts into named agent sessions on one desk: list shows them with their last run, set replaces the whole list, and run starts one now (still skipped if that session is busy). set and run need a workspace admin.
Related: Set up your factory steps 1 to 4, Fix a machine or desk.