Settings file reference

Overview

Use settings.yaml to configure how Poolside behaves in Poolside Assistant and the pool CLI. This page is a reference for the top-level settings you can define in Poolside settings files. For task-based guidance, see Tool permissions, MCP servers, and Secrets.

File locations and precedence

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

Top-level settings

The following top-level keys are supported in Poolside settings files.

Key	Purpose	See also
`pool`	Configure Poolside API connection settings	pool settings
`tools`	Configure tool rules and approval behavior	Tools
`paths`	Configure file access rules for explicit file tools	Paths
`secrets`	Configure secret approvals, fallback default redaction patterns, and user redaction patterns	Secrets
`mcp_servers`	Configure personal MCP servers	MCP servers
`sandbox`	Configure local sandbox behavior	Sandbox

`pool` settings

Use pool to configure settings for the Poolside Agent CLI.

Key	Type	Description
`pool.api_url`	string	Set the Poolside API URL.

Poolside still accepts a top-level api_url key for compatibility, but use pool.api_url in new settings files.

Tools

Use tools to turn tools off or configure approval rules. Each tool key can include:

Key	Type	Description
`allow`	list	Auto-approve patterns for that tool
`deny`	list	Deny patterns for that tool
`disabled`	boolean	Turn the tool off when set to `true`

Tools example for .poolside/settings.yaml

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

Tool rule syntax

Tool rules support * 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.

For more information, see Tool rules.

Paths

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

Key	Type	Description
`allow`	list	Paths the agent can read, with optional `write: true` access
`deny`	list	Paths the agent cannot access

Each path entry supports:

Key	Type	Description
`path`	string	File or directory pattern
`write`	boolean	Allow edits when set to `true`

Paths example for .poolside/settings.yaml

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

Path rule behavior

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.

Secrets

Use secrets to configure secret approvals, fallback default redaction patterns, and user redaction patterns. Administrators manage organization redaction patterns in the Poolside Console.

Key	Type	Description
`allow`	list	Secret names that Poolside can use without prompting again
`fallback_redaction_patterns`	boolean	Use fallback default redaction patterns when an agent run, such as standalone mode, cannot load organization patterns from the API. Defaults to `true`.
`redact_patterns`	list	User redaction patterns for sensitive values

Each redact_patterns entry supports:

Key	Type	Description
`name`	string	Name of the pattern
`pattern`	string	RE2 regular expression used for redaction

Secrets example

secrets:
  allow:
    - GITHUB_TOKEN
  fallback_redaction_patterns: true
  redact_patterns:
    - name: internal-api-key
      pattern: sk_internal_[A-Za-z0-9]+

For more information, see Secrets and Redaction patterns.

MCP servers

Use mcp_servers to configure personal MCP servers in your settings file. Shared MCP servers configured in Poolside Console are not defined here. Each server entry can include:

Key	Type	Description
`command`	string	Executable to run for a `stdio` server
`args`	list	Arguments passed to the command
`cwd`	string	Working directory for the server process
`transport`	object	Remote connection details
`env`	map	Environment variables for the server
`enabled_tools`	list	Tool names to enable
`allow`	list	Tool approval patterns to allow
`deny`	list	Tool approval patterns to deny
`disabled`	boolean	Turn the server off when set to `true`

transport supports:

Key	Type	Description
`type`	string	Connection type. Supported values are `http` and `sse`.
`url`	string	MCP server URL
`headers`	list	HTTP headers to send with requests

MCP servers example for .poolside/settings.yaml

mcp_servers:
  filesystem:
    command: node
    args:
      - /path/to/filesystem-server.js
    env:
      NODE_ENV: production
  notion:
    transport:
      type: http
      url: https://mcp.notion.com/mcp
      headers:
        - "Authorization: Bearer <api-token>"

For more information, see MCP servers.

Sandbox

Use sandbox to configure local sandbox behavior for user-managed runs. Sandbox settings include:

Key	Type	Description
`image`	string	Container image to use
`env_vars`	map	Environment variables to set in the sandbox
`secrets`	list	Secret names the sandbox can request
`filesystem`	object	Workspace access configuration
`filesystem.mounts`	list	Extra host paths to mount into the sandbox
`network`	object	Network policy and allowed destinations

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

sandbox:
  image: poolsideengineering/ubuntu-with-tools
  env_vars:
    NODE_ENV: development
  secrets:
    - GITHUB_TOKEN
  filesystem:
    workspaces:
      access: read-only
    mounts:
      - host: <absolute-host-path>
        sandbox: <absolute-sandbox-path>
        access: read-only
  network:
    policy: allow-list
    egress:
      allowed_domains:
        - poolside.ai
      allowed_cidrs:
        - 10.0.0.0/8

Supported values:

Key	Supported values
`filesystem.workspaces.access`	`read-only`, `read-write`
`filesystem.mounts[].access`	`read-only`, `read-write`
`network.policy`	`off`, `allow-list`, `unsafe-allow-all`

Use allowed_domains, allowed_cidrs, or both under network.egress. Use env_vars to pass string environment variables into the sandbox container. Use secrets to list the names of secrets that the sandbox can request. For more information, see Secrets. For filesystem.mounts:

host must be an absolute path on the host
sandbox must be an absolute path inside the container
Mount targets must be unique
Host mount paths cannot overlap with workspace directories already mounted by Poolside

For more information, see Local sandbox and Sandboxes.

Example settings files

Personal defaults (all projects):

Personal defaults example ~/.config/poolside/settings.yaml

tools:
  shell:
    allow:
      - "git log *"
paths:
  deny:
    - path: ~/.ssh/**
mcp_servers:
  filesystem:
    command: node
    args:
      - /path/to/filesystem-server.js

Personal, project-specific:

Personal project-specific example .poolside/settings.local.yaml

tools:
  shell:
    allow:
      - "npm run *"
      - "go test *"
    deny:
      - "git push *"
paths:
  allow:
    - path: ~/workspace/<project-name>/notes/**
      write: true
  deny:
    - path: ~/workspace/<project-name>/.env
mcp_servers:
  local-dev:
    command: node
    args:
      - ~/scripts/dev-tools.js

Shared, project-specific:

Shared project-specific example .poolside/settings.yaml

tools:
  shell:
    allow:
      - "npm run lint"
      - "npm run test *"
    deny:
      - "rm -rf *"
      - "git push --force *"
paths:
  allow:
    - path: src/**
      write: true
    - path: docs/**
      write: true
  deny:
    - path: .env
    - path: secrets/**

Get started

Use Poolside

Work with agents

Customize agents

Connect agents

Control agents

Administration

Settings file reference

Overview

File locations and precedence

Top-level settings

`pool` settings

Tools

Tool rule syntax

Paths

Path rule behavior

Secrets

MCP servers

Sandbox

Example settings files

Get started

Use Poolside

Work with agents

Customize agents

Connect agents

Control agents

Administration

Documentation Index

​Overview

​File locations and precedence

​Top-level settings

​pool settings

​Tools

​Tool rule syntax

​Paths

​Path rule behavior

​Secrets

​MCP servers

​Sandbox

​Example settings files

​Related resources

Overview

File locations and precedence

Top-level settings

`pool` settings

Tools

Tool rule syntax

Paths

Path rule behavior

Secrets

MCP servers

Sandbox

Example settings files

Related resources