Guides

Persistent Workspaces

View as Markdown

This guide covers patterns for durable state management — long-lived environments, repeatable automation, and template-based workflows.

Create a persistent workspace

$# Basic workspace
$chaser workspaces create --session-type sandbox --name my-project --json
$
$# With a pinned OCI image
$chaser workspaces create --session-type sandbox --name my-project \
>  --image ghcr.io/example/dev:latest --json

Run commands against a workspace

Chaser provisions or reuses a sandbox session automatically:

$curl -sS "$CHASER_API_URL/v1/exec" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"workspace": "my-project", "command": "npm ci && npm test"}' | jq

Files created by one command are available to the next. The workspace disk persists even when no session is running.

Snapshots

Create filesystem-level restore points before risky operations:

$# Create a snapshot
$chaser workspaces snapshots create my-project --name before-upgrade --json
$
$# List snapshots
$chaser workspaces snapshots list my-project --json
$
$# Restore (requires no active session, or use --force)
$chaser workspaces snapshots restore my-project before-upgrade --force --json
$
$# Delete a snapshot
$chaser workspaces snapshots delete my-project before-upgrade --json

Snapshots capture the full workspace disk state. They are not live RAM/process checkpoints.

Templates and cloning

Mark a workspace as a template, then clone it to create independent copies:

$# Create a template workspace
$chaser workspaces create --session-type sandbox --name base-dev \
>  --image ghcr.io/example/dev:latest --template --json
$
$# Clone it for a feature branch
$chaser workspaces create --clone-from base-dev --name feature-branch --json

Cloning copies workspace metadata and the latest filesystem state. The clone is fully independent — changes to the clone do not affect the source.

Cloning is blocked while the source workspace has an active session.

Workspace naming

$# Rename a workspace
$chaser workspaces label <workspace> new-name
$
$# Clear the name
$chaser workspaces label <workspace> --clear

Names are unique per account, case-insensitive, max 64 characters.

Import from GitHub

$curl -sS "$CHASER_API_URL/v1/workspaces/import" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"github_repo": "owner/repo"}' | jq

The GitHub repository is cloned into /workspace. The repo selector is persisted on the workspace record so later session boots can re-bootstrap if needed.

Storage

  • Each workspace has a baseline disk size of 10 GB
  • Per-account total workspace storage is capped at 25 GB (measured as actual on-disk bytes)
  • Storage usage is visible in GET /v1/billing/summary