Core Concepts
Workspaces
Section titled “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
Section titled “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
Section titled “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.comThe port scanner polls /proc/net/tcp inside the container every 5 seconds and recognizes common development ports (3000, 5173, 8080, etc.) with friendly labels.
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
Section titled “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
Section titled “Providers”A provider is a cloud infrastructure abstraction. SAM currently supports two providers:
Hetzner Cloud
Section titled “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
Section titled “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)
Provider Selection
Section titled “Provider Selection”SAM follows a Bring Your Own Cloud (BYOC) model: you provide your own cloud provider API tokens through the Settings UI. The platform never stores cloud credentials as environment variables — all 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 credential
Projects
Section titled “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
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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 four AI coding agents:
| Agent | Provider | API Key Variable |
|---|---|---|
| Claude Code | Anthropic | ANTHROPIC_API_KEY |
| OpenAI Codex | OpenAI | OPENAI_API_KEY |
| Google Gemini | GEMINI_API_KEY | |
| Mistral Vibe | Mistral | MISTRAL_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
Section titled “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
Section titled “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