# Machines, desks and the sidecar

Source: https://opvs.ai/docs/factory/machines-and-desks

> The difference between a machine, a desk and the sidecar, and what the health check reports.

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 B
```

## Machine

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_id`s. `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](/developers/factory/builders).

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

`status`

`ok` whenever the page answers. It does not mean the desk will take work

`env_id`

This desk

`machine_id`

The host. Empty means OPVS cannot place the host, and project secrets are withheld from the desk

`version`

The sidecar's version string

`code_digest`

A fingerprint of the code this process is running. Two desks can share a version and differ here

`desk`

The desk image: `version`, `image_digest`, `input_hash`, `colour`. `null` for a sidecar installed straight on the host, never a guess

`worker`

The build loop: `enabled`, `draining`, `at_cap`, `inflight`, `max_concurrent_builds`, `harnesses`

`desk_credential`

Whether the desk's sign-in can be refreshed by OPVS, and when it expires. Never the token itself

`system`

CPU, memory and disk. Any field it cannot read is `null`

## Desk states

State

Means

`provisioned`

Ordered; waiting for the installer, or resumed after a pause

`active` (dashboard: ready)

The sidecar answers the health check

`unreachable`

Three health checks in a row were missed

`suspended`

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](/developers/factory/set-up) steps 1 to 4, [Fix a machine or desk](/developers/factory/fix-a-machine).