Quick start · Hyperbeam docs

This runs agents as ordinary local processes with no isolation. It is for trying Hyperbeam out and for working on it. To keep it running on your own machine, with each agent in its own sandbox, run it in a local cluster. To run it for a team, install it on Kubernetes.

Before you start

You need Docker (for Postgres), Rust and Bun.

1. Start Postgres

Terminal

docker run -d --name hyperbeam-pg -e POSTGRES_USER=hyperbeam -e POSTGRES_PASSWORD=hyperbeam \
  -e POSTGRES_DB=hyperbeam -p 127.0.0.1:5440:5432 postgres:16

2. Build Hyperbeam

The web UI is embedded in the server binary, so build it first.

Terminal

(cd web && bun install && bun run build)
cargo build --release

3. Start the server

Terminal

export HYPERBEAM_DATABASE_URL=postgres://hyperbeam:[email protected]:5440/hyperbeam
export HYPERBEAM_MASTER_KEY=$(./target/release/hyperbeam-server gen-key)
./target/release/hyperbeam-server serve

Warning

Keep the master key. It encrypts every stored credential, and if you change the setting, the credentials stored with the old one can no longer be read. To change the key, rotate it.

Open http://localhost:8080. The first person in creates the team and owns it.

4. Connect an agent

Hyperbeam drives coding agents over the Agent Client Protocol (ACP). In this local mode the agent runs on your machine, so install its ACP adapter. For Claude Code:

Terminal

npm i -g @agentclientprotocol/claude-agent-acp

Then give it a credential:

Open Settings → Harnesses and select Claude Code.
Add an Anthropic API key, for the team or just for yourself. Or add your own Claude subscription token from claude setup-token; it is used only for your sessions.

Codex, Gemini CLI and OpenCode work the same way. See Harnesses and models and Credentials.

5. Start your first agent

Press C, or select New work.
Describe the task, and pick Claude Code under Harness if it is not already the default.
Select Start agent.

You land on the agent’s page and watch it set up its sandbox, plan, run commands and reply. Send it a message to continue the conversation. To let agents clone your repositories and open pull requests, connect GitHub under Settings → Integrations. See Set up a team.

Next steps

Concepts explains workstreams, sessions, sandboxes and grants.
Set up a team connects GitHub and invites people.
Run in a local cluster moves this setup into sandbox pods on your machine.