Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Getting Started

Bento is an opinionated framework for running AI agents in response to events. It provides the scaffolding and plumbing to respond to a range of triggers and run agents in ephemeral containerised sandboxes, with no human in the loop.

Prerequisites

  • Docker — for the Postgres database
  • Claude Code (claude) — the default agent runtime
  • A GitHub account (for webhook triggers)
  • macOS only: Homebrew SQLite — brew install sqlite (Apple's system SQLite omits loadable extensions, which qmd requires for vector search)
Optional — knowledge retrieval: 
npm install -g @tobilu/qmd

When qmd is on PATH, the daemon indexes your source files and injects relevant context into agent prompts. Missing → retrieval phase silently disabled.

Install

curl -sSL https://install.getbento.sh | sh

Downloads the bento binary for your platform. The installer reports where it landed (typically /opt/homebrew/bin on macOS, /usr/local/bin on Linux).

Verify:

bento --version

Start Postgres

The daemon needs Postgres at postgresql://bento:bento@localhost:8421/bento. Grab the canonical compose file and bring it up:

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

(Data lives in a named volume — docker compose down doesn't wipe it. down -v does.)

Scaffold a project

Inside the directory you want to wire up:

cd ~/dev/my-project
bento init

This creates .bento/daemon.yaml (daemon config) and .bento/pipelines/pr-review.yaml (a starter PR-review pipeline). If the directory has a GitHub remote, the repo is detected automatically.

.bento/ is gitignored by default — it holds per-developer secrets and local settings. Edit daemon.yaml to set your GITHUB_WEBHOOK_SECRET and database URL.

Register and start the daemon

Run this from the project directory (the same one where you ran bento init):

bento daemon install   # registers launchd (macOS) or systemd (Linux)
bento daemon start

bento daemon install writes a service unit that auto-restarts the daemon and runs it under your user account. bento daemon start kicks it off immediately without waiting for a reboot.

Check everything is healthy:

bento doctor

Connect GitHub webhooks

The daemon listens for GitHub webhook events. Point your repo's webhook at the daemon:

  1. Run bento doctor — it shows your webhook URL
  2. In your GitHub repo: Settings → Webhooks → Add webhook
    • Payload URL: the URL from bento doctor
    • Content type: application/json
    • Secret: the value of GITHUB_WEBHOOK_SECRET from your config
    • Events: Pull requests, Pull request reviews, Issue comments

Open a PR

Once the webhook is connected, open a pull request. The daemon receives the event, spins up an agent, and posts a review to the PR.

Watch it happen:

bento daemon logs -f

Configuration reference

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

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