Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

A workspace is an isolated micro-VM running full Debian 12 Linux with systemd, SSH access, and its own private IP address. Each workspace gets dedicated CPU, RAM, and disk - nothing is shared with other workspaces. Workspaces are the core primitive in Rigbox. You create one, run code inside it, expose services to the internet, and tear it down when you’re done.

​
Workspace Lifecycle

Every workspace moves through a predictable set of states:
StatusDescription
provisionedVM is allocated but not yet booted
runningVM is booted and accepting connections
stoppedVM is shut down; disk state is preserved
deletedVM and all data are permanently removed
A stopped workspace retains its disk contents. You can restart it at any time without losing files or installed packages.

​
Creating a Workspace

Use the Rigbox CLI to create a workspace. Replace <WORKSPACE_NAME> with a name of your choice (for example, my-project): 
rig workspace new --name <WORKSPACE_NAME> --template base --ram 512 --vcpu 1 --disk 3072
The flags are optional - leave them off to use the base template. If requested resources are below the template or catalog floor, Rigbox raises them before creating the workspace. rig workspace new prints the new workspace’s ID, status, and connection info on stdout. For the underlying HTTP shape, see Create Workspace in the API reference.

​
Quick Deploy with a Template

If you don’t need custom sizing, deploy from a pre-configured template in one command: 
rig workspace spawn --name <WORKSPACE_NAME> --template dev
rig workspace spawn creates the workspace, starts it, and waits until it’s ready - all in one call. See Images & Templates for the list of templates, or Quick Deploy for the API.

​
Starting a Workspace

Boot a previously-stopped workspace and wait for it to become running: 
rig workspace start --workspace <WORKSPACE_NAME_OR_ID>
rig workspace start polls the workspace status internally and returns once the VM is up. If a stopped workspace is below its template or catalog resource floor, Rigbox raises the stored resources before booting. Add --wait-for-apps to wait for workspace apps to report active before the command returns. For scripting, rig workspace ls prints the current state. See Start Workspace for the API form.

​
Workspace is ready

Once running, you can SSH in, expose ports, install catalog apps, and more.

​
Stopping a Workspace

Stopping a workspace shuts down the VM but preserves the disk. You can restart it later. 
rig workspace stop --workspace <WORKSPACE_NAME_OR_ID>
Stop workspaces you aren’t actively using. Stopped workspaces don’t consume CPU or RAM resources.
See Stop Workspace for the API form.

​
Resizing a Workspace

You can change the RAM, vCPU count, and disk size of a workspace. The workspace must be stopped first. 
curl -X PUT https://api.rigbox.dev/api/v1/workspaces/$WORKSPACE_ID/resources \
  -H "Authorization: Bearer $RIGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ram_mb": 1024,
    "vcpu_count": 2,
    "disk_size_mb": 5120
  }'
The workspace must be in a stopped state before resizing. Start it again after the resize completes.
See Update Workspace Resources for the full schema.

​
Environment Variables

Set environment variables that are injected into the workspace on boot. 
curl -X POST https://api.rigbox.dev/api/v1/workspaces/$WORKSPACE_ID/env \
  -H "Authorization: Bearer $RIGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "env_vars": {
      "DATABASE_URL": "postgres://localhost:5432/mydb",
      "API_SECRET": "sk-abc123"
    }
  }'
Environment variables persist across restarts. You don’t need to set them again after stopping and starting a workspace.
See Update Workspace Environment for details.

​
Live Metrics

Monitor CPU, RAM, and disk usage in real time. 
curl -s https://api.rigbox.dev/api/v1/workspaces/$WORKSPACE_ID/metrics \
  -H "Authorization: Bearer $RIGBOX_API_KEY" | jq
See Get Metrics for the full response schema.

​
Logs

Tail recent workspace system logs or follow them in real time: 
rig workspace logs --workspace <WORKSPACE_NAME_OR_ID>          # recent logs
rig workspace logs --workspace <WORKSPACE_NAME_OR_ID> --follow # live stream
For programmatic access (e.g. ingesting log lines into another system), see Get Logs and Stream Logs — /logs/stream returns Server-Sent Events.

​
Deleting a Workspace

Deleting a workspace is irreversible. All files, installed packages, and configuration inside the VM are permanently destroyed. Make sure you’ve saved anything important before deleting.
rig workspace rm --workspace <WORKSPACE_NAME_OR_ID>
See Delete Workspace for the API form.

​
Complete Example: Spawn a Workspace

End-to-end with a single command - rig workspace spawn creates the workspace, boots it, and waits until it’s ready: 
rig workspace spawn --name demo-workspace --template base --ram 512 --vcpu 1 --disk 3072
When it returns, the workspace is running and SSH-reachable. Get the connection string with: 
rig workspace ssh-info --workspace demo-workspace

​
Next Steps