Settings file reference

Use settings.yaml to configure how Poolside behaves in 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 the related feature pages linked from each section.

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 usually takes precedence:

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

Some settings combine across files instead. The relevant sections below describe those exceptions and any file-location restrictions.

Top-level settings

Poolside settings files support the following top-level keys.

Key	Purpose	See also
`pool`	Configure the saved API connection and CLI launch 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
`web_search`	Configure a search provider for the `web_search` and `web_fetch` tools	Web search
`hooks`	Run commands at agent lifecycle events	Hooks
`subagents`	Configure agents that the main agent can delegate to	Subagents
`agent_servers`	Configure user-level ACP-compatible agent servers that `pool` can launch or connect to	Agent servers

`pool` settings

Use pool to configure the saved API connection and CLI launch settings. The CLI reads pool settings only from ~/.config/poolside/settings.yaml.

Key	Type	Description
`pool.api_url`	string	Set the saved API base URL.
`pool.auto_mode_classifier`	string	Model ID that enables the Auto approval mode.
`pool.default_agent_server`	string	Set the `agent_servers` entry to use when `--agent-server` is not provided.
`pool.worktree_prefix`	string	Prefix generated Git worktree names when you use `pool --worktree` without a branch name.

POOL_AUTO_MODE_CLASSIFIER_MODEL overrides pool.auto_mode_classifier for the current process. An explicitly empty value disables Auto mode even when the personal settings file configures a classifier.

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 off tools 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	Disable the tool when set to `true`

The allow and deny lists combine across all settings files. 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.

Tools example for .poolside/settings.yaml

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

Tool rule syntax

Tool rules support * wildcards. ** is not supported.
The rule string must match the tool call shown in the approval prompt.

For composite-command matching and approval behavior, 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`

The allow and deny lists combine across all settings files.

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.

Key	Type	Description
`allow`	list	Secret names that Poolside can use without prompting again
`fallback_redaction_patterns`	boolean	Use Poolside’s built-in default redaction patterns. Defaults to `true`.
`redact_patterns`	list	User redaction patterns for sensitive values

The allow and redact_patterns lists combine across all settings files. 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.

MCP servers

Use mcp_servers to configure personal MCP servers in your settings file. 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.

Web search

Use web_search to configure the search provider for web_search and enhanced web_fetch content extraction. The web_fetch tool works by default with no configuration. The web_search tool activates after you set a provider and an API key.

Key	Type	Description
`provider`	string	Search provider. Supported values are `parallel` and `exa`.
`api_key`	string	Provider API key. Without it, the `web_search` tool stays off.
`base_url`	string	Optional override for the provider API endpoint.
`summarize_results`	boolean	Summarize tool results with the session model. Defaults to `false`.

Web search example for ~/.config/poolside/settings.yaml

web_search:
  provider: parallel
  api_key: <api-key>
  summarize_results: true

Keep api_key in a personal settings file, not in shared project settings. For more information, see Web search and fetch.

Hooks

Use hooks to run commands at six agent lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, PreCompact, SessionStart, and Stop. The hooks section supports these keys:

Key	Type	Description
`<event-name>`	list	Hook entries for a supported event
`stop_hook_max_continuations`	integer	Maximum consecutive continuations requested by `Stop` hooks. Unset means unlimited; `0` refuses all continuations.

Each hook entry supports these keys:

Key	Type	Description
`name`	string	Optional stable name used in logs and when settings levels merge
`matcher`	string	Tool-name matcher for `PreToolUse` and `PostToolUse`. Required by the schema and ignored for other events.
`command`	string	Required shell command to run
`timeout`	integer	Timeout in seconds. Defaults to `60`.

Event lists combine across settings levels from least specific to most specific, which is also their run order. See hook configuration levels and merge order. A named hook declared again replaces the earlier definition in its original position. Unnamed hooks combine.

Hooks example for .poolside/settings.yaml

hooks:
  stop_hook_max_continuations: 1
  PreToolUse:
    - name: block-sudo
      matcher: shell
      command: <project-path>/.poolside/hooks/block-sudo.sh
      timeout: 10

For event payloads, decisions, matching, failures, limits, and security, see Hooks.

Subagents

Use subagents to configure agents that the main Poolside agent can delegate work to.

Key	Type	Description
`default`	string	Subagent to use when a delegation does not name one
`agents`	map	Named subagent definitions
`agents.<name>.type`	string	Launch type: `in_process`, `command`, or `agent_server`
`agents.<name>.description`	string	Description used when choosing a subagent. Required for enabled custom subagents.
`agents.<name>.instructions`	string	Instructions prepended to each delegated task
`agents.<name>.command`	string	ACP server executable for `type: command`
`agents.<name>.args`	list	Arguments passed to `command`
`agents.<name>.env`	map	Environment variables added to the command process
`agents.<name>.agent_server`	string	Command-based top-level `agent_servers` entry for `type: agent_server`
`agents.<name>.session_config_options`	map	ACP session configuration IDs and values. Supported IDs and values depend on the ACP server; unsupported IDs are ignored.
`agents.<name>.inherit_agent_config`	boolean	Send the main session’s model, agent configuration, MCP servers, and repository configuration when the ACP server supports Poolside session configuration metadata. Defaults to `true` for `general` and `false` otherwise.
`agents.<name>.disabled`	boolean	Remove the subagent from the available set when `true`

Subagent definitions merge across settings levels. More specific scalar values override earlier values, while env and session_config_options combine by key. Changing type clears launch fields from the previous type.

Subagents example for .poolside/settings.yaml

subagents:
  default: reviewer
  agents:
    reviewer:
      type: in_process
      description: Reviews completed changes.
      instructions: Report findings without editing files.

For defaults, validation, permissions, and usage accounting, see Subagents.

Agent servers

Use agent_servers in ~/.config/poolside/settings.yaml to configure ACP-compatible agent servers that pool can launch or connect to with --agent-server or -s. For these options, pool reads agent server configuration only from personal settings. Subagents are the exception. When a subagent uses type: agent_server, Poolside also reads agent_servers from project settings files to resolve the reference. When pool starts, it migrates legacy ~/.config/poolside/pool.json agent server configuration into settings.yaml and removes pool.json. Each agent_servers entry must set either command for a local stdio server or url for a remote network server. Do not set both. Use args and env with command; use headers with url.

Key	Type	Description
`type`	string	Agent server type. Defaults to `custom`. The `registry` and `remote` values are reserved for future use.
`command`	string	Executable to run for the agent server
`url`	string	Remote ACP server URL for the Streamable HTTP transport
`headers`	map	HTTP headers to send when connecting to `url`
`args`	list	Arguments passed to `command`
`env`	map	Environment variables for the `command` process
`default_config_options`	map	Saved ACP session configuration defaults for the server. Valid keys depend on the agent server’s ACP session config IDs.

Set pool.default_agent_server to the agent_servers key that pool should use when you do not pass --agent-server.

Agent server example for ~/.config/poolside/settings.yaml

pool:
  default_agent_server: claude
agent_servers:
  claude:
    command: claude-agent-acp
  gemini:
    command: gemini
    args:
      - --acp
  remote:
    url: http://localhost:3284/acp
    headers:
      Authorization: Bearer <token>

For more information, see Use other agent servers.

Example settings files

Personal defaults (all projects):

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

pool:
  worktree_prefix: feat-
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/**

​File locations and precedence

​Top-level settings

​pool settings

​Tools

​Tool rule syntax

​Paths

​Path rule behavior

​Secrets

​MCP servers

​Sandbox

​Web search

​Hooks

​Subagents

​Agent servers

​Example settings files

​Related resources

File locations and precedence

Top-level settings

`pool` settings

Tools

Tool rule syntax

Paths

Path rule behavior

Secrets

MCP servers

Sandbox

Web search

Hooks

Subagents

Agent servers

Example settings files

Related resources