Filesystem restrictions
Deny agent reads and writes to sensitive paths
Use [filesystem] to deny reads and writes to paths and patterns:
[filesystem]
deny_read = [".env", ".env.local", "~/.aws"]
deny_write = [".env", ".git", "~/.ssh"]Plain paths may be relative to the working directory, home-directory paths such as ~/.ssh, or absolute paths. A matching path also covers its directory descendants.
Patterns
deny_read and deny_write also accept globs and regular expressions:
[filesystem]
deny_read = [
"**/.env*", # glob: any .env file at any depth
"~/.config/*/token", # `*` and `?` stay within one path segment
"re:^~/.*\\.pem$", # regex over the absolute path
]A pattern that matches a directory covers everything under it. Prefix an entry with re: to treat it as a regular expression over the absolute path. Run stashbase agent explain to see how each pattern is matched, and stashbase agent validate to see warnings for backends that can only expand patterns at launch.
| Backend | How patterns are matched |
|---|---|
| macOS Seatbelt | Natively, so files created during the run are covered too. |
| systemd-run / bubblewrap | Expanded to concrete paths at launch, up to 200k entries per pattern. |
| Docker | Expanded at launch, inside the working directory only. |
| Windows | Rejected with an error. |
Because Linux and Docker expand patterns at launch, files created after the agent starts may not be covered there.
Platform enforcement
On macOS, filesystem restrictions use Seatbelt. On Linux, Stashbase prefers a systemd user session and can use bubblewrap as a fallback. If no supported enforcement backend is available, validation and launch fail closed rather than silently weakening the policy. Bubblewrap restrictions are inherited by descendants. Windows has no native backend; use the Docker sandbox, which also works on macOS and Linux and hides everything outside the working directory.
Existing file descriptors and data already loaded into process memory are outside filesystem restrictions. These controls are path restrictions, not general process-memory, administrator, or root isolation.
Validate and troubleshoot
Validate a profile before launching the agent:
stashbase agent validate --profile codingFilesystem denials observed directly by the proxy are recorded as filesystem_denied audit events with path and operation metadata. A nested tool may instead surface the native operating-system error it received.
See Run and secure agents for the broader security boundary.