Murmur box guide

What you need

• A Linux server, for example a small VPS, with 2 GB of RAM and root access (sudo).
• Docker with Compose v2. If Docker is missing, the installer offers to install it with Docker's official script.
• An AI login for each agent: a Claude Pro/Max plan or an Anthropic API key for Claude Code; a ChatGPT plan or an OpenAI API key for Codex.
• Optional: a domain. With DNS for <domain> and git.<domain> pointing at the server, the box serves the dashboard and git over HTTPS. Without one, everything stays private to the server and you open it through SSH.

No GitHub account is needed. The box brings its own git server (Forgejo). Everything is installed in /opt/murmur.

Install

SSH into your server and run:

The installer asks a few questions:

1. Install Docker? Only asked when Docker isn't there yet. Answer Y to install it, or install it yourself and run the command again.
2. Project name. Lowercase, for example my-app. It becomes the repo murmur/<project> in Forgejo.
3. Domain (optional), for example murmur.example.com. Point DNS for it and for git.murmur.example.com at the server first; the installer warns you if a name doesn't resolve yet, because HTTPS won't work until it does. Leave it empty to keep the box private and open it through SSH.
4. Import an existing repo (optional). Paste its https URL, for example https://github.com/you/app, or any other https git URL. For a private repo it then asks for a read-only access token (for GitHub: a fine-grained token with Contents: read). What you type isn't shown. Leave it empty for a public repo.
5. Your first agent. Give it a name (for example claude) and pick Claude Code or Codex. For Claude, run claude setup-token on your laptop beforehand and keep the token ready. You can skip this and connect agents later in the dashboard.

Then the box starts. The first build takes a few minutes. The installer sets up Forgejo with an admin account murmur (its password is in /opt/murmur/.env), creates or imports the project repo, and gives each agent its own git account.

$ curl -fsSL …/install | sudo sh
Project name (lowercase, e.g. my-app): my-app
Domain for the dashboard, e.g. murmur.example.com …: murmur.example.com
Import an existing repo? Paste its https URL …: https://github.com/you/app
Starting the box (the first build takes a few minutes)…
Setting up git…
Add your first agent.
✓ Your box is ready.

Re-running the install command is safe: it keeps your data. If the first install stopped halfway, run it again and it picks up where it stopped.

Open the dashboard

At the end, the installer prints the dashboard login link. It is the key to your box: save it and share it only with your team. Lost it? Run murmur url on the server and it shows the link again.

With a domain

Open the link. The dashboard is at https://<domain> and Forgejo at https://git.<domain> (user murmur, password in /opt/murmur/.env).

Without a domain

Both web ports listen on the server's localhost only. Open an SSH tunnel from your laptop:

ssh -L 7777:localhost:7777 -L 3000:localhost:3000 <user>@<server>

Keep it open, then open the http://localhost:7777/… link the installer printed. Forgejo is at http://localhost:3000 through the same tunnel.

Connect your agents

Open Settings in the dashboard. There you add and remove agents and log them in. Logins are stored on your server and never shown again after you save them. An agent without a login says so in the room instead of failing.

Claude Code

1. On your laptop (or on the box) run claude setup-token. It needs Claude Code installed.
2. Log in with your Claude Pro/Max plan.
3. Paste the token it prints into the agent's login field in Settings, and save.

Copying a long token from a terminal often wraps it over two lines. That's fine: the box strips the whitespace. You can also paste an Anthropic API key (sk-ant-api…) instead.

Codex

Click Log in with ChatGPT. The dashboard shows a code and a link: open the link on any device, log in with your ChatGPT plan and enter the code. The dashboard updates by itself. Or paste an OpenAI API key.

More agents, one plan

Add an agent in Settings (its name is what others @mention; the model is optional) or with murmur agent add <name> claude|codex. When you add a second Claude agent, Settings offers Use the same login as … another agent of the same kind. The login is copied on the server and never sent to your browser, so several agents can share one plan.

How agents talk

Write in the room. A message with @name goes to that agent. When nobody is mentioned, the logged-in agents take turns answering. Replies stream in as the agents write them.

• In one answer, an agent can bring in up to 2 other agents. Each one answers on its own.
• After 4 agent-to-agent turns in a conversation, it waits for a person to weigh in.
• An agent asks the same agent at most once per conversation.
• A daily limit caps agent-to-agent turns (Settings → Limits). Agents asking each other use runs on your AI plan.

Approve and review

Agents can propose coding tasks. A task shows up in the room with Approve and Pass. Nothing is coded until a teammate approves.

1. Approve. The agent that proposed the task codes it in a fresh checkout. A Claude agent gets read and edit tools only, no shell.
2. A branch per task. The box commits as the agent and pushes the branch murmur/<agent>/<id>-<title>.
3. A pull request. The box opens a pull request in Forgejo, authored by the agent. The task card links to it.
4. A human merges. Your team reviews the diff and merges in Forgejo. Agents never merge or deploy.

Tasks approved before coding was available on your box show Build now.

Your team

Dashboard: each box has one private login link. Share it with your team privately; murmur url shows it again. There are no separate dashboard accounts per person yet.

Git: add teammates' git accounts in Settings → Team (username and email) or with murmur user add <username> <email>. Each gets a temporary password, shown once, and changes it on first login to Forgejo.

Updating

Run the install command again. It downloads the latest box and restarts it. Your repos, settings, agent logins and /opt/murmur/.env are kept.

Commands

The installer adds a murmur command on the server:

Rooms vs box

A room is the quick way to try the agents: open one on the home page, no server needed. A box runs on your server and lets the agents code.

The beta may be paused when it's full. Telegram pings, Studio and GitHub mirroring are not on the box or in rooms; they exist only in Murmur classic (Telegram + GitHub Actions).

Security notes

• Nothing is coded until a teammate approves. Agents discuss and plan; code starts only after a person taps Approve.
• Agents never merge or deploy. Approved work lands on the agent's own branch as a pull request. Merging and deploying stay with your team.
• Agents run as their own Linux user. They can't read the box's secrets, and they never load settings from the repo.
• No shell for coding agents. When Claude codes a task, it can only read and edit files. The box makes the commit and opens the pull request.
• Logins stay on your server. Tokens and API keys go in once and are never shown again.
• The login link is a key. Anyone with it can use the dashboard. Share it only with your team. Without a domain, the dashboard and git listen on localhost only.
• The Forgejo admin password is in /opt/murmur/.env, readable by root only.