Extra folders

By default an agent works in the directory you start the run from. To let it work on other local folders in the same run, for example a CLI change plus the matching backend change, list them under [workspace] extra_paths:

[workspace]
extra_paths = ["../backend", { path = "../docs", read_only = true }]

Paths are relative to the directory you start the run from. ~/ and absolute paths work too. Entries are read-write unless marked read_only, and your [filesystem] restrictions apply inside them as well.

Use one profile across several repos

An entry that is the working directory, or inside it, is skipped, since the agent already has it. A global profile can therefore list every repo in a set and be used from any of them:

[workspace]
extra_paths = ["~/Projects/cli", "~/Projects/backend"]

Global profiles must use ~/ or absolute paths. A read_only entry inside the working directory is refused instead of skipped; use [filesystem] deny_write for that.

How each backend handles them

• Docker sandbox: each folder is mounted at the same path as on your machine. Git works inside them, but the agent can't change .git/config, .git/hooks/ or anything else your own git would later run. If an extra folder is a git worktree, its repository's .git directory is mounted too.
• Native backend: the agent can already reach these folders. A read_only entry is added to the run's deny_write.

With --worktree, only the current repo gets a worktree. Extra folders are used as they are, so the agent's edits land directly in those checkouts.

Refused paths

Stashbase refuses /, your home directory or a parent of it, credential and app-data directories such as ~/.ssh, ~/.aws or ~/Library, a parent of the working directory, folders that overlap each other, and paths that don't exist. This is a safety net against obvious mistakes, not a complete boundary.

Stashbase also refuses to start any agent from /, your home directory (or a parent of it) or a credential directory, because the agent would get everything there. Start from a project directory and list other folders under extra_paths.

Run stashbase agent validate to see refused and skipped entries:

stashbase agent validate --profile coding

Docker limits

• Docker Desktop can only mount folders it shares with its VM. On macOS that is /Users, /Volumes, /private, /tmp and /var/folders by default. For a folder elsewhere, add it under Docker Desktop → Settings → Resources → File sharing.
• Paths containing : are refused, so extra folders don't work with the Docker backend on Windows yet.