Sandbox Agent File Writes Behind a Path Allowlist
Agent tools that can write anywhere turn a helpful edit into a secrets leak. Sandboxing agent file writes behind a path allowlist keeps changes inside a known tree. You still automate. You just stop hoping the model respects unspoken boundaries.
Pair this with token hygiene from rotate agent tool tokens on a weekly calendar hold.
List Paths the Agent May Touch
Start with repo-relative folders: src, docs, tests. Deny .env, keys, and home directories by default. Put the allowlist in config next to the agent definition so reviewers see it in the same PR as prompt changes.
Treat allowlist edits like dependency bumps. Diff them the way you diff prompt changes in PR review like code diffs.
Fail Closed on Unknown Paths
If a tool requests a path outside the list, reject and log. Soft warnings teach agents to retry until something sticks. Hard fails teach cleaner plans.
Include symlink checks. A path that looks safe can resolve into a denied tree.
Separate Read Scopes From Write Scopes
Agents often need broad reads and narrow writes. Keep two lists. Quarantine new MCP servers behind read-only profiles first: quarantine new MCP servers behind read-only profiles.
Promote write rights only after a dry run log shows stable targets.
Log Every Denied Write
Store path, tool name, and agent run id. Overnight fixtures from failed runs help: record failed agent runs as overnight fixtures. Patterns show which prompts push outside the fence.
Review denied writes in the same weekly token rotation hold so security and agent ops share one calendar slot.
Test Allowlists in CI
Add a unit that attempts writes to .env and tmp outside the tree. Expect rejection. Pin model versions so a silent alias bump does not change tool behavior: pin model versions in agent config like dep locks.
Document how humans override for emergencies. Overrides need a ticket id and an expiry.
Keep the Allowlist Short
Long lists become silent policy. Prefer a few roots with explicit denials for hot files. When latency budgets matter, log tool-call times so security checks stay cheap: log tool-call latency budgets for each agent step.
Revisit after each new tool lands. New tools inherit deny-by-default until listed.
Publish the allowlist in the agent README so new contributors do not invent home-directory shortcuts. Policy that lives only in chat will drift.
On incident week, freeze allowlist expansions. Add paths only after the write path is understood, not during the firefight.
Map allowlisted paths to CODEOWNERS so security reviews route correctly. A write into docs might be fine for content agents and wrong for payment agents. Scope by agent role, not one global list forever.
Red-team once a quarter with prompts that ask the agent to write into ssh folders. Expect denial and a clean log. Missing denials are release blockers.
FAQ
Can the agent create new folders?
Only under allowlisted parents. Creating siblings outside the tree should fail.
What about absolute paths?
Normalize then match. Reject absolute paths that escape the workspace root.
Do reads need the same list?
Use a wider read list. Keep write narrower.
How do we handle temp files?
Give a dedicated temp root inside the sandbox and wipe it after the run.
Is OS sandboxing enough alone?
Use both. Path allowlists are policy you can review in git.
What if a vendor tool ignores the list?
Wrap the tool or disable write until the wrapper exists.