Skip to main content
A workspace is an isolated Firecracker 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

To create a workspace, send a POST request with the VM configuration. 
curl -X POST https://api.rigbox.dev/api/workspaces \
  -H "Authorization: Bearer $RIGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "image": "base",
    "ram_mb": 512,
    "disk_size_mb": 3072,
    "vcpu_count": 1
  }'
The response includes the workspace id you’ll use for all subsequent operations. See Create Workspace for the full request/response schema.

​
Quick Deploy with a Template

If you don’t need custom sizing, use quick deploy to create a workspace from a pre-configured template in a single call. 
curl -X POST https://api.rigbox.dev/api/quick-deploy \
  -H "Authorization: Bearer $RIGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "dev"
  }'
Quick deploy selects the image, RAM, disk, and vCPU settings from the template. See Images & Templates for available templates.

​
Starting a Workspace

After creation, boot the workspace with a start request, then poll until the status is running.

​
Send the start request

curl -X POST https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID/start \
  -H "Authorization: Bearer $RIGBOX_API_KEY"

​
Poll until running

The VM takes a few seconds to boot. Poll the workspace endpoint until status is running. 
while true; do
  STATUS=$(curl -s https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID \
    -H "Authorization: Bearer $RIGBOX_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "running" ] && break
  sleep 2
done

​
Workspace is ready

Once running, you can SSH in, expose ports, install catalog apps, and more. See Start Workspace for response details.

​
Stopping a Workspace

Stopping a workspace shuts down the VM but preserves the disk. You can restart it later. 
curl -X POST https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID/stop \
  -H "Authorization: Bearer $RIGBOX_API_KEY"
Stop workspaces you aren’t actively using. Stopped workspaces don’t consume CPU or RAM resources.
See Stop Workspace for details.

​
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/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 Resize Workspace 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/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 Set Environment Variables for details.

​
Live Metrics

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

​
Logs

Retrieve workspace logs or stream them in real time via Server-Sent Events. 
curl -s https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID/logs \
  -H "Authorization: Bearer $RIGBOX_API_KEY"
The /logs/stream endpoint returns Server-Sent Events (SSE). Use an SSE client library for production integrations. See Get Logs and Stream Logs for details.

​
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.
curl -X DELETE https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID \
  -H "Authorization: Bearer $RIGBOX_API_KEY"
See Delete Workspace for details.

​
Complete Example: Create, Start, and Poll

This end-to-end example creates a workspace, starts it, and waits for it to be ready.
Python
import requests
import time

API_URL = "https://api.rigbox.dev/api"
HEADERS = {"Authorization": f"Bearer {api_key}"}

# 1. Create the workspace
workspace = requests.post(
    f"{API_URL}/workspaces",
    headers=HEADERS,
    json={
        "name": "demo-workspace",
        "image": "base",
        "ram_mb": 512,
        "disk_size_mb": 3072,
        "vcpu_count": 1,
    },
).json()

workspace_id = workspace["id"]
print(f"Created workspace: {workspace_id}")

# 2. Start the workspace
requests.post(f"{API_URL}/workspaces/{workspace_id}/start", headers=HEADERS)

# 3. Poll until running
while True:
    resp = requests.get(f"{API_URL}/workspaces/{workspace_id}", headers=HEADERS)
    status = resp.json()["status"]
    print(f"  Status: {status}")
    if status == "running":
        break
    time.sleep(2)

print(f"Workspace {workspace_id} is running and ready to use.")

​
Next Steps