Self-host baum

This guide installs baum on a single cloud VM. The installer sets up the container runtime and baumctl; baumctl install then configures and starts the appliance.

Current platform support

Only an amd64 VM running Ubuntu is supported for self-hosting at this time. Do not use an Arm VM or another Linux distribution.

Before you begin

Prepare:

• a fresh amd64 Ubuntu VM with a public IPv4 address;
• a hostname such as example.usebaum.com;
• access to manage the hostname’s DNS records;
• inbound TCP ports 80 and 443 open in the cloud firewall;
• a TLS notification email address; and
• a GitHub account or organization that will own the baum GitHub App.

If you want pull request summary comments, also create an Anthropic API key. Pull request reviews use an OpenAI API key by default. The interactive installation flow asks for keys with terminal echo disabled, so they are not shown as you paste them.

1. Create the VM

Create a new VM with your preferred cloud provider using:

• Architecture: amd64 (also called x86-64)
• Operating system: Ubuntu
• Networking: a stable public IPv4 address
• Firewall: inbound TCP 22 for administration, plus TCP 80 and 443 for baum

Use SSH keys instead of a password where your provider supports them. Connect to the VM and apply its available Ubuntu security updates before continuing.

2. Point the hostname at the VM

Create an A record for your chosen hostname that points to the VM’s public IPv4 address. For example:

example.usebaum.com  A  203.0.113.10

Wait until the hostname resolves publicly to the VM. The installation performs a public DNS check and will stop if the name cannot be resolved.

Note

Enter the hostname without https:// or a path when baumctl asks for it.

3. Install the server prerequisites

SSH into the VM and run:

curl -fsSL https://static.usebaum.com/install-server.sh | sudo sh

The bootstrap script:

• verifies that the host is running Ubuntu;
• installs Docker Engine and Docker Compose when required; and
• installs baumctl in /usr/local/bin.

Confirm that the operator CLI is available:

baumctl --version

4. Install baum

Start the interactive installation:

sudo baumctl install

The installer asks for:

• the public hostname;
• an email address for TLS notifications;
• the GitHub account or organization that will own the GitHub App;
• a display name for the GitHub App;
• whether to enable pull request summary comments; and
• an optional Anthropic API key (entered with terminal echo disabled).

Follow the displayed GitHub App setup URL when prompted. Complete the GitHub flow in your browser and return to the terminal while the installation continues. The command checks DNS and ports, writes the appliance configuration and secrets, starts the containers, and waits for the services to become healthy.

If the process is interrupted, run the same command again:

sudo baumctl install

The installer records progress and resumes the incomplete installation.

5. Verify the appliance

Check service health:

sudo baumctl status

Then open your hostname in a browser:

https://example.usebaum.com

Once the site is available, give users the hostname and direct them to the user getting-started guide. Their CLI server URL is the site URL with /api appended.

Pull request summary comments

Summary comments are off by default. When enabled, the comment worker sends each pull request’s title, body and commit counts, plus excerpts of the linked agent sessions (prompts, short assistant replies, edited file paths, and commit SHAs with subjects), to the model provider that writes the comment. baum assumes no provider. The appliance sends this data only to Anthropic (api.anthropic.com), with the anthropic-api-key secret and the --anthropic-model chosen at installation (default claude-sonnet-5):

sudo baumctl secrets set anthropic-api-key
sudo baumctl apply --pr-comments=true

If you run the platform from config.toml instead of the appliance, set both base_url and model under [pr_comments] (or PR_COMMENTS_BASE_URL and PR_COMMENTS_MODEL) to an Anthropic-compatible Messages API you have chosen. The key goes in ANTHROPIC_API_KEY (or ANTHROPIC_API_KEY_FILE). While comments are enabled, the pr-comment worker refuses to start until both settings and the key are present.

Before users sync verdicts to repositories that require pull request reviews, read GitHub reviews and branch protection. The GitHub App’s approvals can count toward required approvals.

Enable pull request reviews

Review generation is off by default. It runs through Codex CLI with the gpt-6-luna model and an OpenAI API key, unless you choose Claude Code, which uses the Anthropic API key instead. Store the key for the harness you choose, then enable reviews:

# Codex CLI (default); the model defaults to gpt-6-luna
sudo baumctl secrets set openai-api-key
sudo baumctl apply --pr-reviews=true

# Claude Code; the model defaults to --anthropic-model
sudo baumctl secrets set anthropic-api-key
sudo baumctl apply --pr-reviews=true --pr-review-harness=claude

--pr-review-model chooses another model for either harness, and --pr-review-base-url points either harness at a compatible API endpoint, such as a gateway. Pass an empty value, for example --pr-review-model=, to return to the default. Changing the harness resets the model and base URL unless you pass them in the same command. The same flags work with baumctl install --pr-reviews. The review worker needs outbound HTTPS access to api.anthropic.com or api.openai.com, or to the base URL you set.

Review tiles

Reviews contain no visual tiles unless you allow some. To trial tiles, list the kinds that generation may offer. The kinds are database-schema, api-contract, architecture, access-model and bug-fix:

sudo baumctl apply --pr-review-tile-kinds=architecture,access-model

This setting is available on apply only, not on install. Pass an empty value, --pr-review-tile-kinds=, to stop generating tiles. The list only affects new reviews. Tiles that are already stored still appear only when the review page is opened with ?tiles=1. apply rejects a kind the catalogue does not list. If an update retires a kind you listed, that kind is no longer offered and the other kinds continue.

Review input retention

To generate a review, baum stores the pull request’s code checkout and its evidence, both unredacted, under the pr-review/ prefix of the object storage bucket. It deletes them once the review run records its outcome. As a backstop for a worker that stops between steps, the bucket also expires those objects after 24 hours:

• Bundled object storage: baum applies this lifecycle rule itself and keeps your other rules on the bucket. You do not need to do anything.

• External S3 (--external-s3): baum leaves your bucket’s lifecycle rules alone. Add a rule that expires objects under the pr-review/ prefix after one day. With the AWS CLI, for example:

  aws s3api put-bucket-lifecycle-configuration --bucket YOUR-BUCKET \
    --lifecycle-configuration '{"Rules":[{"ID":"baum-pr-review-inputs","Status":"Enabled","Filter":{"Prefix":"pr-review/"},"Expiration":{"Days":1}}]}'

  This call replaces the bucket’s whole lifecycle configuration. If the bucket already has rules, add this rule to them instead.

Lifecycle rules count whole days, and most stores remove an expired object in a background pass, so an object can outlive the 24 hours by up to about a day.

baum also clears each review run’s recorded outcome, including a rejected review document and its diagnostics, 30 days after the run finished. The validation findings of a pull request’s most recent failed review stay, so maintainers can still see why it failed.

Protect the installation

Backups contain application data, but deliberately exclude secrets. Configure an off-host backup destination and create an encrypted recovery export so that you can rebuild the appliance if the VM is lost. Follow Backups and recovery exports before putting the installation into production.

Common operator commands

Command	Purpose
sudo baumctl status	Show appliance and service health.
sudo baumctl doctor	Run every health check and exit non-zero if one fails.
sudo baumctl logs SERVICE	Stream logs for one service.
sudo baumctl update	Update to a compatible baum release.
sudo baumctl backup	Create a backup and upload it to the configured destination.
sudo baumctl recovery export	Export secrets and installation configuration as an encrypted bundle.
sudo baumctl secrets list	Show required secrets and their status.
sudo baumctl secrets validate	Validate secret presence, format, and permissions.
sudo baumctl apply	Reconcile configuration or secret changes.
sudo baumctl gate enable	Protect the entire site with a username and password.

Run sudo baumctl <command> --help for the options supported by your installed version.