Permissions

Control filesystem access with declarative permission rules for Deep Agents

Control which files and directories an agent can read or write to using declarative permission rules. Pass a list of rules to permissions= and the agent’s built-in filesystem tools respect them.

Permissions require deepagents>=1.9.1.

Permissions only apply to the built-in filesystem tools (ls, read_file, glob, grep, write_file, edit_file). Custom tools and MCP tools that access the filesystem are not covered. Permissions also do not apply to sandbox backends, which support arbitrary command execution via the execute tool.

Use permissions when you need path-based allow/deny rules on the built-in filesystem tools. Use backend policy hooks when you need custom validation logic (rate limiting, audit logging, content inspection) or need to control custom tools.

Basic usage

Pass a list of FilesystemPermission rules to createDeepAgent. Rules are evaluated in declaration order. The first matching rule wins. If no rule matches, the operation is allowed.

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("basic: agent not created");

Rule structure

Each FilesystemPermission has three fields:

Field	Type	Description
operations	("read" | "write")[]	Operations this rule applies to. "read" covers ls, read_file, glob, grep. "write" covers write_file, edit_file.
paths	string[]	Glob patterns for matching file paths (e.g., ["/workspace/**"]). Supports ** for recursive matching and {a,b} for alternation.
mode	"allow" | "deny"	Whether to allow or deny matching operations. Defaults to "allow".

Rules use first-match-wins evaluation: the first rule whose operations and paths match the current call determines the outcome. If no rule matches, the call is allowed (permissive default).

Paths must be absolute (start with /) and cannot contain .. or ~. Invalid paths throw at agent construction time.

Examples

Isolate to a workspace directory

Allow reads and writes only under /workspace/ and deny everything else:

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("isolate-workspace: agent not created");

Protect specific files

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/.env", "/workspace/examples/**"],
      mode: "deny",
    },
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("protect-files: agent not created");

Read-only memory

Allow the agent to read memory files but prevent it from modifying them. This is useful for organization-wide policies or shared knowledge bases that should only be updated by application code. See read-only vs writable memory for more context.

const store = new InMemoryStore();
const agent = createDeepAgent({
  model,
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: (rt) => [rt.serverInfo.user.identity],
    }),
    "/policies/": new StoreBackend({
      namespace: (rt) => [rt.context.orgId],
    }),
  }),
  permissions: [
    {
      operations: ["write"],
      paths: ["/memories/**", "/policies/**"],
      mode: "deny",
    },
  ],
  store,
});
if (!agent) throw new Error("read-only-memory: agent not created");

Deny all access

Block all reads and writes. This is a restrictive baseline you can layer more specific allow rules on top of:

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("deny-all: agent not created");

Rule ordering

Because of first-match-wins, rule order matters. Place more specific rules before broader ones:

const correctPermissions: FilesystemPermission[] = [
  { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

const incorrectPermissions: FilesystemPermission[] = [
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  {
    operations: ["read", "write"],
    paths: ["/workspace/.env"],
    mode: "deny",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

Subagent permissions

Subagents inherit the parent agent’s permissions by default. To give a subagent different permissions, set the permissions field in its spec. This replaces the parent’s rules entirely.

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
  subagents: [
    {
      name: "auditor",
      description: "Read-only code reviewer",
      systemPrompt: "Review the code for issues.",
      permissions: [
        { operations: ["write"], paths: ["/**"], mode: "deny" },
        { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
        { operations: ["read"], paths: ["/**"], mode: "deny" },
      ],
    },
  ],
});
if (!agent) throw new Error("subagent: agent not created");

To explicitly grant a subagent unrestricted access, set permissions: []. An empty array overrides the parent rules with no restrictions. Omitting permissions inherits from the parent.

Composite backends

When using a CompositeBackend with a sandbox default, every permission path must be scoped under a known route prefix. Sandboxes support arbitrary command execution, so path-based restrictions alone cannot prevent filesystem access through shell commands. Scoping permissions to route-specific backends avoids this conflict.

const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});
const agent = createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/memories/**"], mode: "deny" },
  ],
});
if (!agent) throw new Error("composite-backend: agent not created");

Permissions that include paths outside any route throw at construction time:

const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/workspace/**"], mode: "deny" },
  ],
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [{ operations: ["read"], paths: ["/**"], mode: "deny" }],
});

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.