Tool permissions

Overview

Use settings.yaml to control what Poolside agents can do in your IDE and in the pool CLI. For a complete reference of supported settings keys, see Settings file reference. You can use it to:

Allow or block specific tools
Automatically approve or deny certain tool calls
Limit which files agents can read or modify
Run agents inside a sandbox with stronger runtime boundaries

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

How permissions work

Poolside permissions involve several layers. Each layer can restrict what an agent is able to do.

Layer	Managed by	What it controls
Role-based permissions	Administrators	What users can do in the organization
Agent configuration	Administrators or users	Which tools, Model Context Protocol (MCP) servers, repositories, and sandboxes an agent can use
`settings.yaml`	Individual users or teams	Tool approvals, path rules, and local sandbox configuration
Sandbox	Administrators or users	Runtime file system and network boundaries

At runtime, Poolside enforces the intersection of these layers. A user cannot gain access through settings.yaml to anything their role or the agent configuration does not already allow.

Prompt injection is possible whenever an agent consumes external input, such as code from third-party packages or external documentation. Treat agent actions with the same caution you would apply to running code you do not trust.

Main controls in `settings.yaml`

Most users interact with three configuration areas. Other supported settings include 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 which files the agent can read or modify
`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 and paths mainly control approvals and explicit file operations. They do not fully sandbox 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.

When the same setting appears in multiple files, the most specific file takes precedence:

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

For most IDE users, .poolside/settings.local.yaml is the right place for personal, project-specific restrictions. Use ~/.config/poolside/settings.yaml for personal defaults across all projects. 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.

IDE approvals

In the IDE, you can:

Approve a tool call once
Always approve a matching tool call
Deny a tool call

When you choose Always approve, Poolside updates rules in your personal project-specific .poolside/settings.local.yaml file. To open the permissions settings file directly from the IDE, run /approvals in the chat panel or use the Poolside: Open Permissions Settings command.

Running commands without approval prompts

This setting bypasses approval prompts for most tool calls. Use it only if you fully trust the agent and understand the risks of unrestricted tool access.

If you have the Auto Approve Commands permission, you can enable Execute commands without asking in Poolside Assistant to run most tool calls automatically without prompting for approval. This includes shell commands, file operations, and MCP tool calls. The Auto Approve Commands permission applies to all agents in your organization and is off by default. When you enable Execute commands without asking:

Most tool calls run immediately without confirmation
Poolside ignores approval allow rules
Deny rules still apply
Secrets are not auto-approved unless already authorized in your settings or earlier in the conversation

To enable this setting in Poolside Assistant:

In the prompt input box, type / to open the Commands menu.
Under Settings, select Approvals, or type /approvals and press Enter.
Select the Execute commands without asking DANGEROUS checkbox.

A warning indicator appears in the prompt box while this mode is active. To turn it off, follow the same steps and clear the Execute commands without asking DANGEROUS checkbox. This capability also applies to the pool command-line tool (CLI). For more information, see Run in automated mode.

Command-line tool approvals

In the pool command-line tool, tool calls require approval unless a matching allow rule exists in settings.yaml, or you have the Auto Approve Commands permission and pool runs with --unsafe-auto-allow=true. When --unsafe-auto-allow=true 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 tools off or configure approval rules. File access tools such as read and edit are controlled by paths, not tools.

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:
    disabled: false
    allow:
      - "git log *"
      - "rg *"
    deny:
      - "rm *"
      - "git push *"

How tool rules work:

Tool rules support only * wildcards. ** is not supported.
The rule string must match the tool call shown in the approval prompt.
Subshells and composite shell commands always require manual approval.
Shell commands that use control operators such as | are not supported by auto-approval.

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 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: tools can read files, and you review changes before Poolside applies them
read-write: tools can modify workspace files directly

For user-managed local runs, define sandbox settings in your personal default ~/.config/poolside/settings.yaml file. For managed local sandboxes, your sandbox can use any image your local Docker engine can pull or already has locally, including private images from registries Docker is already authenticated to. Poolside does not ask for registry credentials.

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

Sandbox availability depends on your agent configuration and your organization’s permissions. You can manage sandbox settings in the IDE using /sandbox.

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. 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
Do not mount a workspace directory again through mounts
Choose a container image that already includes the tools your workflow needs

Poolside already mounts workspace directories for the sandbox and rejects extra mounts that overlap with those workspace paths.

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
Poolside does not provide a sandbox UI field for registry credentials

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`

Rules:

* matches zero or more characters including /
** is not supported

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`

Rules:

* matches characters except /
** matches across directories
*:/Program Files/** matches any Windows volume

Get started

Use Poolside

Work with agents

Customize agents

Connect agents

Control agents

Administration

Overview

How permissions work

Main controls in `settings.yaml`

The `shell` tool

File locations

Approvals

IDE approvals

Running commands without approval prompts

Command-line tool 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

Get started

Use Poolside

Work with agents

Customize agents

Connect agents

Control agents

Administration

Documentation Index

​Overview

​How permissions work

​Main controls in settings.yaml

​The shell tool

​File locations

​Approvals

​IDE approvals

​Running commands without approval prompts

​Command-line tool 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

Overview

How permissions work

Main controls in `settings.yaml`

The `shell` tool

File locations

Approvals

IDE approvals

Running commands without approval prompts

Command-line tool 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