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

# Diagnostics

## `bento config validate`

Validate the config on disk: `.bento/daemon.yaml`, every pipeline and capability file, `members.yaml`, and `groups.yaml`, plus the agents and skills they reference. It runs the same static configuration checks as daemon startup. Startup also checks live dependencies.

It reads files only. It needs no daemon, no database, and no sandbox, so it runs safely in CI or in a pre-commit hook.

```bash
bento config validate
```

When the config is invalid, the command exits `1` and lists each error. Otherwise it exits `0`.

An unset `${VAR}` reference is a warning, not an error. The loader expands a missing variable to an empty string, and the same config is valid on a host that holds the secrets and in CI, which holds none.

One limit follows from that. An unset reference leaves an empty value, and an empty value is also what a secret written as `""`, `null`, or nothing at all leaves. This command does not tell them apart, so it accepts every declared secret. A secret that is declared nowhere is still an error. The daemon rejects an empty one at startup, where the environment is known.

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

Host-dependent checks stay in `bento doctor`: whether a runtime is installed, whether a credential is present, and whether the database is reachable.

## `bento doctor`

Validate the infrastructure: config, database, runtimes, sandbox, tunnel, Daytona, authentication, repositories, orchestrator, worktrees, workloads, queue, and credentials. `bento.doctor.yaml` defines the checks.

The credentials section reads the daemon's live rotation state through `GET /credentials/status`. It prints each credential's status. For a credential on cooldown after a subscription cap, it also prints the reason and the next available time. The pool resides in memory. If the daemon is not available, this section reports a warning.

The queue and credentials sections send the token from `~/.bento/credentials`, the same token that `bento queue status` sends. If the daemon answers with 401 or 403, the section reports that the daemon rejected the CLI token. It does not tell you to start the daemon. Run `bento auth setup`, then `bento daemon restart`. The daemon reads the token only when it starts.

A fallback after an authentication error does not always disable the credential. Bento disables it only when the runtime's own terminal event rejected it. The same error read off stderr or off quoted agent output leaves the credential available for later runs, and it does not start a fallback either. That text matches no failure category bento recognizes, so the run stops on the first candidate. See [credential rotation and recovery](/configuration#targets) for the distinction between fallback, cooldown, and a dead credential.

```bash
bento doctor
```

| Flag | Description |
|------|-------------|
| `--fix` | Auto-remediate issues (requires per-check opt-in in `bento.doctor.yaml`) |
| `--json` | Output as JSON |

## `bento probe <scope> [target]`

Run a single sandbox probe.

```bash
bento probe runtime claude
bento probe env ANTHROPIC_API_KEY
bento probe gh-auth
bento probe git-version
bento probe git-cache-lock
bento probe ping claude-high
bento probe ping --targets
```

| Scope | Target | Description |
|-------|--------|-------------|
| `runtime` | `<name>` | Check that a runtime is installed and callable |
| `env` | `<KEY>` | Check that an environment variable is visible in the sandbox |
| `gh-auth` | — | Check GitHub authentication |
| `git-version` | — | Report the git version inside the sandbox |
| `git-cache-lock` | — | Start two containers against one bind-mounted scratch cache and check that `flock` serializes them. The second container tries the lock with `flock -n` while the first holds it. The shared git cache's whole contract rests on that lock. A bind mount whose filesystem drops `flock` (Docker Desktop's virtiofs or gRPC-FUSE on darwin) makes every caller look uncontended. The probe needs a container backend. A backend that ignores bind mounts reports the probe as not applicable. |
| `ping` | `<target>` | Round-trip a minimal request using the target's runtime, model, effort, and credential |
| `ping` | `--targets` | Ping every target configured in `daemon.yaml` |

| Flag | Description |
|------|-------------|
| `--timeout <seconds>` | Per-probe timeout |
| `--instance <name>` | Target daemon instance (default: cwd config, else the running instance) |
