Skip to main content

Setup & configuration

Workspace Trust

Opening a folder Bodega has not seen before puts up a trust prompt. What that prompt actually controls is whether the folder's own .bodega/config.json is allowed to change your settings, a cloned repo cannot reconfigure your agent until you say so. Separately, a folder Bodega has not been given access to before also asks whether Bodega may read and edit files in it. If you cancel that prompt the project is not opened: you get a plain message and a Try again button. This page is precise about what trust does and does not cover, because the difference matters.

When the prompt appears

Two moments: opening a project from the picker, and reopening your last project at startup. Bodega asks the backend whether the path is already trusted; if it is, nothing appears and the project opens.

The check fails closed: if it errors, the path is treated as untrusted. You get the prompt rather than a silent grant.

  • Trust Workspace records the folder as trusted and opens it.
  • Not now declines, and the project still opens. Declining is not a refusal to work in the folder; it is a refusal to apply the folder's config.

When you decline, a dismissible Project config inactive chip appears so the state is visible rather than assumed.

What trust actually controls

The enforced effect is a single, sharp one: an untrusted folder's .bodega/config.json is not loaded as settings. The path behaves exactly as if the file were not there for project routing rules and for the project-settings view.

Even with trust, only two allowlisted keys take effect today: routing rules and named run configs (the Run Tasks launcher reads run configs directly). The rest of the allowlist is accepted in the file but not applied yet. The allowlist itself is fixed, model and token settings, the persona prompt and name, agent iteration and dual-model settings, guardrail limits, the three panel prompts, editor formatting preferences, named run configs, and routing rules. Keys that would let a committed repo change where your prompts go or widen your exposure are global-only and are excluded on purpose: cloud escalation, the mixture tools, llama.cpp custom arguments, the shell environment policy, and the deferred-tools mode. A repo you clone cannot reach any of them, trusted or not.

Routing rules are the one entry with different mechanics, they are added above your own rules rather than replacing them, and a request they route always says so in its routed-by line.

Trust is not a filesystem sandbox. The agent's file access is bounded separately, by the project-directory enforcement described under Privacy & Security, and that applies whether or not you granted trust. Do not read the prompt as "nothing can be read or written until I approve".

Where trust is stored, and undoing it

Trust records live in a local SQLite table keyed on a normalised path, resolved to an absolute path, forward-slashed, and lower-cased on Windows only. A folder with no row is untrusted; granting trust is an idempotent upsert that also keeps the original path spelling for display.

Every way of opening a folder asks for trust the same way, including the top-bar menu's Open Folder and the native File menu; a folder you open appears in Recent projects. If a folder is new to Bodega, a system prompt asks whether Bodega One may read and write files in it. Cancel closes the project (nothing is left half-open) and a notice says it was not opened because Bodega needs your permission, with Try again.

Revocation exists in the backend and in the API client, but there is no UI button for it today: no settings row, no context-menu entry. If you need a folder untrusted, that is currently not something you can do from the app.

One behaviour to know if revocation does reach you: it is forward-only. It marks the record untrusted so future opens do not load the config; it does not retract config already applied to a running session. Reopen the project to be sure.

Project skills are a separate approval

A repo can also ship skills in .bodega/skills/. Those are gated independently of workspace trust and are not covered by it, trusting a workspace does not approve its skills.

Unapproved project skills are refused outright: not loaded, not listed, not invocable. When a project has any, a "N skills need approval" chip appears; clicking it takes you to Settings → Connections → Skills, where each skill has its own Approve button.

Approval is keyed to the exact file contents and the exact project path. Editing an approved skill's file invalidates its approval and it has to be approved again, which is the point: the thing you approved is the thing that runs.

Environment setup scripts

An environment (see Getting Started) can carry a setup script, such as npm ci or copying a config file. It is yours, saved for you and never read from a project's .bodega/config.json, so trusting a folder never brings a script with it.

  • It never runs unasked. The first time, and every time after the script's text changes, a Review the setup script card shows the whole script, where it will run and the time limit. Run script runs it, Skip starts the session without it, Don't run and stop archives the session and removes its worktrees. When the environment's default mode is Ask the card appears on every start; when it is Act, only when the script changed since you last approved it. With no default mode set, starting the environment from the app or with bodega env start asks every time, while bodega run --env <name> "task" starts in Act and so asks only when the script changed. The decision is recorded like any approval: the first answer wins, from any window, your phone or a chat app, and a no from a phone or chat app means Don't run and stop. Approval is for the script's exact text, not for the folders it runs in.
  • Where it runs. In the primary folder's worktree (or the folder itself when it has none), with a 10-minute limit that stops the script and everything it started.
  • What it can see. The shell's basic variables (paths, temp folders, build-tool locations) and BODEGA_PORT_BASE. None of your API keys or other environment variables.
  • What it cannot do. The same commands the agent's shell refuses are refused here, and with air-gap on (or when any folder of the environment is vaulted) a script containing a command Bodega recognises as reaching the network, such as npm install, npx, pip install or git clone, does not run at all. That check is best-effort: it reads the script's text, so a download hidden in a variable or inside a program the script runs is not caught. Read the script; it runs exactly as written. Output is checked for keys and passwords before it is saved or shown.

If a script fails, times out or is refused, the session shows in Runs under Needs you as Setup failed until you start a turn. After a restart an unanswered card is gone; start the environment again to be asked again.

In the CLI

bodega skills trust lists a repo's .bodega/skills/ and their approval state; skills approve <name> approves one against its current content hash (the same content-hash-keyed approval as the app, editing the file invalidates it); skills revoke <name> withdraws approval. bodega plugin install <path> installs a plugin bundle and prints its contents first, with --dry-run to preview and --approve-grants <skill>:<grant>,... for non-interactive elevated-permission approval.

This page mirrors the in-app docs hub for app version 1.0.0-beta.54.1. Found something unclear or out of date? Tell us on Discord. New here? Download the free beta and follow along.