Concepts

A short glossary so the rest of the docs make sense. Most of these terms map 1:1 to tables in the database or activities in the workflow.

Tenant

A tenant is the unit of isolation. One Linear workspace + one GitHub organization = one tenant. Every database query, sandbox, and credential is scoped to a tenant. In self-host mode you'll typically have one tenant; in the managed cloud each customer is a separate tenant.

Workstream

A workstream is the long-lived record for a piece of work — usually corresponding to a Linear issue. It moves through states (pending → investigating → implementing → pr_open → done) as the agent makes progress. The workstream survives restarts, crashes, and human intervention.

Agent session

An agent session is a single attempt at running the coding agent. One workstream may have multiple sessions if the agent fails and is restarted, or if a human asks the agent to revise its work. Each session has its own sandbox.

Sandbox

A sandbox is the isolated environment where the agent actually runs — a checked-out copy of the repo, environment variables, and a place for the agent to execute commands. Sinatra supports two providers:

• daytona — Daytona cloud sandbox, requires a Daytona API key.
• local — runs in /tmp/sinatra-<id>/ on the worker host. Good for development. Strips GH_TOKEN/GITHUB_TOKEN from spawned processes and gives each sandbox its own GH_CONFIG_DIR so the agent's gh auth is isolated.

Run

A run is a single execution of the agent inside a session — one prompt, one or more turns, one final outcome (PR opened, error, or abandoned). Sessions can have multiple runs (e.g., the user comments back asking for changes).

Engine

The engine is the agent harness running inside the sandbox. Sinatra ships with claude-code (default) and opencode. Choose per-repo via .sinatrarc.

.sinatrarc

A per-repo config file customers commit to their target repository to control the engine, model, sandbox setup, hooks, and CI behaviour. See the configuration reference.