# Persistent Workspaces

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

## Create a persistent workspace

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
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`

## Related

- [Workspaces](/docs/platform/workspaces) -- API reference for workspace operations
- [Interactive Development](/docs/guides/interactive-development) -- using workspaces for development
- [CI/CD Integration](/docs/guides/ci-cd-integration) -- workspace-backed CI