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

# Workspaces

When a trigger fires against a target that carries a repository, the daemon creates a **workspace**: a persistent directory tied to that target and shared by every trigger that resolves to it. A pull request that receives three successive pushes gets three invocations in the same workspace. Subsequent prompts include workspace notes and a compact prior-run index.

## Directory layout

Workspaces live under `~/.bento/workspaces/`, one directory per workspace key (see [Workspace keys](#workspace-keys)). Inside each workspace:

```
~/.bento/workspaces/<hash>/
  workspace.state.json
  runs/
    <run-id>/
      meta.json          ← trigger metadata and optional one-line result
      output.md          ← completed final reply
      attempts/<number>/ ← raw runtime stdout and stderr
      steps/             ← hook artifacts
  checkout/
    worktrees/<run-id>/
```

The daemon bind-mounts only `checkout/` at `/workspace` inside the sandbox. Run metadata, transcripts, notes, and workspace state remain daemon-side. The Docker and Podman backends also bind-mount a per-repo git object cache from `~/.bento/gitcaches/<hash>/` over `/workspace/.gitcache` inside the sandbox. This cache lives outside the workspace directory and is shared across all threads of the same repo.

## State across runs

The agent records structured notes during a run with the MCP `submit_note` tool. Bento persists those notes in the database and includes bounded note context in later prompts for the same workspace. Notes can carry open fields, including the identifier of a note that a later note supersedes.

When a run finishes, Bento writes the completed final reply to `output.md` and stores an optional structured result on the Invocation. Later prompts receive one index line per prior run: run ID, age, trigger, and a bounded result summary when present. An agent can call MCP `get_run` with a run ID from that index to retrieve the structured record: the lifecycle status, the full final output, an optional structured result, the diagnostic that ended a failed run, and notes. A pending or running run returns a record that carries its status, so a caller can tell an unfinished run from an unknown one. Only an unknown run ID, or a run on another thread, reads as not found. The CLI provides the same read with `bento invocation get-run <run-id>`; use `--format json` when a script needs the complete record. Bento does not backfill an existing run. A run without a result remains in the index as metadata only.

Example: on a first PR invocation the agent records which files it flagged. On the next push it reads those notes and checks whether they were addressed.

## Workspace keys

Every workspace is tied to a stable key derived from its target or named pipeline:

| Source | Key |
| --- | --- |
| GitHub PR or branch | `github:owner/repo:<branch>` |
| Linear issue | `linear:<issue_id>` |
| Named schedule | `schedule:<pipeline-name>` |
| Named manual run | `manual:<pipeline-name>` |

Two triggers with the same key share one workspace. A trigger that names a target but does not resolve its key fails. Bento extracts a GitHub target. It does not extract a Linear or a Slack target.

A trigger without a repository target produces no workspace. Examples include a cron job with no `repo:` and a knowledge-only MCP call.

## Parallel safety

Each agent run gets its own git repository, cloned with `--reference` on the per-repo object cache. Objects are shared. Refs are not, so parallel runs against the same workspace never collide on a branch, and any run checks out any branch.

## Storage and cleanup

Each workspace directory contains a `workspace.state.json` file written on every run. It records the workspace key, kind, source repo and branch (when known), and `first_seen_at` / `last_seen_at` timestamps. The file is daemon-side bookkeeping and is never mounted into the sandbox.

At startup, the daemon removes old workspace data in tiers. It walks `~/.bento/workspaces/` and measures each workspace's activity. Activity is the newest of `last_seen_at` in `workspace.state.json` and the newest run, so a stale state stamp beside a fresh run does not reap it:

* Past the **no-activity window** (default 30 days), the daemon reaps the regenerable `checkout/`, which holds the object cache and the per-run clones and nearly all the disk. The run transcripts under `runs/` stay, and notes remain queryable in the database beyond workspace retention.
* Past the longer **transcript-retention window** (default 90 days), the daemon removes the whole workspace. The per-turn agent transcripts live only on disk, so they outlive the checkout that produced them.

For a directory without a state file or runs, activity is its own modification time (mtime) before the sweep starts. The daemon applies the same retention tiers to that age. Fresh directories interrupted during preparation remain within retention, so the daemon keeps them. The daemon logs each reap and each deletion with the workspace key, the path, the activity timestamps, and the reason.

To change the windows, set them in `.bento/daemon.yaml`:

```yaml
workspaces:
  checkoutRetentionDays: 14
  transcriptRetentionDays: 60
```
