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, but that 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 as a task on a VM. 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

When you start a chat you can choose a workspace profile:

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

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.

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 VM size per project. The exact machine types, regions, and pricing are shown in the size picker when you start work.

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 VM size and default provider 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, VM size, 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. A trigger runs from one of 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.

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
5. When done, the agent commits, pushes, and opens a pull request

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 — branch off from any point to explore alternatives
• 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

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.