Quickstart

This guide covers two paths: using a hosted instance (if someone has already deployed SAM) or self-hosting your own.

Using a Hosted Instance

SAM is chat-first: you import a repository, describe what you want in a chat, and SAM runs an AI coding agent that reads your code, makes changes, and opens a pull request. It provisions the environment for you — you don’t manage servers.

1. Sign In

Open the web UI and click Sign in with GitHub. Authorize the GitHub App when prompted.

2. Connect an AI Agent

Go to Settings → Connections and connect the AI coding agent you want to use — Claude Code, OpenAI Codex, Gemini CLI, Mistral Vibe, OpenCode, or Amp. Depending on the agent, you’ll paste an API key or connect a subscription. For Claude Code and Codex, a guided sign-in links your Claude Max/Pro or ChatGPT plan in the browser — no terminal needed. Your credentials stay encrypted in the database — they’re never stored as environment variables.

Note

You need cloud compute to submit tasks. On a hosted instance it’s usually provided for you. To work without any cloud credential at all, use an agent profile whose runtime is Instant container — Instant sessions start in seconds but don’t build your .devcontainer or provide Docker, and a chat on one doesn’t open pull requests for you. If you’re self-hosting or the operator requires it, add a Hetzner API token, Scaleway secret key, Vultr API key, Infomaniak application credential, DigitalOcean token, UpCloud API subaccount, or GCP credential under Settings → Connections. See Bring Your Own Cloud for the full list.

3. Install the GitHub App

Go to Settings → GitHub and click Install GitHub App on the repositories you want to use with SAM. This grants SAM access to those repositories.

4. Import a Project

From the Dashboard, click Import Project and pick a repository that has the GitHub App installed. A project links that repo to its chats, agents, and activity.

5. Chat

Open your project and type what you want done in the chat — for example, “add input validation to the signup form and write tests.” SAM automatically provisions a workspace, runs your chosen agent, streams its progress back to you in real time, and opens a pull request when it’s done. If SAM first asks you to create a profile, choose Build and open PRs, then Cloud VM, for work like this: Chat and explore and Instant container profiles give you a chat that doesn’t open a pull request.

6. Come Back Later

You don’t have to watch the chat while the agent works. The Dashboard keeps an Active Tasks list across all your projects: your six most recently active tasks — ranked by their latest message, or by when they started if they have none yet — refreshed automatically.

Each card shows the task’s status, the project it belongs to, when you submitted it, and when its last message arrived. A dot shows where the task stands: Active or Working means it is starting up or its machine is running (Active if there was a message in the last 15 minutes), Sleeping means it is asleep and can be woken, and Idle means nothing is running for it right now. A running task isn’t necessarily busy — a line below the project name shows its current step, such as Waiting for follow-up… when it’s your turn. Select a card to open its chat.

A sleeping conversation still counts as active — you can wake it for up to a week — which is why the list is ranked by recent messages rather than by start time: whatever you touched most recently stays on top, and dormant work drops off. The list only includes your own tasks that are queued, in progress, or asleep: finished, cancelled, and failed tasks are left out (even a failed task whose chat you can still wake), and so are teammates’ tasks in a shared project. Find those in the project’s session list. To hear when a task finishes or needs you, see Notifications. An agent that stops to ask permission or a question inside the chat doesn’t send a notification and isn’t flagged on these cards: its chat is marked Needs input in the project’s session list instead — see When the Agent Needs You.

That’s the whole loop: import → chat → review the PR. No terminal or server setup required.

Self-Hosting

To deploy your own SAM instance:

Prerequisites

• A domain with DNS managed by Cloudflare
• A Cloudflare account with Workers Paid plan ($5/month, required for Durable Objects)
• A GitHub account

Quick Deploy

1. Fork the SAM repository
2. Create a GitHub Environment named production in your fork’s Settings, then restrict its deployment branches and tags to the selected branch main only
3. Add the required secrets — see the Self-Hosting Guide for the full list
4. Run Deploy Production — in your fork, go to Actions → Deploy Production → Run workflow, choose main, and leave target_commit_sha empty (it deploys the current main tip)

The deployment workflow:

• Provisions Cloudflare infrastructure (D1, KV, R2, DNS)
• Deploys the API Worker and Web UI
• Builds and uploads VM Agent binaries
• Runs database migrations
• Verifies with a health check

For future updates, run the Update Self-Hosted Instance workflow to automatically sync the latest upstream release and deploy, or manually sync your fork’s main branch and run Deploy Production (SHA is optional and must be the current main tip when supplied). Pushing to main alone does not update a self-hosted instance.

For detailed step-by-step instructions, see the Self-Hosting Guide.

Next Steps

• AI Agents — choose and configure your coding agent
• Idea Execution — how chatting turns into finished pull requests
• Core Concepts — the vocabulary behind projects, agents, and workspaces