Chaser Documentation

Workspaces are named persistent disks scoped to an account. Each workspace is locked to a session type (browser or sandbox) and stores files across session restarts.

Create a workspace

Two creation modes: fresh and cloned.

Fresh workspace

$ curl -sS "$CHASER_API_URL/v1/workspaces" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "session_type": "sandbox",
>     "name": "my-project",
>     "image": "ghcr.io/example/dev:latest"
>   }' | jq

Field	Required	Description
`session_type`	Yes	`browser` or `sandbox`
`name`	No	Human-readable name (auto-generated if omitted)
`image`	No	OCI image, sandbox only
`template`	No	Flag as a template workspace

Cloned workspace

$ curl -sS "$CHASER_API_URL/v1/workspaces" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "clone_from": "my-project",
>     "name": "my-project-feature"
>   }' | jq

Cloning copies workspace metadata and filesystem state. session_type and image are inherited from the source. Cloning is blocked while the source has an active session.

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 repository is cloned into /workspace and the repo selector is persisted on the workspace.

List workspaces

$ curl -sS "$CHASER_API_URL/v1/workspaces" \
>   -H "Authorization: Bearer $CHASER_API_KEY" | jq

Each workspace includes: id, name, session_type, status, image, template, active_session_id, last_session_id, and persistence metadata.

Naming

$ # Set a name
$ curl -sS -X PUT "$CHASER_API_URL/v1/workspaces/<workspace>/name" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"name": "new-name"}' | jq
$ 
$ # Clear the name
$ curl -sS -X PUT "$CHASER_API_URL/v1/workspaces/<workspace>/name" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"name": null}' | jq

Names are unique per account, case-insensitive, max 64 characters. Ambiguous name matches return workspace_name_ambiguous.

Templates

$ # Enable template mode
$ curl -sS -X PUT "$CHASER_API_URL/v1/workspaces/<workspace>/template" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"template": true}' | jq

Any workspace can be flagged as a template. Templates can be cloned with clone_from.

Snapshots

Create filesystem-level restore points:

$ # Create
$ curl -sS -X POST "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"name": "before-upgrade"}' | jq
$ 
$ # List
$ curl -sS "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots" \
>   -H "Authorization: Bearer $CHASER_API_KEY" | jq
$ 
$ # Restore (force terminates active sessions)
$ curl -sS -X POST "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots/before-upgrade/restore" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"force": true}' | jq
$ 
$ # Delete
$ curl -sS -X DELETE "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots/before-upgrade" \
>   -H "Authorization: Bearer $CHASER_API_KEY"

Snapshot create and restore operations are blocked while a session is active, unless force=true is passed (which terminates the session first).

Delete

$ # Single workspace
$ curl -sS -X DELETE "$CHASER_API_URL/v1/workspaces/<workspace>?force=true" \
>   -H "Authorization: Bearer $CHASER_API_KEY"
$ 
$ # Bulk delete
$ curl -sS -X POST "$CHASER_API_URL/v1/workspaces/bulk-delete" \
>   -H "Authorization: Bearer $CHASER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"workspace_ids": ["ws_1", "ws_2"], "force": true}' | jq

Without force, deletion fails if sessions are actively attached.

Workspace selectors

Anywhere the API accepts a workspace reference, you can use:

Workspace name (preferred)
Workspace UUID

Selectors are resolved within the active account boundary.

API reference

Endpoint	Description
`GET /v1/workspaces`	List workspaces
`POST /v1/workspaces`	Create workspace (fresh or cloned)
`POST /v1/workspaces/import`	Import from GitHub
`PUT /v1/workspaces/{workspace}/name`	Set or clear name
`PUT /v1/workspaces/{workspace}/template`	Toggle template mode
`GET /v1/workspaces/{workspace}/snapshots`	List snapshots
`POST /v1/workspaces/{workspace}/snapshots`	Create snapshot
`POST /v1/workspaces/{workspace}/snapshots/{name}/restore`	Restore snapshot
`DELETE /v1/workspaces/{workspace}/snapshots/{name}`	Delete snapshot
`DELETE /v1/workspaces/{workspace}`	Delete workspace
`POST /v1/workspaces/bulk-delete`	Bulk delete workspaces