# Core Concepts

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:

```http
X-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:

```http
Authorization: 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.