The Rigbox CLI

rig --version

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

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

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

rig login

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

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

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

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

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

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)

rig deploy --stage production

# Whole-workspace: clone prod into a hidden preview, overlay, then cut over
rig deploy --bluegreen preview
rig deploy --bluegreen preview --promote

# In-VM sibling: stage <base>-<suffix> on its own subdomain, then swap
rig deploy --bluegreen v2
rig deploy --bluegreen v2 --promote

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

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

workspace:
  image: base
  resources: { ramMb: 1024, vcpuCount: 1, diskSizeMb: 3072 }
  volumes:                    # reusable workspace volume declarations
    - name: data
      mountPath: /home/developer/data
      sizeMb: 1024

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: [data]               # opt the app into a workspace volume mount

workspace:
  image: dev                  # base template/image for the VM
  resources:
    ramMb: 4096               # workspace VM resources (all optional)
    vcpuCount: 2
    diskSizeMb: 20480
  volumes:                    # declare once, then reference from apps
    - name: data
      mountPath: /home/developer/data
      sizeMb: 1024
  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]
    volumes: [data]           # or volumes: [{ name: data }]
  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

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

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

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>

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>

# 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>

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

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

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>

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

# 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"

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

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>

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