<!--
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)
-->

# Best practices

## Start simple

Begin with a single agent and omit the `orchestrator` field. Add explicit auto orchestration only once the work needs model-selected chaining or parallelization.

## Inspect before tuning

Before you run a pipeline, inspect the input that the agent receives:

```bash
bento trigger inspect <id> --prompt          # the user prompt
bento trigger inspect <id> --system-prompt   # the assembled system prompt
bento trigger inspect <id> --size            # token breakdown
```

Most output quality problems are prompt problems, visible before the agent runs. Once a trigger exists in the store, re-run it at any time without waiting for a real event:

```bash
bento trigger replay <trigger-id>
```

When a pipeline produces poor output, read the trace:

```bash
bento trace <trigger-id>
```

The trace shows each phase — trigger, invocation, spawn — with timing and status. Bento extracts the agent messages from the run log.

## Invest in the knowledge base before skills

Before you add a skill, verify that `wiki/`, `blueprints/`, or `recipes/` contain the domain context that the agent needs.

See [Knowledge Base](/knowledge-base).

## One skill per procedure

A skill that does one specific thing is easier to tune, review, and reuse than one that branches across multiple cases. If a pipeline needs to do two different things depending on the trigger, write two pipelines — each with its own narrow skill.

See [Context Engineering](/context-engineering).

## Start read-only, then enable write-back

Before enabling a pipeline to post comments, push commits, or open PRs, run it without write credentials and review the output via `bento trace`. Add the credential mounts once you trust what the agent produces.

```yaml
# start here — agent runs but cannot write back
sandbox:
  mounts: []

# add mounts once output is verified
sandbox:
  mounts:
    - host: ~/.config/gh
      container: /home/node/.config/gh
```

## Always set a timeout

An unbounded agent run consumes resources and blocks a queue slot. Declare a timeout in every pipeline:

```yaml
guardrails:
  timeout: 300   # seconds
```

300 seconds is a reasonable starting point.

## Scope credentials to the minimum

Mount only what the pipeline actually needs. A review pipeline that posts comments does not need push access. A read-only analysis pipeline does not need any external credentials.

See [Identity](/identity).

## Be intentional about workspace notes

An agent calls the MCP `submit_note` tool during a run to pass durable state to the next invocation on the same target. Bento stores each structured note in the database, and a later run can retrieve a prior run's full record with MCP `get_run` or `bento invocation get-run <run-id>`. This accumulates — stale notes from a prior run will influence future runs on the same workspace.

Prune notes when a target's context has changed significantly (a PR was rebased, a ticket was reprioritized). Stale notes are worse than no notes.

## Review before you automate

Run a new pipeline manually a few times via `bento trigger replay` and review each trace before letting it run unattended on real events. Verify:

* The prompt contains the context you expect.
* The agent's output is in scope.
* Write-back (if any) produces the right artifact.
