> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions

> Control what Poolside agents can read, write, and run by using settings.yaml.

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](https://docs.poolside.ai/settings-file-reference.md).

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](https://docs.poolside.ai/hooks.md), personal MCP server configuration, secret rules, prompt defaults, and API connection settings. For the full schema, see [Settings file reference](https://docs.poolside.ai/settings-file-reference.md).

| 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.

> [!NOTE]
>
> `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:

1. `.poolside/settings.local.yaml`
2. `.poolside/settings.yaml`
3. `~/.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](https://docs.poolside.ai/settings-file-reference.md#example-settings-files).

## 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](#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](https://docs.poolside.ai/cli/interactive-mode.md#use-plan-mode) 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:

1. Choose a classifier model that is available through the API connection for your session.

2. Add its model ID to your personal settings file:

   ```yaml title="Auto mode example for ~/.config/poolside/settings.yaml" theme={null}
   pool:
     auto_mode_classifier: <model-id>
   ```

3. Restart `pool` so it loads the classifier setting.

4. 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`:

```bash theme={null}
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](https://docs.poolside.ai/subagents.md#permissions-and-agent-mode).

### 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`:

```bash theme={null}
pool exec -p "Review this repository" --unsafe-auto-allow
```

When `--unsafe-auto-allow` is set:

* Tool calls run without prompts.
* Deny rules still apply.

> [!WARNING]
>
> 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`.

> [!TIP]
>
> 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.

```yaml title="Tools example" theme={null}
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.

> [!TIP]
>
> 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.

```yaml title="Paths example for .poolside/settings.local.yaml or ~/.config/poolside/settings.yaml" theme={null}
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

```yaml title="Read-only paths example for .poolside/settings.yaml" theme={null}
tools:
  shell:
    disabled: true

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

### Read-write configuration

```yaml title="Read-write paths example for .poolside/settings.yaml" theme={null}
tools:
  shell:
    disabled: true

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

> [!WARNING]
>
> `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`:

```yaml title="Protect sensitive files example for ~/.config/poolside/settings.yaml" theme={null}
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.

```yaml title="Sandbox example for ~/.config/poolside/settings.yaml" theme={null}
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:

```yaml title="Volume mounts example for ~/.config/poolside/settings.yaml" theme={null}
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.

```yaml title="Private image example for ~/.config/poolside/settings.yaml" theme={null}
sandbox:
  image: ghcr.io/<org>/<image>:<tag>
```

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

```bash theme={null}
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.

## Related resources

* [Poolside Agent CLI](https://docs.poolside.ai/cli/pool.md)
* [Settings file reference](https://docs.poolside.ai/settings-file-reference.md)
* [Sandboxes](https://docs.poolside.ai/sandboxes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.