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

# Identity

The agent acts under its own identity — not yours. When it posts a review comment, pushes a commit, or opens a pull request, bento attributes that action to the agent's credentials, not yours. This page covers agent credentials. For bearer tokens used to authenticate calls to the daemon, see [Authentication](/authentication).

## Access scoping

Give the agent only the permissions its pipeline requires.

Two practical consequences:

* **Scope.** A review pipeline that only posts comments holds no token with push access to production. Declare the minimum permissions the pipeline uses.
* **Revocation.** If a pipeline misbehaves, revoke its token without revoking your own credentials.

## Credential delivery

Actor runs receive the GitHub principal selected by their pipeline execution boundary. Observer runs do not receive GitHub credentials. Set `guardrails.read_only: true` or use a dry run to run a pipeline as an observer.

On macOS, the daemon reads each token through `gh auth token` and injects the selected token into actor sandboxes as `GH_TOKEN`. Explicit-principal sandboxes do not receive the shared GitHub CLI profile. Git configuration carries the selected account's verified name and noreply email.

## GitHub identity

For one GitHub account, bento uses the compatibility `github.username` configuration without changing the host's default `gh` identity.

1. Create a dedicated GitHub account for the Agent principal, for example `your-org-agent`.

2. Issue a fine-grained personal access token for that account with only the permissions the pipeline needs.

3. Set the account in `.bento/daemon.yaml`:

   ```yaml
   github:
     username: your-org-agent
   ```

4. Authenticate `gh` as the Agent principal:

   ```bash
   bento setup gh
   ```

5. Restart the daemon:

   ```bash
   bento daemon restart
   ```

   The startup log records the selected principal as `github: agent login = @<login>`.

### Authentication options

To read an existing token from an environment variable, pass its name. Bento verifies that the token belongs to `github.username` before it stores the token in the instance profile:

```bash
bento setup gh --env AGENT_GITHUB_TOKEN
```

On a dedicated remote daemon host, also authenticate the machine's default `gh` profile:

```bash
bento setup gh --env AGENT_GITHUB_TOKEN --host
```

On a workstation where the existing `gh` identity stays as it is, do not pass `--host`. A remote actor sandbox receives the resolved token as `GH_TOKEN` on each run.

The daemon always reads and mounts `~/.bento/<name>/gh`. `github.username` selects the Agent principal explicitly from the keyring of that profile. The daemon resolves the token at startup and uses it for daemon-side API calls, post-backs, git attribution, and actor sandboxes.

## Principal bindings

A pipeline makes several provider accounts available under role-shaped names. Each direct run or actor capability selects one binding:

```yaml
principals:
  pull-request-author: github.principal.your-org-author-agent
  pull-request-reviewer: github.principal.your-org-review-agent
  issue-coordinator:
    - github.principal.your-org-author-agent
    - linear.principal.bento-agent
principal: pull-request-reviewer
```

A binding contains at most one principal per provider. Skills declare the binding names they require. They do not declare account names or credential locations. A direct selector names a role that the pipeline skill or a companion declares. A capability selector names a role that the skill of that capability declares. Bento validates requirements and selectors at startup, delivers only the selected binding, and retains that selection through generic orchestrator tasks, retries, and model fallback.

Authenticate every referenced GitHub principal:

```bash
bento setup gh --principal github.principal.your-org-author-agent --env AUTHOR_GITHUB_TOKEN
bento setup gh --principal github.principal.your-org-review-agent --env REVIEWER_GITHUB_TOKEN
bento daemon restart
```

Trace tasks record `principal_binding`, `principal_ref`, and the stable `principal_provider_id` returned by the provider. GitHub references use the account login as an operator-facing alias. The provider id preserves audit correlation if the login changes. The trace records no credential value.

## Token scoping

Use a fine-grained GitHub token to limit the agent's access. Match the scopes to the needs of the pipeline:

| Pipeline type | Scopes needed |
| --- | --- |
| Post review comments | `pull_requests: write` |
| Push commits | `contents: write` |
| Open or close PRs | `pull_requests: write` |
| Read-only analysis | `contents: read` |

A token with only `pull_requests: write` fails a push, even when the pipeline attempts one.
