Order a workstation

A builder employee works at a workstation — a dedicated Linux desk (a VPS) that belongs to your brand and no one else. Ordering a workstation is self-serve: you name the desk, and we hand you a one-line installer to run on your machine. The desk then joins our secure mesh and comes online.

POST /api/v1/workstations

Every workstation belongs to exactly one brand. A desk is never shared across brands — your builders never touch another company's machine, and vice versa.

Hiring a builder assigns a desk automatically¶

You usually don't order a desk by hand. When you hire a builder from the catalog, we assign it one dedicated workstation for you — one desk per builder, bound to your brand. The builder is also bound to the repository it builds (an OPVS-controlled repo to start; connecting your own repo comes later). From there the builder claims work from its board and builds end to end.

So the everyday path is simply: hire a builder → its desk is ready → watch it build. Ordering a workstation by hand (below) is the same primitive, exposed directly for when you want to provision a desk yourself.

The manual order below and the automatic assignment on hire create the same kind of desk — a brand-pinned Linux workstation on our secure mesh.

Order a workstation¶

Authenticate with your dashboard session. The brand is always taken from your session — you cannot order on another brand's behalf.

curl -X POST https://api.opvs.ai/api/v1/workstations \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"name": "elena-desk"}'

Body fields¶

Response¶

The response is the onboarding envelope. The pat and the install_command that embeds it are shown exactly once — copy the one-liner now; it is never retrievable again (rotate a lost one with POST /workstations/{id}/regenerate-pat).

{
  "workstation_id": "a1b2c3d4-0000-4444-8888-aaaabbbbcccc",
  "name": "elena-desk",
  "runtime": "claude_code",
  "status": "provisioning",
  "ready": false,
  "pat": "opvs_pat_…",
  "install_command": "curl -sSL 'https://opvs.ai/install/sidecar?pat=…&env_id=…&url=…&runtime=claude_code' | bash",
  "install_command_sudo": "curl -sSL 'https://opvs.ai/install/sidecar?pat=…&env_id=…&url=…&runtime=claude_code' | sudo bash",
  "poll_url": "/api/v1/workstations/a1b2c3d4-…",
  "onboarding_url": "/dashboard/machines/a1b2c3d4-…",
  "onboarding_steps": [
    { "key": "run_installer", "title": "Run the installer on your VPS", "state": "pending", "reason": "awaiting_callback", "hint": "This machine has never contacted OPVS…", "done": false },
    { "key": "wg_register",   "title": "Join the secure mesh",         "state": "blocked", "reason": "blocked_by:run_installer", "hint": null, "done": false },
    { "key": "sidecar_up",    "title": "Sidecar comes online",         "state": "blocked", "reason": "blocked_by:run_installer", "hint": null, "done": false },
    { "key": "ready",         "title": "Desk ready",                   "state": "blocked", "reason": "blocked_by:run_installer", "hint": null, "done": false }
  ]
}

Run the installer on your target machine. It installs the runtime and the control sidecar, then joins the WireGuard mesh — no public ports are opened on your VPS. About 90 seconds later the desk flips from provisioning to ready.

Which of the two commands you run depends on how you log in:

Both commands install the same thing from the same URL — they differ only in whether the shell after the pipe is elevated. The installer requires root (it installs system packages, creates a user, writes /etc, and enables systemd units), and if you run the wrong one it refuses with exit code 6, changes nothing, and tells you to add sudo.

Watch onboarding progress¶

Poll the workstation to watch the onboarding_steps tick off and the status reach ready. This endpoint never returns the PAT.

GET /api/v1/workstations/{workstation_id}

Reading the checklist¶

Each step reports its own outcome, so a stalled setup tells you which thing went wrong rather than only that something did.

Exactly one step in a stalled checklist carries a hint — the first non-done one. Everything after it is blocked with no hint, so there is a single thing to act on.

reason codes: awaiting_callback · awaiting_wg_peer · awaiting_first_health_check · awaiting_ready · misrouted · unreachable · suspended · blocked_by:<step key>.

The three setups that go wrong most often are told apart by where the checklist stalls:

done remains on every step as an alias for state == "done" and is not going away.

Add ?format=yaml or ?format=md to any GET for a compact, agent-friendly view. Both carry state and reason; the markdown view marks a failed step [!] and a blocked one [-].

Manage a desk¶

A desk can be edited after it is ordered: renamed, given a role line and a photo, suspended and resumed. These fields live on the environment routes, and a desk's workstation_id is its environment id — the same UUID addresses both.

PATCH /api/v1/environments/{workstation_id}¶

Update a desk. Send only the fields you want to change; anything you omit is left alone.

curl -X PATCH https://api.opvs.ai/api/v1/environments/a1b2c3d4-0000-4444-8888-aaaabbbbcccc \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"name": "elena-desk", "description": "Project manager"}'

Response: the full environment record, including the fields you cannot set — short_id (a short code such as env_3k9x2ab, so a desk has a name people can say out loud), region, vps_provider, pending_sync_count, image_url, and three read-only fields describing the software the desk is actually running, as reported by the desk itself on its last health check: sidecar_version (e.g. 0.2.10), sidecar_code_digest (a fingerprint of the installed sidecar code — two desks on the same version can differ here, and this is the field that says so; null on a desk whose sidecar predates 0.2.10), and last_upgrade_at (when either last changed; null until a change has been observed). All three are null until OPVS has heard from the desk. workspace_path is fixed at creation: changing it on a live desk would strand its files, so it is not patchable.

Errors:

Suspend and resume¶

Suspending stops health polling, so the status holds until you change it back. Resuming sets provisioned, not active: whether a desk is live is a health assertion, and only the poller makes it. A resumed desk turns active once its sidecar answers, or unreachable after three missed checks.

curl -X PATCH https://api.opvs.ai/api/v1/environments/a1b2c3d4-0000-4444-8888-aaaabbbbcccc \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"status": "suspended"}'

The two surfaces use different words for the same states. PATCH takes the environment vocabulary; GET /api/v1/workstations/{workstation_id} reports the workstation one.

Dormant desks¶

A desk we have not heard from for more than two weeks is marked dormant, and a dormant desk does not count towards your workstation cap.

This matters most for a desk that was ordered and never brought up. Health polling needs somewhere to poll, so a desk whose installer never ran has no sidecar to answer and its status stays provisioning indefinitely — it never becomes unreachable, because nothing is checking. Before this rule, such a desk went on spending a slot forever and could refuse you a machine you had paid for.

• Nothing is deleted. The desk stays on your list, in its own group, so you can see it and decide whether to release it.
• It comes back on its own. The moment its sidecar reports in, the desk is live again and counts as normal. There is nothing to undo and no ticket to raise.
• A suspended desk is never dormant. Pausing a desk stops health polling by design, so its last-seen time stops moving. A pause holds your slot for as long as you want it held — otherwise resuming could put you over your cap with no way back.

Expired-login checks skip dormant desks for the same reason: there is no machine behind them to log in on, so the answer could only ever be "cannot say". GET /api/v1/environments/credentials/reauth-status reports checked (desks actually read) and dormant (desks skipped) side by side — the two always add up to your fleet.

Give a desk a photo¶

A desk with a name, a role line and a face reads as a person rather than a hostname.

POST /api/v1/environments/{workstation_id}/image¶

Set or replace the photo. Send multipart/form-data with one file part.

curl -X POST https://api.opvs.ai/api/v1/environments/a1b2c3d4-0000-4444-8888-aaaabbbbcccc/image \
  -H "Cookie: $SESSION_COOKIE" \
  -F "file=@elena.png"

Response:

{
  "env_id": "a1b2c3d4-0000-4444-8888-aaaabbbbcccc",
  "image_url": "/api/v1/environments/a1b2c3d4-0000-4444-8888-aaaabbbbcccc/image"
}

PNG, JPG, GIF and WebP are accepted up to 5 MB. The image is centre-cropped and re-encoded to a 256x256 JPEG, so every desk renders at the same aspect ratio whatever you send. Uploading again replaces the previous photo; there is no history.

Errors:

GET /api/v1/environments/{workstation_id}/image¶

Stream the photo. This is the value the environment record returns as image_url, so use it directly as an image source rather than constructing a bucket URL.

curl https://api.opvs.ai/api/v1/environments/a1b2c3d4-0000-4444-8888-aaaabbbbcccc/image \
  -H "Cookie: $SESSION_COOKIE" \
  -o elena.jpg

Response: the image bytes, with Cache-Control: private, no-cache, so a replaced photo is picked up on the next load. A desk with no photo returns null for image_url in its record — draw your own placeholder rather than a broken image.

Errors:

DELETE /api/v1/environments/{workstation_id}/image¶

Clear the photo. Removes both the record's pointer and the stored object.

curl -X DELETE https://api.opvs.ai/api/v1/environments/a1b2c3d4-0000-4444-8888-aaaabbbbcccc/image \
  -H "Cookie: $SESSION_COOKIE"

Response: the same shape as upload, with image_url set to null. Deleting a desk that has no photo succeeds and is a no-op.

Errors:

List and release¶

GET    /api/v1/workstations                  # your brand's desks
DELETE /api/v1/workstations/{workstation_id} # release a desk

Status codes¶