Persistent Volumes

A persistent volume is an ext4 drive attached to a workspace as a second disk, separate from the workspace’s root filesystem. It keeps application data separate from managed app releases and workspace image replacement.

Why you need one

In v0.13, incremental deployment prepares application code in managed release directories. Those directories are not durable writable storage. Put databases, uploads, and other mutable files on a data volume instead of beside source code. Durable state belongs on a persistent volume. The usual convention is a volume named data mounted at /home/developer/data, exposed to the app as DATA_DIR:

env:
  DATA_DIR: /home/developer/data

Store SQLite databases, uploaded files, and logs under $DATA_DIR and they stay put across deploys.

A persistent volume survives app redeploys, app restarts, and stop→start of the workspace. It is destroyed only when you delete the volume or the workspace itself.

Declare a volume in rig.yaml

The canonical path is to declare durable disks once under workspace.volumes, then opt each app into the mount with volumes: [data]. The volume is created or reattached on deploy, and only apps that reference it receive the mount.

name: markdown-notes
port: 8080
workspace:
  volumes:
    - name: data
      mountPath: /home/developer/data
      sizeMb: 1024
install: pip install --break-system-packages flask gunicorn
start: gunicorn --bind 0.0.0.0:8080 app:app
health: { path: /healthz, timeoutSeconds: 30 }
volumes: [data]
env:
  DATA_DIR: /home/developer/data

Point DATA_DIR at the same path and your app reads and writes durable state there. For multi-app projects, keep the declaration at the workspace level and attach it only to the apps that need it:

workspace:
  image: base
  volumes:
    - name: data
      mountPath: /home/developer/data
      sizeMb: 1024

apps:
  api:
    path: ./api
    port: 5100
    start: npm start
    volumes: [data]
    env:
      DATA_DIR: /home/developer/data

  web:
    path: ./web
    port: 5101
    start: npm start
    dependsOn: [api]
    visibility: public

App references can be written as volumes: [data] or volumes: [{ name: data }]. App-local full specs are still supported for single-app or one-off cases:

volumes:
  - name: data
    mountPath: /home/developer/data
    sizeMb: 1024

Manage volumes with the CLI

You can also manage volumes independently of a deploy. Run locally, stop the workspace before create/resize/remove, then start it to attach the updated drive set:

rig workspace stop --workspace <WORKSPACE_NAME>
# create a volume (size in MiB, mounted at an absolute path)
rig volume create --workspace <WORKSPACE_NAME> --name data --size-mb 1024 --mount-path /home/developer/data
rig volume ls --workspace <WORKSPACE_NAME>                       # list volumes for a workspace
rig volume resize --workspace <WORKSPACE_NAME> --volume <VOLUME_ID> --size-mb 5120   # grow a volume
rig volume rm --workspace <WORKSPACE_NAME> --volume <VOLUME_ID>  # delete a volume (destroys its data)

rig volume resize and rig volume rm take the volume id (from rig volume ls), not its name.

Each command targets a specific workspace with --workspace:

# List volumes for a workspace
rig volume ls --workspace <WORKSPACE_NAME>

# Create a volume (size in MiB, with an absolute mount path)
rig volume create --workspace <WORKSPACE_NAME> \
  --name data \
  --size-mb 1024 \
  --mount-path /home/developer/data

Deleting a volume (rig volume rm) permanently destroys the data on it. This is separate from deleting the workspace — but deleting the workspace destroys its volumes too.

The SQLite-under-$DATA_DIR pattern

The most common use is a SQLite database that outlives deploys. Two pieces make it work:

Set DATA_DIR=/home/developer/data in env: and put the database file under it.
mkdir -p "$DATA_DIR" at startup — a fresh workspace may not have the directory yet.

import os, sqlite3

DATA_DIR = os.environ.get("DATA_DIR", "/home/developer/data")
os.makedirs(DATA_DIR, exist_ok=True)        # the dir may not exist on a fresh workspace
db = sqlite3.connect(os.path.join(DATA_DIR, "notes.db"))

Because notes.db lives on the volume, not in the synced app directory, an app release updates code while the database file remains on its separate disk.

To verify persistence, deploy the app, create some data, run rig deploy again, and confirm the data is still there. Verify the mount and data path; an environment variable alone does not create durable storage.

Next steps

Deploying with rig deploy — the v0.13 deployment workflow.
Releases & Rollback — roll the environment back without touching volume data.
Snapshots — checkpoint the root disk only; attached volumes need separate backups.

For complete resize/removal steps, see volume management.

Start here

Deploy applications

Configure applications

Workspaces and storage

AI and tools

Operate and troubleshoot

Examples

CLI reference

Build on Rigbox

Why you need one

Declare a volume in rig.yaml

Manage volumes with the CLI

The SQLite-under-$DATA_DIR pattern

Next steps

​Why you need one

​Declare a volume in rig.yaml

​Manage volumes with the CLI

​The SQLite-under-$DATA_DIR pattern

​Next steps

Why you need one

Declare a volume in rig.yaml

Manage volumes with the CLI

The SQLite-under-$DATA_DIR pattern

Next steps