Fix a machine or desk that won't come up
On this page
- The install command fails with exit code 6
- I lost the install command
- The checklist stops at "Run the installer" (awaiting_callback)
- The checklist stops at "Sidecar comes online" (misrouted)
- Should I open port 7682?
- The desk says unreachable
- Health says ok, but the desk takes no work
- Two desks run the same version but behave differently
- A new order is refused with 403
- Rename or pause a desk
- Still stuck
Use this page when a machine or desk from Set up your factory steps 1 to 4 does not reach ready, or reaches it and still takes no work. Start every check with the workstation record; it names the step that is stuck and why:
curl -s https://api.opvs.ai/api/v1/workstations/<workstation-id> \
-H "X-Brand-ID: $BRAND_ID" -H "Authorization: Bearer $OPVS_PAT"Read status and the first entry in onboarding_steps that is not done.
The install command fails with exit code 6
You pasted install_command on a host where you are not root. It changed nothing.
Fix: paste install_command_sudo from the same order reply. Do not put the token in front of sudo by hand: variables before sudo are dropped. Paste the command as a whole.
I lost the install command
The token inside it is shown once, and reading the workstation never returns it.
Fix: issue a new one with POST /api/v1/workstations/<workstation-id>/regenerate-pat, then use the install command from that reply.
The checklist stops at "Run the installer" (awaiting_callback)
The installer ran but never reached OPVS, usually because the host cannot reach the internet.
Fix: check the host's outbound network, then run the installer again. Later steps stay blocked until this one is done.
The checklist stops at "Sidecar comes online" (misrouted)
You ran the installer on a host that already carries a desk, with the command for a different desk.
Fix: two desks can share one host, but each needs its own order and its own install command. Run the command that belongs to this workstation.
Should I open port 7682?
No. The sidecar listens on 7682 only inside the private WireGuard network. From the public internet that port should not answer. Check health through the workstation record, or on the host itself with curl -sS http://127.0.0.1:7682/health.
The desk says unreachable
OPVS missed three health checks in a row. A desk still in provisioning with no installer run is different: nothing is polled, so it never turns unreachable by waiting.
Fix: on the host, check that the sidecar is running and answering /health, then read the workstation record again.
Health says ok, but the desk takes no work
status: ok only means the health page answered. Read the worker block in the sidecar's health:
Field | When it blocks work | What to do |
|---|---|---|
| The build loop is not running | Turn the worker on for this desk |
| The desk is finishing current builds and refusing new ones | Wait, or end the drain |
| It is already running | Wait for a build to finish |
| The desk's test gate refused, so this desk claims nothing | Read the rest of |
Also read desk_credential: it says whether the desk's sign-in is one OPVS can refresh, and when it expires.
Two desks run the same version but behave differently
version is the sidecar's version string. code_digest fingerprints the code the process is actually running. Two desks can share a version and differ in digest, for example after a half-applied upgrade. Compare version, code_digest and desk in each desk's health; the workstation record carries the same facts as sidecar_version, sidecar_code_digest and last_upgrade_at.
A new order is refused with 403
You are at your workstation limit. The reply carries limit_type, current and upgrade_url. A desk OPVS has not heard from for more than two weeks is marked dormant and does not count; a suspended desk keeps its place.
Fix: upgrade through upgrade_url, or remove a desk you no longer use.
Rename or pause a desk
curl -s -X PATCH https://api.opvs.ai/api/v1/environments/<workstation-id> \
-H "X-Brand-ID: $BRAND_ID" -H "Authorization: Bearer $OPVS_PAT" \
-H 'Content-Type: application/json' \
-d '{"name": "build-box-2"}'Send "status": "suspended" to pause health polling, and "status": "provisioned" to resume it.
Still stuck
Collect the workstation record and the sidecar's /health reply, and send them to support from the dashboard. Related: Machines, desks and the sidecar.