Working on Devboxes

Local development uses production's same-origin HTTPS shape: https://app.local.devboxes.ai serves the web app and /api, while https://docs.local.devboxes.ai serves the docs. The unified devboxes command covers terminal sign-in, dispatch, runner registration, health checks, and task execution. devboxes login signs in the terminal; devboxes connect registers the machine, reusing that session when it is valid.

How to test it

Start the local services, then apply the current schema and seed data:

docker compose up -d
pnpm dev
pnpm vp run @firops/api#db:migrate
pnpm vp run @firops/api#seed

Run the CLI from source against the local HTTPS edge:

pnpm vp run devboxes#devboxes:local -- login --api https://app.local.devboxes.ai/api
pnpm vp run devboxes#devboxes:local -- connect --api https://app.local.devboxes.ai/api
pnpm vp run devboxes#devboxes:local -- credentials setup --api https://app.local.devboxes.ai/api
pnpm vp run devboxes#devboxes:local -- doctor --api https://app.local.devboxes.ai/api
pnpm vp run devboxes#devboxes:local -- listen --api https://app.local.devboxes.ai/api

After doctor reports the runner ready, the Quickstart is the manual dispatch smoke.

Build the standalone CLI and prove its command surface separately:

pnpm vp run devboxes#build
pnpm vp run devboxes#bin:help

Full validation remains pnpm vp run validate:full. It adds the binary smoke, repository rules, OpenSpec validation, and E2E to the package suites. The feature entries below name the exact test files that prove each contract.

For docs changes, run both docs-owned checks:

pnpm --dir apps/docs run types:check
pnpm --dir apps/docs run build

Decisions

• Local traffic uses the HTTPS edge — the browser and CLI exercise the deployed same-origin boundary instead of a development-only proxy.
• login and connect keep separate identities — terminal approval grants user actions; machine registration grants runner actions. Reusing a valid login session avoids a second approval without collapsing those roles.
• One CLI suite owns the full command and runner contract — protocol, provider connection, credential, and Docker behavior move together instead of passing through separate package gates.
• Default candidate signoff is checks-only — it covers repository format, lint, and types; larger bundles use full validation for binary, package-suite, and E2E coverage.
• The docs keep their own dependency tree — docs changes cannot perturb the runtime workspace, while pnpm dev still presents one local product.

Next: Organizations, roles & access — the access substrate every feature below gates on.