Skip to main content

​
Overview

Use settings.yaml to control what Poolside agents can do in your IDE and in the pool CLI. 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.
LayerManaged byWhat it controls
Role-based permissionsAdministratorsWhat users can do in the organization
Agent configurationAdministrators or usersWhich tools, Model Context Protocol (MCP) servers, knowledge bases, and sandboxes an agent can use
settings.yamlIndividual users or teamsTool approvals, path rules, and local sandbox configuration
SandboxAdministrators or usersRuntime 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.
SettingPurpose
toolsTurn tools off or define auto-approval rules
pathsRestrict which files the agent can read or modify
sandboxRun 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.
ScopeFile locationNotes
Personal, project-specific.poolside/settings.local.yamlDo not commit. Takes precedence over all other files.
Shared, project-specific.poolside/settings.yamlCommit and share with your team.
Personal defaults, all projects~/.config/poolside/settings.yamlApplies 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
For most IDE users, .poolside/settings.local.yaml is the right place for personal restrictions. For command-line tool defaults across projects, use ~/.config/poolside/settings.yaml.

​
Project-local example

Use relative paths in .poolside/settings.local.yaml. 
tools:
  shell:
    allow:
      - "go vet *"
      - "npm *"
    deny:
      - "psql"

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

​
User-global example

Use absolute paths or ~ paths in ~/.config/poolside/settings.yaml. 
paths:
  allow:
    - path: ~/.bash_profile
    - path: ~/**/*.md
    - path: ~/agent-plans/*
      write: true
    - path: C:/Program Files/**
  deny:
    - path: /**/my-secret-file.yml
    - path: *:/my-secret-file.yml

​
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 all 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 tool calls automatically without prompting for approval. This includes all tool calls, such as 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:
  • Tool calls generated by the agent run immediately without confirmation
  • Poolside ignores approval allow rules
  • Deny rules still apply
To enable this setting in Poolside Assistant:
  1. In the prompt input box, type / to open the Commands menu.
  2. Under Settings, select Approvals, or type /approvals and press Enter.
  3. 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 Automation mode in the pool CLI.

​
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 project-specific settings, to .poolside/settings.yaml for shared project settings, or to ~/.config/poolside/settings.yaml for personal defaults across projects.
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 project-specific settings, to .poolside/settings.yaml for shared project settings, or to ~/.config/poolside/settings.yaml for personal defaults across projects.
Example: 
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.
  • Paths without write: true remain read-only.
  • 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.
  • In .poolside/settings.local.yaml, paths must be relative to the project.
  • In ~/.config/poolside/settings.yaml, paths must be absolute or start with ~.

​
Read-only configuration

Allow reading files but block modifications. 
tools:
  shell:
    disabled: true

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

​
Read-write configuration

Allow edits only in specific directories. 
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 user-global ~/.config/poolside/settings.yaml file: 
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. Example configuration: 
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
  • network destinations
Sandbox availability depends on your agent configuration and your organization’s permissions. You can manage sandbox settings in the IDE using /sandbox.

​
Glob reference

​
Tool rule syntax

PatternMatchesDoes not match
go vet *go vet, go vet -vettool shadowgo run
gh * list *gh pr list, gh gist listgh list
Rules:
  • * matches zero or more characters including /
  • ** is not supported

​
Path rule syntax

PatternMatchesDoes not match
/src/**/*.go/src/main.go, /src/pkg/run.go/other/src/main.go
C:/**/bin/*C:/Tools/bin/app.exeD:/Tools/bin/app.exe
Rules:
  • * matches characters except /
  • ** matches across directories
  • *:/Program Files/** matches any Windows volume