Skip to main content

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.

​
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 locationUse this for
.poolside/settings.local.yamlPersonal, project-specific.
Do not commit. Takes precedence over all other files.
.poolside/settings.yamlShared, project-specific.
Commit and share with your team.
~/.config/poolside/settings.yamlPersonal 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:
  1. .poolside/settings.local.yaml
  2. .poolside/settings.yaml
  3. ~/.config/poolside/settings.yaml

​
Top-level settings

The following top-level keys are supported in Poolside settings files.
KeyPurposeSee also
poolConfigure Poolside API connection settingspool settings
toolsConfigure tool rules and approval behaviorTools
pathsConfigure file access rules for explicit file toolsPaths
secretsConfigure secret approvals and custom redaction patternsSecrets
mcp_serversConfigure personal MCP serversMCP servers
sandboxConfigure local sandbox behaviorSandbox

​
pool settings

Use pool to configure settings for the Poolside Agent CLI.
KeyTypeDescription
pool.api_urlstringSet 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:
KeyTypeDescription
allowlistAuto-approve patterns for that tool
denylistDeny patterns for that tool
disabledbooleanTurn the tool off when set to true
Example: 
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:
KeyTypeDescription
allowlistPaths the agent can read, with optional write: true access
denylistPaths the agent cannot access
Each path entry supports:
KeyTypeDescription
pathstringFile or directory pattern
writebooleanAllow edits when set to true
Example: 
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, paths must be relative to the project.
  • In ~/.config/poolside/settings.yaml, paths must be absolute or start with ~.
For more information, see Path rules.

​
Secrets

Use secrets to configure secret approvals and custom redaction patterns.
KeyTypeDescription
allowlistSecret names that Poolside can use without prompting again
redact_patternslistCustom redaction patterns for sensitive values
Each redact_patterns entry supports:
KeyTypeDescription
namestringName of the pattern
patternstringRE2 regular expression used for redaction
Example: 
secrets:
  allow:
    - GITHUB_TOKEN
  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:
KeyTypeDescription
commandstringExecutable to run for a stdio server
argslistArguments passed to the command
cwdstringWorking directory for the server process
transportobjectRemote connection details
envmapEnvironment variables for the server
enabled_toolslistTool names to enable
allowlistTool approval patterns to allow
denylistTool approval patterns to deny
disabledbooleanTurn the server off when set to true
transport supports:
KeyTypeDescription
typestringConnection type. Supported values are http and sse.
urlstringMCP server URL
headerslistHTTP headers to send with requests
Example: 
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:
KeyTypeDescription
imagestringContainer image to use
filesystemobjectWorkspace access configuration
networkobjectNetwork policy and allowed destinations
Example: 
sandbox:
  image: poolsideengineering/ubuntu-with-tools
  filesystem:
    workspaces:
      access: read-only
  network:
    policy: allow-list
    egress:
      allowed_domains:
        - poolside.ai
      allowed_cidrs:
        - 10.0.0.0/8
Supported values:
KeySupported values
filesystem.workspaces.accessread-only, read-write
network.policyoff, allow-list, unsafe-allow-all
Use allowed_domains, allowed_cidrs, or both under network.egress. For more information, see Local sandbox and Sandboxes.

​
Example settings files

Personal defaults (all projects):
~/.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:
.poolside/settings.local.yaml
tools:
  shell:
    allow:
      - "npm run *"
      - "go test *"
    deny:
      - "git push *"
paths:
  allow:
    - path: notes/**
      write: true
  deny:
    - path: .env
mcp_servers:
  local-dev:
    command: node
    args:
      - ~/scripts/dev-tools.js
Shared, project-specific:
.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/**