Core Concepts

Workspaces

A workspace is the environment an AI coding agent runs in: your repository, cloned and ready. In everyday use SAM provisions a workspace for you automatically when you start working in a project chat — you don’t create one by hand.

Every workspace has one or more agent chat sessions and its own lifecycle: pending → creating → running → sleeping → recovery, plus terminal stop and delete states. Sleeping is resumable for seven days; archive is terminal.

A VM workspace additionally gives the agent a full Linux toolchain, Docker, and your .devcontainer; a browser-based terminal for hands-on work; and automatic port detection for dev servers (see below). An Instant workspace trades all of that for a start measured in seconds.

Workspace compute is ephemeral. Persistent sessions preserve the home directory and uncommitted repository state while sleeping. If snapshots keep failing, SAM may keep only the repository state and the conversation instead. Either way the snapshot expires after seven days, so push anything you need to keep longer.

Runtimes: Instant vs VM

A workspace runs in one of two places:

Runtime	Where it runs	Trade-off
Instant	A container on Cloudflare’s network	Starts in seconds, no cloud account needed — but no devcontainer and no Docker
VM	A cloud VM on your provider account	Your full environment, at the cost of a minute or two of provisioning

Which one you get is an agent profile setting: a profile whose runtime is Instant container starts chats on Instant; everything else runs on a VM, as a Task or a Chat depending on the profile (see Chat or Task). A Task carries the work through to a pull request; a Chat is back-and-forth and doesn’t commit or push for you. Instant needs no cloud provider credential, so it’s how you work before connecting a cloud account.

Instant and VM sessions sleep when idle and restore from a runtime-neutral snapshot on wake. A VM wake provisions a replacement workspace after the original compute is removed. See Instant Sessions and persistent sleep.

Workspace Profiles

An agent profile’s Workspace Profile setting chooses how much environment a VM chat gets:

Profile	Best for
Full (default)	Work where the agent needs to run your stack — builds your .devcontainer on a VM workspace; no effect on Instant
Lightweight	Quick questions and code exploration — starts faster; with Task Mode left at Default, its sessions are Chats (no automatic pull request)

Port Exposure

When a service starts listening on a port inside a workspace, SAM automatically detects it and makes it accessible via a unique URL:

https://ws-{workspaceId}--{port}.{baseDomain}

For example, if your dev server starts on port 3000 in workspace abc123, you can open it at https://ws-abc123--3000.example.com. Common development ports get friendly labels automatically.

Nodes

A node is a cloud VM that hosts one or more workspaces. You normally never think about nodes — SAM assigns your workspace to a healthy node or provisions a new one for you, from the machine types your compute pool permits.

Several workspaces can share one node when the node’s CPU, memory, and disk reservations all still fit and nothing on it asked for exclusive use. Work can also ask for a node to itself; see Compute Pools.

When a Node Stops Responding

Every node reports in to SAM regularly. A cloud node that SAM runs for you and that goes quiet is not left running and billed: SAM asks its chats to sleep and deletes it within about 30 minutes. Machines you enrolled yourself are left alone. See SAM lost contact with the machine for what that looks like in a chat and what to do.

Warm Reuse

After a piece of work finishes, SAM keeps the environment warm for a short window (30 minutes by default). If you start follow-up work during that window, SAM reuses the warm environment instead of provisioning a fresh one — cutting startup from minutes to seconds. Idle environments are cleaned up automatically afterward.

Providers

A provider is the cloud your compute runs on. For running workspaces, SAM supports Hetzner, Scaleway, Vultr, Infomaniak, DigitalOcean, UpCloud, and Google Cloud. SAM follows a Bring Your Own Cloud (BYOC) model: you add your own provider credential in Settings → Connections (or the Cloud Provider tab), and VM costs are billed directly to your account. On the hosted platform, compute can be provided for you, so you may not need your own credential. Cloud credentials are never stored as environment variables.

You can set a default provider and default location per project, and the resource requirements new work inherits. The exact machine types, regions, and pricing are shown when you start work.

Compute Pools

A compute pool (also called a node pool or capacity pool) is the set of cloud machines SAM is allowed to rent on your behalf. Pools exist at three scopes — project, user, and installation — and SAM uses the first one that exists, in that order.

Each pool holds the credentials that pay for its machines and the list of concrete provider instance types it permits, discovered from your provider’s live catalog rather than reduced to small/medium/large presets. Two settings shape what SAM does with that list: a strategy (which permitted machine to pick) and an exhaustion policy (what to do when none is available).

You normally do not have to configure any of this — SAM creates and maintains a working pool for the credentials it can see. See the Compute Pools guide for the full picture.

Projects

A project links a GitHub repository to its chats, agents, ideas, and activity. It’s the primary organizational unit in SAM, and the project chat is the primary way you interact with SAM.

Each project has:

• A chat — the main surface where you describe work and watch agents run it
• Agent profiles and skills — reusable configurations you pick from per chat (see below)
• An Ideas board — for capturing and organizing work you haven’t started yet
• A default provider, default location, and default resource requirements for new workspaces
• Runtime configuration — environment variables and files made available to workspaces

Agent Profiles

An agent profile is a saved, reusable configuration for running an agent: which agent, which model, which runtime, the resource requirements its workspaces ask for, the system prompt, and other settings. Instead of configuring everything each time, you create profiles once and pick one when you start a chat (or attach one to a trigger). Profiles are the intended way to choose an agent — you’re not limited to a single project-wide default.

Skills

A skill is a reusable layer of instructions, environment, and files you can apply on top of a profile for a particular kind of work. Skills override profile settings when selected, following the resolution order skill → profile → project → platform. Pick a skill per chat the same way you pick a profile.

Triggers

A trigger starts agent work automatically, without you opening a chat. User-facing triggers run from three sources:

• Schedule (cron) — run on a recurring basis
• GitHub event — react to activity on the linked repository
• Webhook — start work when an authenticated external request arrives (see Webhook Triggers)

Each trigger runs with a specific agent profile (and optional skill), so triggered work behaves like a chat you started yourself.

SAM also has a private operator-only incident trigger source used by the configured platform feedback project. It dispatches agents from grouped private incident backlog summaries rather than from external user/project events.

Ideas

An idea captures a piece of work you want an AI agent to do. Most work starts directly from the project chat — submitting a message both creates and executes the work in one step. The Ideas board is where you keep ideas you’ve drafted but haven’t started yet; once an idea is executing or done, you’ll follow it in the chat session list.

You can also execute a saved idea from its detail page with the Execute button.

How Execution Works

When you submit work from the chat:

1. SAM generates a concise title from your message
2. A descriptive output branch is created (sam/...) from your default branch
3. SAM selects or provisions a workspace, already checked out on that branch, reusing a warm one when available
4. Your chosen agent runs autonomously with your description — unless its permission mode tells it to ask you first, in which case it waits for your answer in the chat
5. When a Task is done, the agent commits, pushes, and opens a pull request (a Chat pushes only what you ask the agent to push)

SAM refuses to auto-push a completed task while the workspace is still on the project’s default branch, so agent work reaches a reviewable branch rather than main. See Where the work lands.

Linking Ideas to Conversations

Ideas can be linked to chat sessions, creating a many-to-many association. This lets you track which conversations led to which ideas, and pull in idea context during a chat. Agents can manage these links using MCP tools (link_idea, unlink_idea, find_related_ideas).

Agent-to-Agent Dispatch

Running agents can spawn follow-up ideas within the same project using MCP tools. This enables multi-step workflows where one agent delegates sub-work to others.

See the Idea Execution guide for full details.

Agent Sessions

An agent session is an AI coding agent conversation running inside a workspace container. Sessions use the Agent Communication Protocol (ACP) to communicate between the browser and the agent process.

SAM supports six AI coding agents:

Agent	Provider	API Key Variable
Claude Code	Anthropic	ANTHROPIC_API_KEY
OpenAI Codex	OpenAI	OPENAI_API_KEY
Gemini CLI	Google	GEMINI_API_KEY
Mistral Vibe	Mistral	MISTRAL_API_KEY
OpenCode	OpenCode managed inference	OPENCODE_API_KEY
Amp	Sourcegraph	AMP_API_KEY

You choose which agent to run by selecting an agent profile in the chat. See the AI Agents guide for how to connect credentials and configure profiles.

Sessions support:

• Streaming responses (real-time output as the agent works)
• Multiple concurrent sessions per workspace (each in its own terminal tab)
• Persistence across page refreshes (tabs restored from VM Agent SQLite)
• Conversation forking — start a new session that carries a summary of this one, to explore an alternative
• Voice input and text-to-speech playback
• File browsing — browse, view, and diff files directly in the chat panel
• File upload/download — attach files to conversations and download from workspaces

See the AI Agents guide and Chat Features guide for full details.

Notifications

SAM includes an in-app notification system with real-time delivery via WebSocket:

Type	Urgency	Trigger
task_complete	Medium	A task finishes executing successfully
needs_input	High	Agent is blocked and needs your decision
error	High	Execution fails
progress	Low	Agent reports incremental progress
session_ended	Medium	A conversation-mode session turn completes
pr_created	Medium	Agent creates a pull request

See the Notifications guide for full details.

Authentication

SAM uses a GitHub App for both OAuth login and repository access. The app needs:

• OAuth — for user sign-in (BetterAuth handles session management)
• Contents: Read and write — for cloning repos and pushing changes
• Email addresses: Read-only — for user profile information
• Pull requests, Checks, and Actions: Read-only — for project event facts from pull request, review, check, and workflow webhooks

Caution

User credentials (cloud provider credentials and agent credentials) are encrypted at rest using AES-256-GCM. The encryption key is a platform secret managed by Pulumi — never share it or store it in source control.