Run your first agent

This is the shortest path that demonstrates Fountain's whole job. An agent starts in a sandbox with a real repository, inspects the checkout, and streams its answer to your terminal.

The example uses Fountain's public repository. It needs no GitHub token, setup script, package install, or Vault.

Choose where Fountain runs

Run the server yourself, or use the hosted server. The manifest and the agent run are the same on both.

Run your own server

You need Docker, OpenSSL, and a sandbox provider token. The Compose file runs Postgres. The example below uses Sprites as the sandbox provider.

git clone https://github.com/BinaryBourbon/fountain
cd fountain
cp .env.compose.example .env

echo "SECRET_KEY_BASE=$(openssl rand -base64 48 | tr -d '\n')" >> .env
echo "MASTER_SECRETS_KEY=$(openssl rand 32 | base64 | tr '+/' '-_' | tr -d '=\n')" >> .env

# Add your SPRITES_TOKEN to .env, then start Fountain.
docker compose up -d

Open http://localhost:4000. Create the first operator account, then add an Anthropic credential under Account, then Inference keys.

The Compose defaults self-verify the first account and make it the admin. Create that account before you expose the server to another network. The deployment guide shows how to verify readiness, close registration, and configure the other sandbox providers.

Use the hosted server

Create an account on managoat.com, then add an Anthropic credential under Account, then Inference keys. The hosted server supplies the control plane and sandbox provider.

Install and authenticate the CLI

On macOS, install the CLI with Homebrew.

brew install BinaryBourbon/tap/fountain

On Linux, Homebrew needs a C compiler before it installs a formula, build-essential on Debian and Ubuntu. The release binary has no such need.

curl -fsSLo fountain \
  https://github.com/BinaryBourbon/fountain/releases/latest/download/fountain-linux-amd64
chmod +x fountain
sudo mv fountain /usr/local/bin/

Use fountain-linux-arm64 on an ARM machine.

Point the CLI at the server you chose.

# Your own server
FOUNTAIN_BASE_URL=http://localhost:4000 fountain auth login

# Hosted server
fountain auth login

auth login shows a one-time code and opens the console's approval page in your browser. Approve the device there. The CLI saves the server URL and an API key, so the commands below need no server flag.

Apply and run

Download the small manifest, apply it, and call the agent by name.

curl -fsSLo fountain.yml \
  https://raw.githubusercontent.com/BinaryBourbon/fountain/main/examples/quickstart/fountain.yml

fountain apply -f fountain.yml
fountain run fountain-reader -p \
  "Find the code that reclaims an idle sandbox. Explain when it runs and name the files you read."

The clone already contains the manifest. If you run your own server from the checkout, skip the download. Apply examples/quickstart/fountain.yml from the repository root, so the manifest matches the code you deployed.

apply creates two reusable rows. The Environment says which repository the sandbox receives. The Agent says which runtime and model work in it.

run creates the Conversation. Fountain starts the sandbox, clones the repository, starts Claude, and streams the work and final answer. The command prints the conversation id first. Use it for a follow-up.

fountain conv prompt <conversation-id> -p \
  "Now trace the call one level deeper. What stops two reclaimers from racing?"

The follow-up lands on the same sandbox. The checkout and the agent session are still there.

What the example leaves out

The example has no Vault because it reads a public repository. Add a Vault when a run needs a credential that changes independently from the machine or the Agent. The guided tour adds a GitHub token, changes a repository, and opens a pull request.

The example uses Claude because it is Fountain's most exercised runtime. To use Codex, Gemini CLI, or OpenCode, change runtime and model in the manifest and add that provider's inference credential. The runtime catalog lists the accepted shapes.