Deploying with rig deploy

rig deploy is the one command that takes a project on your machine and runs it as a live app in a Rigbox workspace. It reads a rig.yaml in the project directory, resolves a target workspace, syncs your code, and brings the service up behind a public subdomain. It is the single, consolidated deploy verb — it replaced the older rig app deploy and rig workspace deploy commands.

cd my-app
rig deploy

That’s the whole workflow for most projects. The rest of this guide explains what happens under the hood and how to control it.

How rig deploy resolves a workspace

rig deploy never makes you name a workspace by hand on every run. It resolves the target in this order:

--workspace <name|id> — an explicit flag always wins.
.rig.lock — a gitignored, per-project lock file that records the last workspace this project deployed to. If it exists, the redeploy reuses that same workspace.
Spawn a fresh workspace — if neither of the above applies, rig deploy creates and starts a new workspace, then writes it into .rig.lock so the next deploy reuses it. Pass --name <name> to choose the workspace name.

# First deploy in a new project — spawns a workspace named "my-app" and locks it
rig deploy --name my-app

# Later deploys — no flags needed; the lock points back at the same workspace
rig deploy

# Override the target for a one-off deploy
rig deploy --workspace staging-box

.rig.lock is per-project and should stay gitignored. It records where this project last deployed, so redeploys are idempotent and never spawn duplicate workspaces. Delete it (or pass --name) to start fresh against a new workspace.

The rig.yaml contract

rig.yaml is the source of truth for a deploy. CLI and UI edits to params are transient overlays — the next rig deploy re-applies whatever rig.yaml says.

Single-app shape

name: my-app
port: 8080
start: uvicorn app:app --host 0.0.0.0 --port 8080
install: |
  pip install --break-system-packages --no-cache-dir fastapi uvicorn
health:
  path: /healthz
  timeoutSeconds: 30
env:
  DATA_DIR: /home/developer/data
volumes: [data]
secrets:
  - name: STRIPE_KEY
  - name: SENTRY_DSN
    optional: true
credentials:
  - generate: true
params:
  - key: model
    type: select
    label: Model
    default: rigbox/default
    envVar: MODEL
    options:
      - { value: rigbox/default, label: "Default" }
      - { value: rigbox/fast, label: "Fast" }
visibility: public
workspace:
  image: base
  resources: { ramMb: 1024, vcpuCount: 1, diskSizeMb: 3072 }
  volumes:
    - name: data
      mountPath: /home/developer/data
      sizeMb: 1024

Field	Purpose
`name`	App name → public subdomain `name.rigbox.dev`.
`port`	The port your process listens on. Your `start` command must bind `0.0.0.0:<port>`.
`start`	The long-lived command run under systemd.
`install`	One-time setup run on the VM after the code syncs (build steps, dependency installs, migrations).
`health`	`{ path, timeoutSeconds }` — the platform gates on `GET <path>` → 2xx. See The health contract.
`env`	Plain environment variables.
`secrets`	`[{ name, optional? }]` — user-supplied secrets read from your local env at deploy time and injected. See Secrets.
`credentials`	`[{ generate: true }]` — the server mints a stable random value, injected as `CRED_<UPPER_KEY>`.
`params`	Server-validated config (types: `string`, `number`, `boolean`, `secret`, `select`, `email`, `url`, `textarea`).
`visibility`	`private` (default), `public`, or `{ emails: [...] }`.
`build`	Opt into a reproducible image build. See Deploy modes.
`source`	A git source for the build context (optional — the CLI uploads the local dir by default).
`volumes`	App opt-in mounts. Use workspace volume refs (`[data]`) or full app-local specs. See Persistent Volumes.
`workspace`	`{ image, resources, volumes }` — VM image/sizing plus reusable workspace volume declarations.

Multi-app shape

For a project that runs several services together, use a top-level workspace: block and an apps: map. Each app declares a path: to its directory plus its own inline spec.

workspace:
  image: base
  resources: { ramMb: 2048, vcpuCount: 2, diskSizeMb: 10240 }
  volumes:
    - name: data
      mountPath: /home/developer/data
      sizeMb: 1024
apps:
  api:
    path: ./api
    port: 5100
    start: uvicorn main:app --host 0.0.0.0 --port 5100
    install: pip install --break-system-packages -r requirements.txt
    health: { path: /healthz, timeoutSeconds: 30 }
    volumes: [data]
    env:
      DATA_DIR: /home/developer/data
  web:
    path: ./web
    port: 5101
    start: npm start
    install: npm ci && npm run build
    dependsOn: [api]
    visibility: public
    health: { path: /healthz, timeoutSeconds: 60 }

dependsOn: [api] injects RIGBOX_API_URL (the UPPER_SNAKE of the sibling app name) into the dependent app’s environment, pointing at the sibling over loopback. Boot order follows the dependency graph — api comes up before web. Here only the front door (web) is public; api stays private and is reachable only from web over the loopback URL.

Keep public surface minimal: mark only the user-facing app public and leave internal services at the default private. Dependents reach them via the injected RIGBOX_<NAME>_URL, not the internet.

The health contract

The platform gates every deploy on a health check. This is non-negotiable:

Your process must bind 0.0.0.0:<port> — never 127.0.0.1 or localhost, where <port> matches port:.
It must serve GET <health.path> → 2xx quickly. Use a generous timeoutSeconds: 30 for fast apps, 60–90 when install: does a heavy build (a Next.js or Rails build, for example).

If health never goes green within timeoutSeconds, the deploy is marked failed and rolled back — your previously running version stays up.

health:
  path: /healthz
  timeoutSeconds: 30

Deploy modes

rig deploy picks its mode from rig.yaml. There is no --reproducible flag — the presence of a Dockerfile (or prebuilt image) in build: is the only signal.

Standard deploy

With no build: block (or a build: that is just a shell command), rig deploy:

Rsyncs the app directory into the workspace.
Runs install: on the VM.
(Re)starts the service.

This is the default and fits most apps with fast installs.

name: my-app
port: 8080
start: node server.js
install: npm ci && npm run build
health: { path: /healthz, timeoutSeconds: 30 }

Reproducible deploy

A Dockerfile in rig.yaml makes the deploy reproducible automatically — no flag.

When build: declares a dockerfile (or a prebuilt image), rig deploy builds a content-addressed image that freezes the environment, boots the workspace from that exact image digest, and then rsyncs your app code on top.

name: ai-chat
port: 8080
build:
  dockerfile: Dockerfile
start: uvicorn chat:app --host 0.0.0.0 --port 8080
health: { path: /healthz, timeoutSeconds: 30 }

The Dockerfile must be FROM rigbox-base. The platform asserts that its agent and systemd are present and rejects any other base at build time, so you keep the platform’s opinions while layering your own dependencies on top.

# Dockerfile — must be FROM rigbox-base.
FROM rigbox-base
RUN pip install --break-system-packages --no-cache-dir \
      fastapi uvicorn pydantic httpx

The CLI uploads the local project directory as the build context, so no git repo is required. Install dependencies to system paths (e.g. pip --break-system-packages) so the rsynced code finds them. Keep your app’s own source out of the image — it arrives by rsync.

`build:` has three shapes

Shape	Mode	Meaning
`build: <command>`	Standard	A build command run on the VM after `install:`.
`build: { dockerfile, context?, sizeMb? }`	Reproducible	Build a content-addressed image from a local Dockerfile.
`build: { image, sizeMb? }`	Reproducible	Pull a prebuilt OCI image by reference.

The hybrid model: build once, rsync the rest

The reproducible path is hybrid — the slow, stable environment is built once and frozen into an image; fast-changing app code rides over it via rsync. The image is cached keyed by the build inputs — the install/build command, the Dockerfile contents, the base image, the git source, and dependency lockfiles — not your app code. So:

$ rig deploy
→ building image from Dockerfile (FROM rigbox-base)
  + pip install fastapi uvicorn pydantic httpx
→ image built: sha256:9f3c… (frozen)
→ booting workspace from image digest
→ rsyncing app code (chat.py, static/)
→ starting service · health GET /healthz → 200 OK
✓ deployed to https://ai-chat.rigbox.dev   (release rel_01…)

$ rig deploy
→ build inputs unchanged — reusing cached image sha256:9f3c…
→ rsyncing changed app code (chat.py)
→ restarting service · health GET /healthz → 200 OK
✓ deployed to https://ai-chat.rigbox.dev   (release rel_02…)

Editing the Dockerfile or a lockfile changes a build input, so the next deploy rebuilds the image. Editing only app code reuses the cached image and just rsyncs the change — no rebuild, no re-install.

Every reproducible deploy also auto-records a release (an image digest + run-config), so you can roll back later. See Releases & Rollback.

When to use which

install: (no Dockerfile) — simple apps with fast installs. The default.
build: { dockerfile } — heavier or slower environments you want frozen and byte-identical across deploys. rig deploy builds and mounts the image for you, and only rebuilds when the build inputs change.

Env, secrets, credentials, params, and visibility

These are all declared in rig.yaml and applied on every deploy.

env — plain environment variables baked into the unit.
secrets — [{ name, optional? }]. The value is read from your local environment at deploy time and injected into the VM (it is never stored in rig.yaml). Set optional: true to skip cleanly when unset.
credentials — [{ generate: true }]. The server mints a random value on first deploy, injected as CRED_<UPPER_KEY>, stable across redeploys.
params — server-validated config that is live-editable with rig app param set <key>=<value>. Every param the app reads must set envVar; select params require options: [{ value, label }].
visibility — private (default, gateway auth-gates every request), public, or { emails: [...] } (owner + allow-list). Declare it in rig.yaml so redeploys preserve it. See the Visibility guide.

export STRIPE_KEY="sk_live_…"   # picked up by secrets: [{ name: STRIPE_KEY }]
rig deploy

Blue-green deploys and promotion

For zero-downtime rollouts, stage a change, verify it, then swap production over atomically — either a whole-workspace clone (rig deploy --bluegreen preview) or an in-VM sibling (rig deploy --bluegreen <suffix>), each cut over with --promote. See Blue-green deploys & promotion for both flows, the service-host-vs-live-environment boundary, and rollback.

Deploy via the API

rig deploy orchestrates several REST calls. The image build step maps to the builds endpoint, and the resulting digest is recorded as a release. For endpoints without a dedicated command, rig api sends a raw authenticated request:

# Kick off an explicit image build (the deploy auto-build uses the same endpoint)
rig api POST /v1/builds --body - <<'JSON'
{ "dockerfile": "FROM rigbox-base\nRUN pip install --break-system-packages flask" }
JSON

See Releases & Rollback for the release lifecycle and the rig build command.

Next steps

Persistent Volumes — durable storage that survives redeploys and stop→start.
Releases & Rollback — pin and roll back image digests.
Visibility — private, public, and email-allow-listed apps.
Expose and Route — how apps map to subdomains.
The Rigbox CLI — the full command surface.

Getting Started

Concepts

Deploying & hosting

AI, automation & data

CLI Reference

Integrations & tools

Build on Rigbox

Deploying with rig deploy

How rig deploy resolves a workspace

The rig.yaml contract

Single-app shape

Multi-app shape

The health contract

Deploy modes

Standard deploy

Reproducible deploy

`build:` has three shapes

The hybrid model: build once, rsync the rest

When to use which

Env, secrets, credentials, params, and visibility

Blue-green deploys and promotion

Deploy via the API

Next steps

​How rig deploy resolves a workspace

​The rig.yaml contract

​Single-app shape

​Multi-app shape

​The health contract

​Deploy modes

​Standard deploy

​Reproducible deploy

​build: has three shapes

​The hybrid model: build once, rsync the rest

​When to use which

​Env, secrets, credentials, params, and visibility

​Blue-green deploys and promotion

​Deploy via the API

​Next steps

How rig deploy resolves a workspace

The rig.yaml contract

Single-app shape

Multi-app shape

The health contract

Deploy modes

Standard deploy

Reproducible deploy

`build:` has three shapes

The hybrid model: build once, rsync the rest

When to use which

Env, secrets, credentials, params, and visibility

Blue-green deploys and promotion

Deploy via the API

Next steps