Tool Permissions

Every agent has a tools configuration block that controls which tools it can access. This lets you create agents with different security profiles -- from full-access coders to restricted read-only analysts.

Allow/Deny Patterns

Tool permissions use glob-style patterns to match tool names:

tools:
  allow:
    - "files:*"          # All functions in files.py
    - "search:*"         # All functions in search.py
    - "web:search"       # Only the search function in web.py
  deny:
    - "shell:*"          # No shell access

Pattern Syntax

Patterns match against the script:function format (colon-separated). Under the hood, tools are exposed to the LLM with double-underscore naming (files__read_file), but permission patterns use the colon syntax.

Precedence

Deny always wins. If a tool matches both an allow and a deny pattern, it is denied.

tools:
  allow:
    - "*"              # Allow everything...
  deny:
    - "shell:*"        # ...except shell tools
    - "files:write_*"  # ...and file writing

Common Configurations

Full access (default for most agents):

tools:
  allow:
    - "*"

Read-only analyst (can search and read but not modify):

tools:
  allow:
    - "files:read_file"
    - "files:read_file_lines"
    - "search:*"
    - "find:*"
    - "web:*"
  deny: []

Coder without shell (can edit files but not run commands):

tools:
  allow:
    - "files:*"
    - "edit:*"
    - "patch:*"
    - "search:*"
    - "find:*"
    - "git:*"
  deny:
    - "shell:*"

Web-only (can browse and fetch but not touch local files):

tools:
  allow:
    - "web:*"
    - "browser:*"

The will_create_tools Flag

When set to true, the agent's system prompt is augmented with instructions on how to create new supypowers tools at runtime:

will_create_tools: true

This appends a detailed template to the system prompt that teaches the agent:

• How to create a Python file in powers/ with the correct structure
• The supypower contract (Pydantic input model, no print statements, dependency declaration)
• Common patterns for HTTP requests, API calls, and secret usage

The agent can then write new tool scripts and immediately use them. This is powerful for coding agents that need to extend their own capabilities.

You: I need a tool that can convert CSV files to JSON
Agent: I'll create that tool for you.
       [creates powers/csv_utils.py with a csv_to_json function]
       The tool is now available as csv_utils__csv_to_json.

Security note: Only enable will_create_tools for agents you trust with filesystem write access. The created tools can contain arbitrary Python code.

Service Tools

When service.enabled: true and a supyagent cloud API key is available, additional tools from connected integrations (Gmail, Slack, GitHub, etc.) are automatically discovered and added to the agent's tool set.

Service tools follow the same allow/deny pattern system:

tools:
  allow:
    - "*"
  deny:
    - "gmail:send_email"    # Prevent sending emails
service:
  enabled: true

Service tools are labeled with a remote source, while supypowers tools show their script path and built-in tools show native.

Workspace Isolation

The workspace field restricts tool execution to a specific directory:

workspace: /home/user/project

When set, file operations are validated to stay within the workspace directory. This prevents the agent from accidentally (or intentionally) modifying files outside the project.

Container Sandbox

For stronger isolation, enable the container sandbox:

sandbox:
  enabled: true
  image: python:3.12-slim
  runtime: auto             # auto-detect podman or docker
  network: bridge
  memory_limit: 2g
  allow_shell: true
  setup_commands:
    - pip install pandas numpy
  extra_mounts:
    - host_path: /data/datasets
      container_path: /mnt/data
      readonly: true

When sandbox mode is enabled:

• All supypowers tools run inside the container
• The workspace is bind-mounted into the container
• Additional host paths can be mounted (read-only by default)
• Network access can be restricted (none, bridge, host)
• Memory usage is capped
• Shell tools can be disabled with allow_shell: false

The sandbox requires either podman or docker to be available on the host.

Disabling Shell in Sandbox

sandbox:
  enabled: true
  allow_shell: false       # Block shell:* tools even if tool permissions allow them

When allow_shell: false, all tools whose names start with shell__ are filtered out regardless of the tools.allow patterns.

Process Supervisor

The supervisor controls how tool execution is managed in terms of timeouts and backgrounding:

supervisor:
  default_timeout: 60                  # Seconds before auto-backgrounding
  on_timeout: background               # background, kill, or wait
  max_background_processes: 10
  force_background_patterns:
    - "*__start_server*"               # Servers always run in background
  force_sync_patterns:
    - "*__read_*"                      # Reads always complete synchronously
  tool_settings:
    "web__scrape_page":
      timeout: 120
      mode: sync

Execution Modes

For any tool, the supervisor determines how to run it:

Tools matching force_background_patterns always run in background. Tools matching force_sync_patterns always wait for completion. Per-tool settings in tool_settings override the defaults.

Background Process Management

When tools are backgrounded, the agent gets access to built-in process management tools:

• list_processes -- List all running and completed background processes
• get_process_output -- Get the output of a specific process
• kill_process -- Terminate a background process

These tools are always available and cannot be denied through tool permissions.

Related

• Configuration -- Full YAML schema reference
• Building Tools -- Creating custom tools with supypowers
• Cloud Integrations -- Connecting service tools