Chapter 03 · Filesystem permissions and path boundaries

Demonstrate how to keep the agent's file operations inside /workspace/ and protect /.env from modification.

Mechanics and design choices

Permissions are declarative rules evaluated first-match-wins in declared order; unmatched operations are allowed by default. Rules apply to built-in file tools, while FilesystemBackend(virtual_mode=True) normalizes paths under root_dir and blocks .., ~, and absolute paths outside the root. Treat them as two layers: permissions gate tool calls; the virtual filesystem resolves paths.

Example

import os
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model=os.environ["MODEL_ID"],
    api_key=os.environ["DEEPAGENT_API_KEY"],
    base_url=os.environ.get("DEEPAGENT_BASE_URL", "https://api.openai.com/v1"),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from deepagents.middleware.filesystem import FilesystemPermission

agent = create_deep_agent(
    model=model,
    backend=FilesystemBackend(root_dir="/tmp/deepagents-sandbox", virtual_mode=True),
    permissions=[
        FilesystemPermission(operations=["write"], paths=["/.env"], mode="deny"),
        FilesystemPermission(operations=["read", "write"], paths=["/workspace/**"], mode="allow"),
    ],
    system_prompt="You work inside /workspace. Never touch /.env.",
)
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Write a note to /workspace/notes.txt, then try to modify /.env."}]},
    {"configurable": {"thread_id": "ch03"}},
)
print(result["messages"][-1].content)

Run and verify

API key required. Two checks: /workspace/notes.txt is written, and the /.env write is denied by the permission layer, with the model receiving deny semantics.

Pitfalls

permissions gate built-in file tools only; they do not constrain other custom tools or execute on sandbox backends. Sandboxes rely on isolation and network policy instead. permissions= takes FilesystemPermission objects (verified on 0.7.15: dict literals are not auto-converted and raise AttributeError: 'dict' object has no attribute 'mode').

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is permission matching?

2. What is the default when nothing matches?

3. What does virtual_mode control?

4. Is execute gated by permissions?

Hands-on exercises

1. Ask it to write /outside.txt and observe the virtual-mode rejection.
2. Reorder rules and observe first-match-wins behavior.
3. Give a subagent narrower permissions than the parent.

Official references

• permissions
• backends

Verified on 2026-09-17 with Deep Agents 0.7.15.