Filesystem Tools
Use sandboxed file tools for safe agent read/write operations (no path traversal), with an explicit root directory you control.
This page covers:
- The sandbox model (what paths are allowed)
- Registering filesystem tools
- Executing read/write/append/replace safely
File I/O should be explicit and sandboxed.
A filesystem tool without a sandbox is a security boundary violation. Predicate filesystem tools are restricted to a root directory you choose.
Table of Contents
Sandbox model
Filesystem tools operate under a configured base directory (sandbox root). Requests like:
../secrets.txt/etc/passwd
should be rejected or normalized to stay within the sandbox.
Recommended layout:
- store agent file outputs under something like
./.sentience/files/
Register filesystem tools
from predicate.tools import ToolRegistry, FileSandbox, ToolContext, register_filesystem_tools
registry = ToolRegistry()
sandbox = FileSandbox("./.sentience/files")
register_filesystem_tools(registry, sandbox)
ctx = ToolContext(runtimeExamples
Write then read a file
await registry.execute("write_file", {"path": "notes.txt", "content": "hello"}, ctx=ctx)
result = await registry.execute("read_file",Related topics
- Tool Registry — typed tool execution + tool-call trace events