<!--
Sitemap:
- [Installation](/installation): Install the Bento daemon on macOS or Linux, then write your first pipeline to run a coding agent on a GitHub, Linear, or schedule event.
- [Upgrading](/upgrading): Version-specific steps for upgrading an existing Bento install.
- [Concepts](/concepts)
- [Build your first pipeline](/tutorials/pipeline-args)
- [Target a specific issue or PR from a URL](/tutorials/url-targeting)
- [Keep state across runs](/tutorials/pipeline-state)
- [Fire a pipeline on a schedule or on demand](/tutorials/schedule-and-fire)
- [Deploy a box to Railway](/tutorials/deploy-to-railway)
- [Operate a hosted daemon](/tutorials/operate-a-hosted-daemon)
- [Configuration](/configuration): Configure the Bento daemon with daemon.yaml: service name, port, webhooks, sandboxes, knowledge base, and environment variables.
- [Members](/members)
- [Knowledge base](/knowledge-base/)
- [Method and delivery](/knowledge-base/modes): Choose how Bento retrieves knowledge (BM25, vector, or hybrid) and how it delivers that knowledge to a coding agent.
- [Config](/knowledge-base/config)
- [MCP](/knowledge-base/mcp): Give coding agents your team knowledge over MCP. The Bento daemon serves an ask_knowledge search tool and per-file resources.
- [Pipeline configuration reference](/pipelines/config): Reference for Bento pipeline YAML: triggers, agents, skills, instructions, filters, sandboxes, structured results, and outputs.
- [Filters](/pipelines/filters): Filter GitHub, Linear, and webhook events by repository, label, and other fields so only the right Bento pipelines run.
- [Triggers](/triggers/): Start a Bento pipeline from a GitHub, Linear, webhook, schedule, or manual trigger. Compare the trigger types and when each one fires.
- [GitHub trigger](/triggers/github): Run a coding agent on GitHub pull request, issue, and other webhook events. Configure HMAC verification and event patterns.
- [Linear trigger](/triggers/linear): Run a coding agent on Linear issue and comment events. Configure the Linear webhook, signature verification, and Hookdeck relay.
- [Webhook trigger](/triggers/webhook): Fire a Bento pipeline from any HTTP POST to /webhooks/{name}, with bearer-token authentication declared in daemon.yaml.
- [Schedule trigger](/triggers/schedule)
- [Manual trigger](/triggers/manual): Fire any Bento pipeline on demand with bento trigger fire, and pass typed inputs to a pipeline that runs only on request.
- [Traces](/pipelines/traces)
- [Slack](/integrations/slack)
- [Public access](/public-access): Expose the Bento daemon to GitHub webhooks through a Cloudflare Quick Tunnel or Tailscale Funnel, and compare the two options.
- [Context engineering](/context-engineering): Assemble each coding agent prompt from personas, policies, skills, and pipeline instructions. Learn which file each instruction belongs in.
- [Best practices](/best-practices)
- [Troubleshooting](/troubleshooting)
- [Architecture](/architecture/vision)
- [Workspaces](/workspaces)
- [Authentication](/authentication)
- [Identity](/identity)
- [Security](/security)
- [References](/references)
- [Changelog](/changelog): Bento release history.
- [CLI reference](/cli/)
- [Setup](/cli/setup)
- [Secrets](/cli/secrets)
- [Lifecycle](/cli/lifecycle)
- [Sandbox image](/cli/image)
- [Sandboxes](/cli/sandbox)
- [Observability](/cli/observability)
- [Diagnostics](/cli/diagnostics)
- [Triggers](/cli/triggers)
- [Workbench](/cli/workbench)
- [Auth](/cli/auth)
- [Knowledge](/cli/knowledge)
- [Evals](/cli/evals)
- [Bento docs: run coding agents from version-controlled pipelines](/index): Bento runs coding agents from pipelines you keep in your repository. Declare the trigger, sandbox, skill, and guardrails in YAML.
- [Runtime wrapper](/architecture/runtime-wrapper)
- [Skill evolve](/architecture/skill-evolve)
-->

# Installation

Bento is a command-line daemon for macOS and Linux. The installer selects the published binary for your machine and installs it in user space.

## Supported platforms

<div className="bento-platform-grid">
  <div className="bento-platform-card">
    <div className="bento-platform-card__topline">
      <span className="bento-platform-card__mark" aria-hidden="true">M</span>
      <span className="bento-platform-card__status">Automatic</span>
    </div>

    <strong>macOS · Apple Silicon</strong>
    <span>M-series Macs · arm64</span>
    <code>bento-darwin-arm64</code>
  </div>

  <div className="bento-platform-card">
    <div className="bento-platform-card__topline">
      <span className="bento-platform-card__mark" aria-hidden="true">M</span>
      <span className="bento-platform-card__status">Automatic</span>
    </div>

    <strong>macOS · Intel</strong>
    <span>Intel Macs · x86\_64</span>
    <code>bento-darwin-x64</code>
  </div>

  <div className="bento-platform-card">
    <div className="bento-platform-card__topline">
      <span className="bento-platform-card__mark" aria-hidden="true">L</span>
      <span className="bento-platform-card__status">Automatic</span>
    </div>

    <strong>Linux · x64</strong>
    <span>64-bit Linux · x86\_64</span>
    <code>bento-linux-x64</code>
  </div>

  <div className="bento-platform-card">
    <div className="bento-platform-card__topline">
      <span className="bento-platform-card__mark" aria-hidden="true">L</span>
      <span className="bento-platform-card__status">Automatic</span>
    </div>

    <strong>Linux · arm64</strong>
    <span>64-bit Linux · arm64</span>
    <code>bento-linux-arm64</code>
  </div>
</div>

Bento does not support Windows.

## Requirements

Install these tools before you configure Bento:

* `curl` and `git` — download the installer and identify your project repository.
* [Docker](https://docs.docker.com/get-docker/) with Docker Compose — runs Postgres and agent sandboxes. On macOS, [OrbStack](https://orbstack.dev/) is an alternative Docker runtime.
* [Claude Code](https://code.claude.com/docs/en/overview) (`claude`) — the default agent runtime. You also need a Claude subscription for the login flow in this guide.
* [GitHub CLI](https://cli.github.com/) (`gh`) — authenticates the GitHub integration.
* [QMD](https://github.com/tobi/qmd) (`qmd`) 2.8.3 or later — the default retrieval engine for agent knowledge. Follow [Install QMD](#install-qmd).
* SQLite — on macOS, install it with `brew install sqlite`.

Three runtimes are optional, each an alternative to Claude Code: [Codex CLI](https://developers.openai.com/codex/cli) (`codex`), `pi`, and `opencode`.

On Linux, complete Docker's [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/) for access without `sudo`. Confirm that your user has access to the running Docker daemon and Compose:

```bash
docker info
docker compose version
```

### Install QMD

Install [Node.js 22 or later](https://nodejs.org/en/download) with npm. Confirm the Node.js version before you install QMD:

```bash
node --version
npm --version
```

On Ubuntu 24.04, install SQLite and the tools that QMD's native dependencies need:

```bash
sudo apt-get update
sudo apt-get install -y sqlite3 python3 build-essential cmake
```

Install QMD under your home directory. This avoids permission errors in a system-owned npm directory:

```bash
npm install --global --prefix "$HOME/.local" @tobilu/qmd
export PATH="$HOME/.local/bin:$PATH"
qmd --version
qmd status
```

To keep this PATH in later sessions, add the export to your shell's startup file. For Bash, use `~/.bashrc`.

For other platforms, follow [QMD's requirements](https://github.com/tobi/qmd#requirements). QMD downloads its local models on first use.

If you use another retrieval engine, follow its [configuration instructions](/knowledge-base/config). Chroma needs [uv](https://docs.astral.sh/uv/) on PATH for its host embedder. Turbopuffer needs an API key.

## Install the daemon

The one-line installer supports every platform listed above. It verifies the release checksum, then installs the binary under `/usr/local/bin`, `/opt/homebrew/bin`, or `~/.local/bin`, depending on directory permissions.

```bash
curl -fsSL https://install.getbento.sh | sh
```

:::warning\[Do not use sudo]
Run the Bento installer and daemon as your own user. Dependency installation, such as `apt-get`, may need elevated permissions.
:::

Add the user installation directory to your current PATH, then print the version:

```bash
export PATH="$HOME/.local/bin:$PATH"
bento --version
```

If the installer selects another directory, follow its PATH instructions. Run the remaining commands as this same user.

## Install a specific version

For a reproducible install or a rollback, set `BENTO_RELEASE`:

```bash
curl -fsSL https://install.getbento.sh | BENTO_RELEASE=0.6.5 sh
```

## Bootstrap a project

Authenticate your GitHub CLI account before initialization, so Bento detects the login:

```bash
gh auth login
gh auth status
```

Go to your existing project checkout. Replace `PATH_TO_PROJECT` with its path:

```bash
cd PATH_TO_PROJECT
bento init
```

The command writes six files: `.bento/daemon.yaml`, `.bento/.gitignore`, `.bento/pipelines/pr-review.yaml`, `agents/reviewer/PERSONA.md`, `CLAUDE.md`, and `.mcp.json`. It reads the `origin` git remote and the `gh` login to fill in `repos:` and `github.username`.

## Set up the database

The daemon looks for Postgres at `postgresql://bento:bento@localhost:8421/bento`. To change that address, edit `.bento/daemon.yaml`. To start a Postgres instance at the default address, use Docker:

```bash
curl -fsSL https://install.getbento.sh/services.yml -o docker-compose.yml
docker compose up -d
```

Wait until Postgres reports `healthy` before you continue:

```bash
docker compose ps
```

`docker compose down -v` removes the volume and all data.

## Authenticate the daemon

From your project directory, authenticate the Claude account that Bento uses:

```bash
bento setup claude personal
```

Complete the login prompts. Bento stores the credential under your home directory and adds its path to `.bento/daemon.yaml`. Installing `claude` alone does not authenticate it. For another runtime, follow [runtime authentication](/cli/setup).

Check that `github.username` in `.bento/daemon.yaml` names the account that should act on your repository. Then authenticate that account for this daemon:

```bash
bento setup gh
```

The daemon uses its own GitHub profile. Your earlier `gh auth login` supplies the identity for initialization.

## Store the webhook secret

The starter configuration requires a GitHub webhook secret before the daemon starts. Create a random secret in your password manager. Keep it for the repository's GitHub webhook configuration.

For a new installation, generate the database encryption key:

```bash
bento secrets key --generate
```

In Bash, paste the secret at the prompt. The command stores it in Postgres without putting the value in shell history:

```bash
read -r -s -p "GitHub webhook secret: " WEBHOOK_SECRET
printf '\n'
printf '%s' "$WEBHOOK_SECRET" | bento secrets set webhook/github
unset WEBHOOK_SECRET
```

In `.bento/daemon.yaml`, replace the GitHub source's `secret: ${GITHUB_WEBHOOK_SECRET}` line with `secret_ref: webhook/github`:

```yaml
webhooks:
  host: 127.0.0.1
  sources:
    github:
      verify: github
      secret_ref: webhook/github
```

Keep the secret value out of repository files. Back up the encryption key as described in [key management](/cli/secrets#key-location). The daemon reads the key and decrypts the stored secret at startup.

## Start the daemon

Validate the configuration, then start the daemon:

```bash
bento config validate
bento daemon start
```

Confirm that the daemon is reachable and its prerequisites are ready:

```bash
bento daemon status
bento doctor
curl -fsS http://127.0.0.1:7890/health
```

If you change `port` in `.bento/daemon.yaml`, use that port in the health URL. Wait until the response reports `readiness.state: "ready"`. If it reports `pending`, wait and check again. If it reports `failed`, resolve the listed prerequisites and restart with `bento daemon restart`. See [startup readiness](/cli/lifecycle#startup-readiness).

### Install a user service

On Linux, check that your systemd user manager is available before you install the service:

```bash
systemctl --user status
```

If it reports a bus connection error, resolve the user session before service installation. A plain Docker container has no systemd user manager. Use `bento daemon start` without service installation there. For foreground diagnostics, run `bento serve` and check readiness from a second terminal.

To register the daemon with launchd on macOS or systemd on Linux, stop the detached daemon first:

```bash
bento daemon stop
bento daemon install
bento daemon start
bento daemon status
bento doctor
curl -fsS http://127.0.0.1:7890/health
```

Confirm that readiness returns to `ready` after the service starts.

## Your first pipeline

`bento init` scaffolded a `CLAUDE.md` and an `.mcp.json` into your repository. Open the repository in an AI coding agent such as Claude Code, Codex, or Cursor. The agent reads `CLAUDE.md` to learn how bento works, and connects to the `bento` MCP server declared in `.mcp.json`. Ask it to build your first pipeline: an agent persona, the pipeline YAML, the webhook registration, and a test run. Use the same secret from your password manager when you register the GitHub webhook.

For the concepts behind agents, skills, and pipelines, see [Concepts](/concepts). For the full pipeline field reference, see [Pipelines: Config](/pipelines/config).

## Configuration reference

`.bento/daemon.yaml` controls daemon-wide settings: the database URL, the ports, the sandbox backend, and the pipeline lifecycle hooks. Each file under `.bento/pipelines/` is one pipeline definition. See [Configuration](/configuration) for the full field reference.

**Runtime state** (the PID, the log, and the agent directories) lives under `~/.bento/<name>/`, where `name` is the `name:` field in `daemon.yaml` and defaults to `bento`. Workspaces are shared at `~/.bento/workspaces/`. Neither directory is committed to git.
