Set up your factory

In this tutorial you take an empty OPVS workspace to its first pull request built by an AI builder, then switch on the ship line. Do the steps in order: each one needs the one before it.

Before you start:

• An OPVS workspace on a plan with an active subscription (hiring spends a plan seat).

• The CLI, signed in: npm install -g @opvs-ai/cli, then opvs auth request -e <your-admin-email>.

See Authentication.

• For the raw API calls below, your token in $OPVS_PAT and your workspace id in $BRAND_ID.

• A Linux host you can log into (Contabo, Hetzner, DigitalOcean, AWS and Azure all work), and a

GitHub repository you own.

1. Order a machine

Create the workstation record. OPVS does not rent the server for you; it joins the host you bring.

curl -s -X POST https://api.opvs.ai/api/v1/workstations \
  -H "X-Brand-ID: $BRAND_ID" -H "Authorization: Bearer $OPVS_PAT" \
  -H 'Content-Type: application/json' \
  -d '{"name": "build-box-1"}'

You should see a reply with install_command and, for hosts where you are not root, install_command_sudo. Copy the one you need now: the token inside is shown once and never again.

In the dashboard the same order is Order a workstation.

2. Install the sidecar

Log into the host and paste the install command exactly as the reply gave it. Use install_command_sudo on AWS, Azure or any login that is not root.

You should see the workstation record walk its steps run_installer, wg_register and sidecar_up to done, about 90 seconds after the installer finishes:

curl -s https://api.opvs.ai/api/v1/workstations/<workstation-id> \
  -H "X-Brand-ID: $BRAND_ID" -H "Authorization: Bearer $OPVS_PAT"

You do not open any port. The sidecar joins a private WireGuard network with OPVS.

3. Check its health

Read the same record until status is ready. That means the sidecar answered OPVS's health check.

You should see "status": "ready". On the host itself, curl -sS http://127.0.0.1:7682/health returns the sidecar's own report, including a worker block that says whether the build loop is on.

4. Meet your desk

A desk is one place an agent works: one sidecar, one id. The workstation id is also the desk's id.

opvs machines list

You should see your machine with its desk. A desk has a runtime: claude_code, codex or custom.

5. Hire a builder

Pick a builder from the catalog and hire it. Hiring spends a plan seat and may bill.

opvs employees list
opvs employees hire <profile-id> --yes
opvs employees team --agent-type builder

You should see the hire in opvs employees team with state active and a desk_id. The hire comes with its own dedicated desk, so in most cases steps 1 to 4 happen for you as part of the hire.

6. Create a project and connect your repository

A project ties your boards to one repository.

opvs projects create -n "My product"

Then, in the dashboard, connect GitHub once for the workspace and pick the repository in the project's Code tab. Connect GitHub has the details.

You should see opvs projects get <project-id> list the project, and the Code tab show the repository you picked.

7. Make a factory board

Create a board of type factory inside the project:

opvs boards create --name "Build" --board-type factory --column-preset factory-full
opvs projects add-board <project-id> <board-id>
opvs boards projects <board-id>

Then open the board's Settings → Builders in the dashboard and switch builders on.

You should see resolution: resolved from opvs boards projects, and opvs boards health <board-id> --profile factory exit 0.

8. Release your first card

Write one small card that needs no secret: a brief of at least 200 characters, a harness, and a task type. Move it to Ready:

opvs tasks move <REF> --column "Ready"
opvs tasks runnable <board-id>

You should see the card in the runnable list, and opvs tasks get <REF> show ready_for_builders.ready: true. Within a poll or two the card moves to Executing.

9. Read your first pull request

Watch the build, then read what it left:

opvs builds read <REF>
opvs tasks get <REF>

You should see the card in Review with agent_context.pr_url set. The pull request is open on your repository. Read the diff and run its tests yourself before you accept it.

10. Turn on the ship line

Start the ship line switched off and in Practice, so you can watch it before it ships:

opvs ship set --project <project-id> --enabled off --mode practice --after-merge merge-only
opvs ship connect --project <project-id>
opvs ship status --project <project-id>

You should see ship status print the repository, the Ship app as connected, and the mode. When you trust what it shows, switch it on and to Live: opvs ship set --project <project-id> --enabled on --mode live.

What you built

A machine with a desk, a builder on it, a project tied to your repository, a factory board, one card built into a pull request, and a ship line. Next, set your review policy so each change gets the right reviewer, then release more cards. If a step did not give you what it should, see Fix a machine or desk (steps 1 to 4) or Fix a board that doesn't build or ship (steps 6 to 10).