Overview

Core Concepts

View as Markdown

This page covers the mental model you need to work with Chaser effectively.

Sessions

A session is a running microVM. It has a UUID, a type (browser or sandbox), and a set of control endpoints. When you create a session, Chaser boots a VM, and when you terminate it, the VM is destroyed.

Sessions can be ephemeral (no durable state) or workspace-backed (attached to a persistent disk).

POST /v1/sessions
{
  "session_type": "sandbox",   // "browser" or "sandbox"
  "workspace": "my-project",   // optional: attach to a workspace
  "ephemeral": true            // optional: no persistence
}

Rules:

  • If ephemeral is true, no workspace is used. The session is disposable.
  • If ephemeral is false (the default), a workspace selector is required.
  • Browser sessions accept workspace or ephemeral, but not image.
  • Sandbox sessions accept image only when ephemeral is true. For persistent sandboxes, the image is set on the workspace.

Workspaces

A workspace is a named persistent disk. It stores files across sessions — terminate a session, boot a new one against the same workspace, and your files are still there.

Each workspace is locked to a session type (browser or sandbox) and belongs to an account.

POST /v1/workspaces
{
  "session_type": "sandbox",
  "name": "my-project",
  "image": "ghcr.io/example/dev:latest"   // optional, sandbox only
}

Key properties:

  • Names are unique per account, case-insensitive, max 64 characters.
  • Selectors — anywhere the API accepts a workspace reference, you can use the workspace name (preferred) or UUID.
  • Templates — flag a workspace as a template, then clone new workspaces from it.
  • Snapshots — create filesystem-level restore points. Snapshot operations are blocked while a session is actively attached unless force=true is passed.
  • GitHub import — import a workspace from a GitHub repository with POST /v1/workspaces/import. The repository selector is persisted on the workspace for re-bootstrap.

Accounts

Every user gets an implicit personal account. You can also create organization accounts for team collaboration.

All resources (sessions, workspaces, API keys, webhooks, audit events) are scoped to the active account. Select the active account on any request:

1X-Chaser-Account: Acme Engineering

If omitted, your personal account is used. Accepted values: account ID, exact account name, or personal.

Organization features:

  • Members with roles: owner, admin, member
  • Service accounts with scoped API keys for automation
  • Shared workspaces visible to all members of the organization

Authentication

All API requests require a bearer token:

1Authorization: Bearer sk_your_key_here

Accepted token types:

  • API keys (sk_...) — created via the dashboard, CLI, or API
  • JWT access tokens — from OAuth login flows (Google, GitHub)

Scoped API keys can be restricted to specific permissions: sessions.read, sessions.write, workspaces.read, workspaces.write, exec.write, files.read, files.write, keys.read, keys.write, billing.read, billing.write, audit.read, webhooks.read, webhooks.write. Keys without explicit scopes have full access.

API keys are bound to the account selected at creation time and cannot be redirected to a different account later.

Session endpoints

When a session is created, the response includes control endpoints:

  • Subdomain style: https://<session_id>.chaser.sh/
  • Path style: https://api.chaser.sh/s/<session_id>/

Both resolve to the same session. Browser sessions use these for CDP access. Sandbox sessions use them for PTY, exec, file transfer, and port forwarding.

Connection leases

Chaser tracks active connections to sessions (PTY streams, exec streams, and other transports). The active_connection_leases field in session responses reflects this.

When you terminate a session with DELETE /v1/sessions/{id}, it may return a conflict if the session has active connections. Use force=true to override. The same applies to workspace deletion when sessions are attached.

Session status

Session status is one of: creating, running, or terminated. The API reconciles status from the control plane and the underlying VM daemon to give you an accurate view.