Permissions - Poolside

Use settings.yaml to control what Poolside agents can do when you run pool or pool exec. For a complete reference of supported settings keys, see Settings file reference. You can use settings.yaml to:

Turn off specific tools
Automatically approve or deny certain tool calls
Limit which files agents can read or modify through explicit file tools
Run agents inside a local sandbox with stronger runtime boundaries

These controls help you balance productivity with safety when running agents in your development environment.

Main controls in settings.yaml

Most users interact with three configuration areas. Other supported settings include hooks, personal MCP server configuration, secret rules, prompt defaults, and API connection settings. For the full schema, see Settings file reference.

Setting	Purpose
`tools`	Turn tools off or define auto-approval rules
`paths`	Restrict file access through explicit file tools
`sandbox`	Run agents inside an isolated runtime environment

These settings serve different purposes:

Tools decide what actions the agent can attempt.
Paths decide which files the agent can access through file tools.
Sandbox defines where the agent runs.

tools controls tool availability and approvals. paths controls access through explicit file tools. Neither setting fully sandboxes the agent. If you need an enforced runtime boundary, use a sandbox.

The shell tool

Treat the shell tool as high risk. Shell commands can:

Install software
Modify files
Run scripts

Programs started through shell may read or modify files outside the restrictions defined in paths. If you need strict file access controls, turn off shell or run agents inside a sandbox.

File locations

Poolside reads settings.yaml from three locations.

File location	Use this for
`.poolside/settings.local.yaml`	Personal, project-specific. Do not commit. Takes precedence over all other files.
`.poolside/settings.yaml`	Shared, project-specific. Commit and share with your team.
`~/.config/poolside/settings.yaml`	Personal defaults (all projects). Applies when no project-level settings override it.

Poolside evaluates available files in this priority order:

.poolside/settings.local.yaml
.poolside/settings.yaml
~/.config/poolside/settings.yaml

For allow and deny rules under tools and paths, priority does not cause the rules in one file to replace the rules in another. Poolside combines these rules across all files. A matching deny always overrides allow. Other settings use setting-specific merge behavior. Use ~/.config/poolside/settings.yaml for personal defaults across all projects. Use .poolside/settings.local.yaml for personal, project-specific restrictions. Use .poolside/settings.yaml for shared project defaults. For example settings files for each location, see Settings file reference.

Approvals

Approvals let you automatically allow or deny specific tool calls, which reduces repeated confirmation prompts when you trust certain operations. Rules:

If a tool call does not match an allow rule, Poolside asks for approval.
deny rules always override allow.

Approvals are a convenience feature, not a security boundary. Use a sandbox for stronger isolation. In an interactive pool session, approval modes give you a quick way to adjust approval behavior without editing settings.yaml:

Approval mode	ID	What it does
Always ask	`default`	Prompts for tool actions that are not already allowed
Accept edits	`accept-edits`	Auto-approves workspace file reads and writes, then prompts for everything else
Auto	`auto`	Uses Accept edits as a baseline, then classifies remaining permission requests by risk. See Auto mode.
Allow all	`always-allow`	Approves tool actions automatically

Press Shift+Tab to cycle through approval modes, or use /mode to open the approval mode selector. Changing the approval mode does not change rule precedence. A matching deny overrides a matching allow. Build and Plan are separate agent modes. Changing the agent mode does not change approval behavior. Switching from Plan to Build always requires your review, including when the approval mode is Allow all.

Auto mode

Auto mode is opt-in. To configure it:

Choose a classifier model that is available through the API connection for your session.
Add its model ID to your personal settings file:
Auto mode example for ~/.config/poolside/settings.yaml
pool: auto_mode_classifier: <model-id>
Restart pool so it loads the classifier setting.
Run /mode and select Auto.

Auto appears only when the classifier and API connection are configured. To set or override the classifier for one invocation, set POOL_AUTO_MODE_CLASSIFIER_MODEL when you start pool:

POOL_AUTO_MODE_CLASSIFIER_MODEL=<model-id> pool

The environment variable takes precedence over pool.auto_mode_classifier, and it enables Auto mode even when no settings entry exists. Setting it to an empty value disables Auto mode for that invocation. How Auto mode works Auto mode applies Accept edits first. For each action that would otherwise require approval, pool sends the classifier your current and earlier prompts, working directory, and the pending action with its arguments. The request uses your session’s API connection and credentials. If you connect through a third-party provider such as OpenRouter, that provider receives the classifier request. The classifier returns one of these results:

Classification	Result
Low risk	Run immediately
Medium risk	Run and add a notice to the transcript
High risk	Open the normal approval dialog

An explicitly requested push or pull request can be classified as medium risk when the action stays within the repository and is recoverable. Destructive, unclear, authentication, and secret-handling actions remain high risk. These are classifier guidelines, not fixed rules for every action. If the model ID is unavailable, the classifier times out, the provider returns an invalid result, or the action cannot be classified, Poolside opens the normal approval dialog. Auto mode stays selected. If every action prompts for approval, verify the classifier model ID and API connection. Auto mode never turns a matching deny into an approval. Subagents use Accept edits when the parent session uses Auto. Their permission requests are not sent to the classifier. For other constraints, see Subagents.

Command-line approvals

In pool, tool calls require approval unless a matching allow rule exists in settings.yaml. To run pool exec without approval prompts, use --unsafe-auto-allow:

pool exec -p "Review this repository" --unsafe-auto-allow

When --unsafe-auto-allow is set:

Tool calls run without prompts.
Deny rules still apply.

Use --unsafe-auto-allow only in trusted sandboxed environments.

Tool rules

Use tools to turn off a tool or configure its approval rules. Configure file access tools such as read and edit with paths. Poolside enables tools by default. If any settings file sets disabled: true for a tool, Poolside disables that tool. Another settings file cannot enable it with disabled: false.

Add tool rules to .poolside/settings.local.yaml for personal, project-specific settings, to .poolside/settings.yaml for shared, project-specific settings, or to ~/.config/poolside/settings.yaml for personal defaults across projects.

Tools example

tools:
  shell:
    allow:
      - "git log *"
      - "rg *"
    deny:
      - "rm *"
      - "git push *"

How approval rules work:

Tool rules support only * wildcards. ** is not supported.
The rule string must match the tool call shown in the approval prompt.
For pipelines, subshells, and other composite commands, Poolside checks each command separately against your rules.
Poolside can auto-approve the complete tool call through an allow rule only when every command matches allow and no command matches deny.
If the rules do not determine the result, the active approval mode determines whether Poolside prompts you or runs the call automatically.

Path rules

Use paths to control which files agents can access through explicit file tools.

Add path rules to .poolside/settings.local.yaml for personal, project-specific settings, to .poolside/settings.yaml for shared, project-specific settings, or to ~/.config/poolside/settings.yaml for personal defaults across projects.

Paths example for .poolside/settings.local.yaml or ~/.config/poolside/settings.yaml

paths:
  allow:
    - path: ~/Documents/**
    - path: ~/workspace/docs/**
      write: true
  deny:
    - path: ~/.ssh/**
    - path: ~/.env

How path rules work:

Poolside treats paths as read-only by default.
write: true allows edits, deletes, moves, and renames.
deny overrides allow.
Path patterns support * and **.
Use forward slashes for all paths, including Windows paths.
Windows-volume paths do not match on Linux, and Linux paths do not match on Windows.
*:/Program Files/** matches any Windows volume.
In .poolside/settings.local.yaml and ~/.config/poolside/settings.yaml, paths must be absolute or start with ~.
In .poolside/settings.yaml, paths must be relative to the project.

Read-only configuration

Read-only paths example for .poolside/settings.yaml

tools:
  shell:
    disabled: true

paths:
  allow:
    - path: src/**
    - path: docs/**
  deny:
    - path: .env
    - path: secrets/**

Read-write configuration

Read-write paths example for .poolside/settings.yaml

tools:
  shell:
    disabled: true

paths:
  allow:
    - path: src/**
      write: true
    - path: docs/**
      write: true
  deny:
    - path: .env
    - path: secrets/**

paths rules apply only to explicit file tools. Programs started through shell may still read or modify files outside these rules.

Protect sensitive files across projects

To block access to sensitive files in every project, add deny rules to your personal defaults file, ~/.config/poolside/settings.yaml:

Protect sensitive files example for ~/.config/poolside/settings.yaml

paths:
  deny:
    - path: ~/.ssh/**
    - path: ~/.aws/**
    - path: /**/.env

deny rules always override allow.

Local sandbox

A sandbox creates a stronger runtime boundary. Sandbox workspace access supports two modes:

read-only: The agent stages workspace changes inside the sandbox. Between turns, Poolside prompts you to apply or discard those changes in your host workspace.
read-write: The agent writes workspace changes directly to your host workspace.

For user-managed local runs, define sandbox settings in your personal default ~/.config/poolside/settings.yaml file.

Sandbox example for ~/.config/poolside/settings.yaml

sandbox:
  image: poolsideengineering/ubuntu-with-tools
  filesystem:
    workspaces:
      access: read-only
  network:
    policy: allow-list
    egress:
      allowed_domains:
        - poolside.ai

Sandbox configuration controls:

Container runtime image
Workspace file access
Extra host mounts
Network destinations

Use volume mounts in local sandboxes

Use volume mounts to mount extra host paths into the sandbox. If your development workflow depends on host resources outside the workspace, add extra mounts under sandbox.filesystem.mounts. For example, you can mount a persistent host cache directory, the local Docker socket, and a Docker config directory into the sandbox:

Volume mounts example for ~/.config/poolside/settings.yaml

sandbox:
  image: <image-with-docker-cli>
  filesystem:
    workspaces:
      access: read-write
    mounts:
      - host: <absolute-host-path-to-build-cache>
        sandbox: /cache
        access: read-write
      - host: /var/run/docker.sock
        sandbox: /var/run/docker.sock
        access: read-write
      - host: <absolute-host-path-to-docker-config-dir>
        sandbox: /docker-config
        access: read-only

Use this pattern when you want to reuse build artifacts and config files across sandbox recreation, talk to your local Docker daemon, or read registry credentials from a mounted config directory. Mounting /var/run/docker.sock gives processes inside the sandbox access to your host Docker daemon. Use that mount only when your workflow requires it. Poolside rejects an extra mount if its host path overlaps a workspace directory. This includes the workspace directory, its subdirectories, and its parent directories. Best practices:

Use absolute host paths.
Put reusable build caches outside the workspace, then mount them into the sandbox.
Mount config directories as read-only unless the tool must write to them.
Choose a container image that already includes the tools your workflow needs.

Use private or local images

For local sandboxes, Poolside uses your local Docker engine to resolve the sandbox image.

Private image example for ~/.config/poolside/settings.yaml

sandbox:
  image: ghcr.io/<org>/<image>:<tag>

Before you use a private image, authenticate Docker on your host for that registry. For example:

docker login ghcr.io

Use a private image only after Docker on your machine is already authenticated to that registry.
You can also use an image that you built or pulled locally.

Glob reference

Tool rule syntax

Pattern	Matches	Does not match
`go vet *`	`go vet`, `go vet -vettool shadow`	`go run`
`gh * list *`	`gh pr list`, `gh gist list`	`gh list`

Tool rule behavior:

In a tool rule, * matches zero or more characters, including /.
Tool rules do not support **.

Path rule syntax

Pattern	Matches	Does not match
`/src/*/.go`	`/src/main.go`, `/src/pkg/run.go`	`/other/src/main.go`
`C:/*/bin/`	`C:/Tools/bin/app.exe`	`D:/Tools/bin/app.exe`

Path rule behavior:

In a path rule, * matches characters except /.
In a path rule, ** matches across directories.
The path rule *:/Program Files/** matches any Windows volume.

​Main controls in settings.yaml

​The shell tool

​File locations

​Approvals

​Auto mode

​Command-line approvals

​Tool rules

​Path rules

​Read-only configuration

​Read-write configuration

​Protect sensitive files across projects

​Local sandbox

​Use volume mounts in local sandboxes

​Use private or local images

​Glob reference

​Tool rule syntax

​Path rule syntax

​Related resources

Main controls in settings.yaml

The shell tool

File locations

Approvals

Auto mode

Command-line approvals

Tool rules

Path rules

Read-only configuration

Read-write configuration

Protect sensitive files across projects

Local sandbox

Use volume mounts in local sandboxes

Use private or local images

Glob reference

Tool rule syntax

Path rule syntax

Related resources