Skip to main content
A workspace is an isolated micro-VM running full Debian 12 Linux with systemd, SSH access, and its own private IP address. Each workspace has its own kernel and filesystem, with configured vCPU, RAM, and disk allocations. Physical host infrastructure is shared; a vCPU allocation does not promise a dedicated physical core. 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.

​
Before you begin

Use the v0.13 CLI and authenticate. Run workspace-management and recipe commands from your local terminal. Commands identified as running inside a workspace require its console terminal or SSH session. Replace example resource IDs with the values returned for your account.

​
Workspace Lifecycle

Every workspace moves through a predictable set of states:
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):
The resource and template flags are optional; --name is required. Omit the resource flags to use the selected template’s defaults. 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 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 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. rig workspace restart stops a running workspace, starts it again, and waits the same way.

​
Workspace is ready

Once running, you can SSH in, expose ports, install catalog apps, and more. rig workspace spawn, start, and restart set up SSH access from your machine when the workspace comes up and print the command, so ssh <WORKSPACE_NAME> connects.

​
Stopping a Workspace

Stopping a workspace shuts down the VM but preserves the disk. You can restart it later.
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.
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 workspace environment variables. The API saves them and updates guest configuration files for a running workspace; existing processes must reload their configuration or restart to use new values.
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

Read the latest CPU, RAM, and disk metrics. Repeat the command when you need a new sample.
For machine-readable output, add --output json and pipe to jq:
See Get Metrics for the full response schema.

​
Logs

Read workspace logs or follow the log 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.
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:
When it returns, the workspace is running and the CLI has set up SSH access, so you can connect by name:
rig workspace ssh-info --workspace demo-workspace prints the full connection details.

​
Verify and troubleshoot

Inspect rig workspace ls and rig workspace services --workspace WORKSPACE_ID. For installed apps, check their status and health before opening the returned URL. A created resource or running VM does not by itself prove the application is ready. For failures, start with runtime logs, health checks, or resource exhaustion.

​
Next Steps