Core Concepts

Workspaces

A workspace is an AI coding environment: a Docker container running inside a VM, with your repository cloned and a devcontainer configured.

Each workspace has:

A unique subdomain (ws-{id}.example.com)
A browser-based terminal (xterm.js over WebSocket)
An agent chat interface (via ACP — Agent Communication Protocol)
Automatic port detection and exposure for dev servers
Its own lifecycle: pending → creating → running → stopping → stopped

Workspaces are ephemeral — they’re meant to be created for a coding session and deleted when done.

Workspace Profiles

SAM supports two workspace profiles:

Profile	Startup Time	Description
Full (default)	2-3 minutes	Standard devcontainer build from your project’s `.devcontainer` config
Lightweight	30-120 seconds faster	Skips devcontainer build, uses a minimal base image

Lightweight workspaces are ideal for quick conversations that don’t need custom build steps. You can select the profile when starting an idea or creating a workspace.

Port Exposure

When a service starts listening on a port inside a workspace container, 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:

https://ws-abc123--3000.example.com

The port scanner polls /proc/net/tcp inside the container every 5 seconds and recognizes common development ports (3000, 5173, 8080, etc.) with friendly labels.

Nodes

A node is a cloud VM that hosts one or more workspaces. When you create a workspace, SAM either assigns it to an existing healthy node or provisions a new one.

Nodes have their own lifecycle:

pending → creating → running → stopping → stopped
Health is tracked via heartbeats from the VM Agent

Warm Node Pooling

After an idea finishes executing, the node doesn’t shut down immediately. Instead, it enters a warm state for 30 minutes (configurable via NODE_WARM_TIMEOUT_MS). If a new idea is executed during this window, SAM reuses the warm node instead of provisioning a new one — reducing startup time from minutes to seconds.

SAM uses a three-layer defense against orphaned warm nodes:

Durable Object alarm — schedules cleanup when the warm timeout expires
Cron sweep — catches nodes that miss their alarm (runs every 5 minutes)
Max lifetime — absolute limit of 4 hours (configurable via MAX_AUTO_NODE_LIFETIME_MS) for auto-provisioned nodes

Providers

A provider is a cloud infrastructure abstraction. SAM currently supports three providers:

Hetzner Cloud

Size	Server Type	Specs	Monthly Cost
Small	CX23	2 vCPU, 4GB RAM, 40GB disk	~$4/mo
Medium	CX33	4 vCPU, 8GB RAM, 80GB disk	~$7.50/mo
Large	CX43	8 vCPU, 16GB RAM, 160GB disk	~$14.50/mo

Locations: Falkenstein (DE), Nuremberg (DE), Helsinki (FI), Ashburn (US), Hillsboro (US)

Scaleway

Size	Server Type	Specs	Hourly Cost
Small	DEV1-M	3 vCPU, 4GB RAM, 40GB disk	~$0.024/hr
Medium	DEV1-XL	4 vCPU, 12GB RAM, 120GB disk	~$0.048/hr
Large	GP1-S	8 vCPU, 32GB RAM, 600GB disk	~$0.084/hr

Locations: Paris (3 zones), Amsterdam (3 zones), Warsaw (2 zones)

Google Cloud Platform (GCP)

Size	Machine Type	Specs	Monthly Cost
Small	e2-medium	1 vCPU, 4GB RAM, 50GB disk	~$25/mo
Medium	e2-standard-2	2 vCPU, 8GB RAM, 50GB disk	~$49/mo
Large	e2-standard-4	4 vCPU, 16GB RAM, 50GB disk	~$97/mo

Locations: Iowa (US), South Carolina (US), Oregon (US), Belgium (EU), Frankfurt (DE), London (GB), Singapore, Tokyo (JP)

Provider Selection

SAM follows a Bring Your Own Cloud (BYOC) model: you provide your own cloud provider credentials through the Settings UI. The platform never stores cloud credentials as environment variables. When SAM uses your own cloud credential, VM costs are billed directly to your account.

You can set a default provider per project. When executing an idea, the provider is selected in this order:

Explicit override on submission
Project default provider
First available user or platform credential

Projects

A project links a GitHub repository to its workspaces, chat sessions, ideas, and activity. Projects are the primary organizational unit in SAM.

Each project has:

A chat-first interface — the project page is a conversation view
An Ideas board — for tracking and organizing work
A default VM size and default provider for new workspaces
A default agent type for idea execution
Runtime configuration — environment variables and files injected into workspaces

Ideas

An idea is how you describe work you want an AI agent to do. Ideas are the primary way to interact with SAM — you write what you want, and SAM handles provisioning, execution, and cleanup.

Ideas progress through these stages:

Stage	Description
Exploring	You’re brainstorming — the idea is a draft
Ready	The idea is defined and ready to execute
Executing	An agent is actively working on it
Done	The agent finished and created a PR
Parked	The idea was cancelled or the execution failed

How Execution Works

When you execute an idea from the chat interface:

SAM generates a concise title from your message (via Workers AI)
A descriptive branch name is created (sam/...)
The runner selects or provisions a node (reusing warm nodes when available)
A workspace is created with your repository cloned
The selected agent runs autonomously with your description
When done, the agent commits, pushes, and creates a PR
The workspace enters a warm pool for potential reuse

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`
Google Gemini	Google	`GEMINI_API_KEY`
Mistral Vibe	Mistral	`MISTRAL_API_KEY`
OpenCode	OpenCode managed inference	`OPENCODE_API_KEY`
Amp	Sourcegraph	`AMP_API_KEY`

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	An idea 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	Agent conversation 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