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. 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.

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 enter the exact 40-character commit SHA at that branch 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, sync upstream changes into your fork’s main branch, then run Deploy Production again with the exact synced commit SHA. 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