Skip to main content

Setup Scripts

Each repository can have an optional setup script that runs automatically whenever a new worktree is created for a session. Useful for installing dependencies, copying configuration files, or any other per-worktree initialization.

Configuring​

Set a setup script when adding a repo, or update it later:

boss repo update my-repo --setup-script "npm install"

Clear it with an empty string:

boss repo update my-repo --setup-script ""

Environment variables​

The following environment variables are available to the setup script:

VariableDescription
REPO_DIRPath to the main git repository (the original clone).
WORKTREE_DIRPath to the worktree being set up.

These let you reference files in the main repo without hardcoding paths. For example, to copy an .env file into each new worktree:

boss repo update my-repo \
--setup-script 'cp "$REPO_DIR/.env" "$WORKTREE_DIR/.env" && npm install'
Copy only what agents need

Every key in the worktree .env reaches every agent session in that worktree. Rather than copying your whole .env, write only the keys agents need into the worktree (for example, filter it with grep -E '^(export )?(LINEAR_API_KEY|SENTRY_ORG)=' "$REPO_DIR/.env" > "$WORKTREE_DIR/.env") and leave other secrets in the main checkout.

Automatic .env loading​

Once a worktree contains a .env file, Bossanova loads it into the environment of every agent session it starts in that worktree; you do not need to source it or run direnv yourself. This is why the setup script above copies .env into the worktree: the copy makes the file present, and Bossanova picks it up automatically from there.

The daemon (bossd) runs under your OS service manager with no interactive shell, so a normal shell's direnv/.env machinery never runs for these sessions. To make repo-local variables available anyway, Bossanova reads <worktree>/.env and overlays it beneath the session's managed environment when it launches the agent. This applies to interactive chats, resumed/woken chats, scheduled (cron) sessions, headless runs, and automated repair runs alike.

A common use is resolving ${VAR} placeholders in a project's .mcp.json. For example, an MCP server configured with an Authorization: Bearer ${LINEAR_API_KEY} header only authenticates if LINEAR_API_KEY is present in the session environment; putting it in the worktree .env is enough. See the MCP guide.

Precedence and format​

  • Managed values win. The overlay is lowest-precedence: Bossanova's own BOSS_* variables and internal session values are never overridden by a repo .env, even if it defines the same key.
  • CLI-redirecting keys are ignored. BOSS_SETTINGS_PATH, BOSS_KEYRING_BACKEND, BOSS_WEB_PORT, BOSS_CLOUD_URL and BOSSD_ORCHESTRATOR_URL in a worktree .env are never passed to a session, so a development daemon's settings in your .env cannot point agents at a different Bossanova instance. Values Bossanova sets itself are unaffected.
  • Missing is fine. A worktree with no .env (or an empty/unreadable one) is a no-op: nothing is loaded and the session starts normally.
  • The parser is intentionally minimal. Blank lines and # comment lines are ignored; an optional leading export is stripped; one pair of surrounding quotes is removed from a value. There is no variable interpolation, no multiline values, and no inline-comment stripping (a value may legitimately contain #). Keep .env files to simple KEY=value lines.

Values loaded from .env are treated as secrets and are never logged.