The Rigbox CLI - Rigbox API

The rig CLI (and its rigbox alias — the same binary) is the primary way to deploy and operate Rigbox from a terminal. It is pre-installed in every workspace VM, and you can install it on your local machine too. This page is the command reference. It is organised as:

Install & authenticate

Get the binary and log in.

Global flags

Output formats, JMESPath queries, scripted input, and rig api.

Deploy & rig.yaml

rig deploy, .env loading, and the full manifest schema.

Command groups

workspace, app, snapshot, volume, build/release/rollback, and more.

Install

Inside a workspace

The CLI is already installed in every Rigbox workspace. Open a terminal and run:

rig --version

Inside a workspace, rig automatically switches into workspace-scoped mode (see Runtime modes). You do not need to log in, and account-wide commands are intentionally hidden.

On your local machine

Install the latest release with one command:

curl -fsSL https://rigbox.dev/install.sh | bash

The installer detects your OS and CPU, downloads the latest release, and installs both rig and rigbox to $HOME/.local/bin. Confirm with rig --version.

Pin a version or change the install directory

For CI or reproducibility, the installer honours two environment variables:

Variable	Purpose	Default
`RIG_INSTALL_DIR`	Install location for the binary.	`$HOME/.local/bin`
`RIG_VERSION`	Pin to a specific release tag (e.g. `v0.12.33`).	`latest`

curl -fsSL https://rigbox.dev/install.sh | \
  RIG_INSTALL_DIR=/usr/local/bin RIG_VERSION=v0.12.33 bash

The env vars must sit on the bash that runs the script — not on the curl. In a pipeline, RIG_VERSION=… curl … | bash would set them on curl and the installer would still see the defaults.

Shell completions

rig completions --install        # detect your shell and wire it up
rig completions bash --no-rc     # print the script instead of editing your rc

To remove the local install entirely, use rig uninstall (add --purge-config to also drop saved credentials).

Authentication

Log in (local machine)

rig login

This opens your browser for OAuth and stores the token locally. Two non-interactive variants exist for headless environments:

rig login --token            # paste a token instead of opening a browser
rig login --import-token     # read a token from stdin and validate it

rig logout removes saved credentials (--purge also clears legacy config paths). rig whoami prints the current user and workspace.

External CLI configuration is stored in ~/.rigbox/config.json, including your auth token and persisted defaults.

API keys

API keys (rb_…) are full-account credentials, shown once at creation and stored hash-only:

rig api-key create --name ci-runner   # plaintext printed once — copy it now
rig api-key ls
rig api-key rm --id <KEY_ID>

Runtime modes

The CLI behaves differently depending on where it runs:

Context	Auth method	Command surface
On your local machine	OAuth token via `rig login`	Full account + workspace control
Inside a workspace VM	Ambient workspace identity from the VM bridge	Workspace-local commands only

Inside a workspace, rig detects /etc/rigbox/workspace.json and talks to the VM-local bridge at http://172.16.0.1:9090/rig/v1. No bearer token is sent — the bridge resolves your workspace from the VM’s source IP, so editing local config cannot switch identity. Account-wide commands (login, most workspace subcommands, template, recipe, ssh) are hidden in this mode; deploy, app, snapshot, volume, tools, and proxy helpers remain available.

Global flags

Every command accepts these global flags (they work before or after the subcommand):

Flag	Purpose
`--output <human\|json\|yaml>`	Output format. Defaults to `human`; set a persistent default with `rig config set output yaml`.
`--query <JMESPATH>`	Filter/transform the structured output with a JMESPath expression.
`--cli-input-json <FILE>`	Read command inputs from a JSON file, or `-` for stdin.
`--cli-input-yaml <FILE>`	Read command inputs from a YAML file, or `-` for stdin (conflicts with `--cli-input-json`).
`--generate-cli-skeleton`	Print a fillable input template for the command, then exit.
`--no-pager`	Do not pipe help output through a pager.

rig workspace ls --output json --query "[?status=='running'].name"
rig workspace spawn --generate-cli-skeleton > spawn.json
# edit spawn.json …
rig workspace spawn --cli-input-json spawn.json

Persisted defaults

rig config set output yaml     # default output format for every command
rig config get output
rig config list
rig config unset output        # revert to the built-in default

Raw API access

rig api sends an authenticated request to any Rigbox API path, reusing your stored credentials:

rig api GET /v1/workspaces
rig api POST /v1/snapshots --body snapshot.json      # JSON body from a file
echo '{"name":"x"}' | rig api POST /v1/snapshots --body -   # or from stdin

Deploy

rig deploy is the core workflow. It reads a rig.yaml in the project directory, rsyncs your source into a workspace VM, runs the install/build steps, and brings the app up as a managed systemd unit reachable at <slug>.rigbox.dev.

rig deploy                              # deploy cwd into its bound/auto workspace
rig deploy --from-dir ./service         # deploy a specific directory
rig deploy --workspace my-project       # target a named/id'd workspace
rig deploy --name my-project            # name to use when spawning a fresh workspace
rig deploy --app api                    # multi-app project: deploy only one app
rig deploy --watch                      # re-deploy on source changes (single-app)

When --workspace is unset, deploy reuses the workspace bound in .rig.lock, or spawns a fresh one. rig deploy --prune-stale drops .rig.lock bindings to workspaces that no longer exist, then exits without deploying.

rig.yaml is the source of truth. A redeploy re-applies everything declared in it — including visibility, limits, and volumes — so transient CLI/UI edits get overwritten on the next deploy.

Loading `.env` files

Deploy auto-loads dotenv files from the project directory and merges them into the environment used to resolve secrets: and env:. Disable with --no-env-file.

rig deploy --stage production

With --stage <name> (or $RIG_ENV), deploy loads stage-specific files. Precedence, highest to lowest:

real shell environment
.env.<stage>.local
.env.local
.env.<stage>
.env

Blue-green and promote

Stage a change as a sibling app, verify it, then swap production traffic atomically:

rig deploy --bluegreen v2              # deploy as <base>-v2 with its own subdomain
rig deploy --bluegreen v2 --promote    # stage then swap production in one transaction

--promote requires --bluegreen. The previous production app is retained as a rollback target until you delete it.

Scaffold a manifest

rig init                               # scaffold rig.yaml in cwd
rig init --name my-api --port 8080 --from ./service --force

The rig.yaml manifest

rig.yaml describes the app(s) to deploy. Multi-word fields use camelCase primarily, with snake_case accepted as an alias. There are two surface forms.

Single-app form

Three fields are required: name, port, and start (with install needed in practice for anything with dependencies).

name: notes-api               # required — slugified to the subdomain (a-z0-9-, 2–64 chars)
port: 5000                    # required — port the app listens on
start: gunicorn app:app       # required — the systemd ExecStart command
install: pip install -r requirements.txt   # dependency install (runs server-side)
build: python manage.py collectstatic       # optional — runs after install, before start

env:                          # static env vars baked into the unit
  LOG_LEVEL: info

secrets:                      # forward local env vars into the deploy (read at deploy time)
  - STRIPE_KEY                          # forward $STRIPE_KEY as STRIPE_KEY
  - { name: APP_DB, from: DATABASE_URL } # forward $DATABASE_URL as APP_DB
  - { name: SENTRY_DSN, optional: true } # skip (don't fail) if unset locally

credentials:                  # platform-generated values injected as env vars
  api_key:
    generate: true            # mint a random value on first deploy
    envVar: NOTES_API_KEY     # runtime var name (defaults to CRED_<UPPER_KEY>)

health:                       # HTTP readiness probe (defaults to GET / with a 60s budget)
  path: /healthz              # must start with /
  timeoutSeconds: 30

dependsOn: [postgresql, redis-server]   # workspace backing services this app needs
restartPolicy: on-failure     # always (default) | on-failure | no
workingDirectory: /opt/notes  # where the payload is extracted (default: ~/.rigbox/deploys/<slug>)
protocol: http                # http (default) | https | tcp

visibility: private           # private (default) | public | privileged allow-list
# visibility:                 # privileged form — owner plus listed emails
#   emails: [alice@example.com, bob@x.dev]

source:                       # where the code comes from
  kind: git                   # local (default; rsync the dir) | git (clone on the VM)
  repo: https://github.com/you/repo.git
  branch: main

ai:                           # opt this app into the managed AI proxy
  managed: true
  providers: [openai]         # defaults to [openai]; injects OPENAI_BASE_URL/_API_KEY

params:                       # user-configurable knobs surfaced in the workspace UI
  - key: max_items
    label: Max items
    description: Upper bound on returned rows
    type: number              # string (default) | number | boolean | secret | select | email | url | textarea
    default: "100"
    required: false
    envVar: MAX_ITEMS         # surface the value as this env var on the unit
    group: Limits
    order: 1
  - key: tier
    label: Plan tier
    type: select
    default: free
    options:
      - { value: free, label: Free }
      - { value: pro,  label: Pro }

limits:                       # per-app runtime caps applied to the systemd unit
  memoryMaxMb: 2048           # systemd MemoryMax
  cpuPercent: 150             # CPUQuota as percent of one core (150 = 1.5 cores)
  tasksMax: 100               # systemd TasksMax

volumes:                      # persistent volumes mounted into the app
  - name: data
    mountPath: /var/lib/data
    sizeMb: 4096

secrets: values are read from your local shell at deploy time. Deploy fails fast (before anything ships) if a non-optional secret is unset, so you can export them all in one go.

Field reference

Field	Type	Notes
`name`	string	Required. Slugified (`[a-z0-9-]`, 2–64 chars) to form the subdomain.
`port`	number	Required. Port the app listens on.
`start`	string	Required. systemd `ExecStart`.
`install`	string	Dependency-install command, compiled into the server-side install script.
`build`	string	Build command run after `install`, before start.
`env`	map	Static env vars baked into the unit.
`secrets`	list	Local env vars forwarded at deploy time (`NAME`, `{name, from}`, or `{name, optional}`).
`credentials`	map	Platform-minted values (`generate`, `envVar`).
`health`	object	`path` (must start `/`), `timeoutSeconds` (default 60).
`params`	list	UI knobs — see field list below.
`dependsOn`	list	Workspace services that must be alive.
`restartPolicy`	string	`always` (default), `on-failure`, `no`.
`workingDirectory`	string	Payload extraction path.
`protocol`	string	`http` (default), `https`, `tcp`.
`visibility`	string/object	`private` (default), `public`, or `{ emails: [...] }`.
`source`	object	`kind: local` (default) or `kind: git` with `repo`/`branch`.
`ai`	object	`managed: true` + optional `providers` to route through the AI proxy.
`limits`	object	`memoryMaxMb`, `cpuPercent`, `tasksMax` (all optional).
`volumes`	list	`name`, `mountPath`, `sizeMb` per entry.
`publish`	object	Metadata for `rig publish` (`vendor`, `slug`, `version`, `summary`, `tags`, …).

Each params: entry accepts: key (required), label, description, type (string default, number, boolean, secret, select, email, url, textarea), default, required, sensitive, options (for select: {value, label}), group, order, helpUrl, validationPattern, and envVar (surface the value as this env var on the unit — without it the value lands in metadata but the process can’t see it).

Multi-app form

A top-level apps: map switches to project form: an optional workspace: envelope plus a name-keyed map of apps. Each app is either a local build context (path:) or a published recipe (ref:).

workspace:
  image: dev                  # base template/image for the VM
  resources:
    ramMb: 4096               # workspace VM resources (all optional)
    vcpuCount: 2
    diskSizeMb: 20480
  env:                        # merged UNDER each app's own env (app wins per key)
    SHARED_FLAG: "1"

apps:
  api:
    path: ./api               # local build context (relative to project dir)
    port: 8080
    start: node server.js
    install: npm ci
    dependsOn: [postgresql]
  worker:
    path: ./worker
    start: python3 worker.py
    install: pip install -r requirements.txt
    dependsOn: [api]          # topo-ordered against sibling apps
  cache:
    ref: "@vendor/redis@1.2.0"  # launch a published recipe by ref instead of building

Every entry under apps: accepts the same inline fields as the single-app form (minus name, which is the map key). dependsOn is topo-sorted across siblings. Mixing single-app keys (start/port at the top level) with apps: is rejected.

Command reference

Placeholders use <WORKSPACE> (a name or ws-… id) and <APP> (a name or app-… id). Most lifecycle commands accept either form.

Account

Command	Description
`rig login` / `rig logout`	Authenticate / clear credentials.
`rig whoami`	Show the current user and workspace.
`rig status`	Dashboard summary for the account (quota, usage).
`rig limits`	Effective resource limits and current usage.
`rig capacity`	Fleet workspace-slot capacity.
`rig api-key create\|ls\|rm`	Manage account API keys.
`rig ai defaults`	Set account AI defaults (`--provider`, `--model`, `--mode managed\|byok`).
`rig ai usage`	Show AI usage history.
`rig config set\|get\|unset\|list`	Persisted CLI defaults.
`rig completions`	Generate/install shell completions.
`rig uninstall`	Remove the local CLI install (`--purge-config`).

workspace

Manage workspace lifecycle and configuration.

rig workspace ls
rig workspace spawn --name my-project --template dev --auto-size
rig workspace new   --name my-project --template dev      # create without starting
rig workspace start --workspace my-project --wait-for-apps
rig workspace stop  --workspace my-project
rig workspace restart --workspace my-project
rig workspace logs  --workspace my-project --follow
rig workspace rm    --workspace my-project --force

Subcommand	Key flags	Description
`ls`	—	List all workspaces.
`spawn`	`--name`, `--template`, `--ram`, `--vcpu`, `--disk`, `--catalog` (repeat), `--env`, `--setup-script-id`, `--service-spec-id`, `--app-param`, `--wait-for-apps`, `--auto-size`	Create and start in one step.
`new`	`--name`, `--template`, `--ram`, `--vcpu`, `--disk`, `--catalog`, `--setup-script-id`, `--service-spec-id`	Create without starting.
`start` / `stop` / `restart`	`--workspace`, (`--wait-for-apps` on start)	VM lifecycle.
`rm` / `cancel` / `retry`	`--workspace`, `--force`	Delete, cancel in-progress creation, retry a failed creation.
`logs`	`--workspace`, `--follow`	Stream workspace logs.
`ssh-info`	`--workspace`	Print the canonical SSH connection info.
`metrics`	`--workspace`	Live CPU/RAM/disk.
`services`	`--workspace`	Background services tracked in the workspace.
`ports`	`--workspace`	Ports the workspace is listening on.
`resize`	`--workspace`, `--ram`, `--vcpu`, `--disk`	Resize VM resources.
`reconcile`	`--workspace`	Reconcile apps with the template.
`env set\|unset\|get`	`--workspace`, (`--reveal` on get)	Workspace env vars.
`ai mode\|show`	`--workspace`, (`--reveal` on show)	Workspace AI configuration.

rig workspace rm permanently destroys the VM and its disk. Back up anything important first.

app

Manage apps inside a workspace. Inside a VM these are always scoped to the current workspace.

rig app ls --workspace my-project
rig app new --name my-api --port 3000 --kind service
rig app logs --app my-api --follow
rig app start --app my-api
rig app share --app my-api --public
rig app rm --app my-api

Subcommand	Key flags	Description
`ls`	`--workspace` (optional)	List apps in a workspace or across all.
`new`	`--name`, `--port`, `--kind service\|cli`, `--workspace`, `--description`	Create an app.
`start` / `stop` / `restart`	`--app`	App lifecycle.
`logs`	`--app`, `--follow`	Stream app logs.
`rm`	`--app`, `--workspace`, `--force`, `--force-delete`	Delete an app.
`share`	`--app`, `--public` / `--private` / `--emails a,b,c`	Set route visibility (pick one mode).
`health`	`--app`	Show runtime health.
`expose-port`	`--workspace`, `--port`, `--name`, `--wrap`	Detect or expose a workspace port as an app.
`domain set`	`--app`, `--domain`	Attach a custom domain.
`verify-domain`	`--app`	Re-check DNS for a custom domain.
`param ls\|get\|set\|unset`	`--app`, then `key`/`KEY=VALUE`	Read and write catalog-app parameters.
`log-source ls\|add\|update\|rm`	`--app`, `--type`, `--ref`, `--name`, `--primary`, `--source`	Manage app log sources (`systemd_unit`, `docker_container`, `file_path`).

rig app new --kind is service (long-lived server at a subdomain) or cli (interactive binary over SSH, no Caddy route). See Catalog Apps.

snapshot

rig snapshot create  --workspace my-project --name pre-upgrade
rig snapshot ls      --workspace my-project       # omit --workspace to list all
rig snapshot restore --workspace my-project --snapshot <SNAP_ID>
rig snapshot rm      --workspace my-project --snapshot <SNAP_ID>

See the Snapshots guide for the full model.

volume

Manage persistent volumes that survive across deploys and reboots.

rig volume create --workspace my-project --name data --size-mb 4096 --mount-path /var/lib/data
rig volume ls     --workspace my-project          # omit --workspace to list all
rig volume resize --workspace my-project --volume <VOL_ID> --size-mb 8192
rig volume rm     --workspace my-project --volume <VOL_ID>

You can also declare volumes inline in rig.yaml under volumes: so a deploy provisions and mounts them automatically.

volume commands back the PersistentVolumes server feature. They may be unavailable until that feature flag is enabled for your account.

build, release, rollback

Reproducible deploys separate build (produce an immutable image artifact) from run (activate a release that pins an image digest).

# Build an immutable image for a workspace
rig build --workspace my-project --base-image dev \
  --install "npm ci && npm run build" \
  --source-repo https://github.com/you/repo.git --source-commit "$(git rev-parse HEAD)"

# Pin that image digest into a release
rig release create --workspace my-project --image-digest sha256:… \
  --run-config '{"execStart":"node server.js","port":3000}'

rig release ls --workspace my-project
rig release activate --workspace my-project --release <RELEASE_ID>

# Roll back = activate a prior release (alias for `release activate`)
rig rollback --workspace my-project --release <RELEASE_ID>

Command	Key flags	Description
`build`	`--workspace`, `--base-image`, `--install`, `--source-repo`, `--source-commit`	Build a reproducible image and print its digest.
`release create`	`--workspace`, `--image-digest`, `--run-config`	Create a release pinning an image digest.
`release ls`	`--workspace`	List releases for a workspace.
`release activate`	`--workspace`, `--release`	Activate a release.
`rollback`	`--workspace`, `--release`	Activate a release (rollback alias).

build, release, and rollback back the ReproducibleBuilds server feature. They may be unavailable until that feature flag is enabled for your account.

ssh

Manage SSH public keys for your account.

rig ssh add  --name laptop --file ~/.ssh/id_ed25519.pub
rig ssh ls                          # account keys; add --workspace to list workspace keys
rig ssh rm   --name laptop
rig ssh sync --workspace my-project  # push your keys into a workspace

A handy one-liner combines ssh-info with your SSH client:

ssh "$(rig workspace ssh-info --workspace my-project --output json | jq -r .ssh_target)"

See the SSH Access guide for the full connection model.

tools

Launch and manage interactive workspace tools (architecture explorer, virtual browser, …).

rig tools ls       --workspace my-project
rig tools launch   --tool architecture-explorer --workspace my-project
rig tools stop     --tool architecture-explorer --workspace my-project
rig tools install  --workspace my-project --tool virtual-browser
rig tools install-status --workspace my-project --tool virtual-browser --job-id <JOB_ID>

template

rig template ls
rig template deploy --template dev --name my-project --catalog vscode,jupyter

recipe

Publish and install community recipes. There are two kinds: app recipes (install into an existing workspace) and composition recipes (deploy a whole workspace).

# App recipes
rig recipe app init --vendor you ...   # scaffold an app recipe directory
rig recipe app ls   --type community
rig recipe app lint  rig.yaml
rig recipe app info  rig.yaml          # or an exact recipe ref
rig recipe app install --ref "@vendor/slug@1.0.0" --workspace my-project
rig recipe app versions --ref "@vendor/slug"
rig recipe app delete   --ref "@vendor/slug@1.0.0"
rig recipe app yank\|deprecate --ref "@vendor/slug@1.0.0"
rig recipe app profile                 # show/update your community profile
rig recipe app health
rig recipe app test composition.yaml

# Composition recipes (whole workspaces)
rig recipe composition init --vendor you --slug stack --name "My Stack" --app "@v/a@1.0.0"
rig recipe composition lint\|ls\|info\|versions\|delete\|yank\|deprecate ...
rig recipe composition deploy --ref "@vendor/stack@1.0.0"

Registry refs use the required -r/--ref flag (install, versions, delete, yank, deprecate). Positional arguments are for local file paths only (lint, info).

publish

Publish a rig.yaml (or a rendered manifest) to the community registry:

rig publish --vendor you --slug notes --version 1.0.0
rig publish --app api                  # multi-app: publish only one child
rig publish --from-manifest manifest.json   # publish a pre-rendered manifest ('-' = stdin)
rig publish --dry-run                  # print the rendered manifest without calling the API

The publish: block in rig.yaml supplies default vendor/slug/version/metadata; flags override it.

setup-script & service-spec

Reusable first-boot configuration attached to workspaces at creation time.

rig setup-script ls
rig setup-script create --name bootstrap --file ./bootstrap.sh
rig setup-script update --id <ID> --name new-name --file ./bootstrap.sh
rig setup-script rm     --id <ID>

rig service-spec ls
rig service-spec create --file ./spec.yaml
rig service-spec update --id <ID> --file ./spec.yaml
rig service-spec rm     --id <ID>

See Setup Scripts and Service Specs.

proxy (workspace-only)

Inside a workspace VM, the managed AI proxy helpers wire your shell to the credit-metered proxy:

rig proxy status                 # bridge URL, routes, credit balance
eval "$(rig proxy on)"           # export OPENAI_/ANTHROPIC_ vars wired to the proxy
eval "$(rig proxy off)"          # unset them
rig proxy dotenv ./.env          # write a .env with proxy config
rig proxy path                   # path to the sourceable proxy.env file

on/off/env accept an optional route alias (openrouter, openai, v1). See Managed AI Proxy.

API reference

The CLI wraps the Rigbox REST API. For programmatic access, see:

Workspaces API — create, manage, and monitor workspaces
Apps API — manage app routes and services
SSH Keys API — register and manage SSH keys
Templates API — browse available templates
AI & Credits API — credits, usage, and AI configuration

Or hit any endpoint directly with rig api GET /v1/workspaces.

Documentation Index

Install & authenticate

Global flags

Deploy & rig.yaml

Command groups

​Install

​Inside a workspace

​On your local machine

​Pin a version or change the install directory

​Shell completions

​Authentication

​Log in (local machine)

​API keys

​Runtime modes

​Global flags

​Persisted defaults

​Raw API access

​Deploy

​Loading .env files

​Blue-green and promote

​Scaffold a manifest

​The rig.yaml manifest

​Single-app form

​Field reference

​Multi-app form

​Command reference

​Account

​workspace

​app

​snapshot

​volume

​build, release, rollback

​ssh

​tools

​template

​recipe

​publish

​setup-script & service-spec

​proxy (workspace-only)

​API reference

Install

Inside a workspace

On your local machine

Pin a version or change the install directory

Shell completions

Authentication

Log in (local machine)

API keys

Runtime modes

Global flags

Persisted defaults

Raw API access

Deploy

Loading `.env` files

Blue-green and promote

Scaffold a manifest

The rig.yaml manifest

Single-app form

Field reference

Multi-app form

Command reference

Account

workspace

app

snapshot

volume

build, release, rollback

ssh

tools

template

recipe

publish

setup-script & service-spec

proxy (workspace-only)

API reference