---
title: Agent Permissions
description: How Pinchy controls what each agent can do using an allow-list of tools and scoped directory access.
---

## Why agent permissions matter

AI agents are powerful — but in an enterprise setting, they must be constrained. An agent that can read any file on the server or execute arbitrary commands is a liability. Pinchy enforces **per-agent permissions** so each agent can only use the tools an admin explicitly enables.

## Allow-list approach

Pinchy uses an **allow-list** model: agents have **no tools by default**. An admin must explicitly enable each tool an agent is allowed to use. This is the opposite of a deny-list approach where everything is allowed unless blocked — with Pinchy, nothing is allowed unless granted.

This means a newly created agent cannot access files, run commands, or browse the web until an admin configures its permissions.

![Agent Permissions — tool allow-list with directory scoping](/screenshots/agent-settings-permissions.png)

## Tool categories

Pinchy organizes tools into two categories:

### Safe Tools

Safe tools provide **sandboxed access** to approved directories and the agent's own workspace. The agent cannot access anything outside those boundaries.

Every agent can always list and read files from its own workspace — any text-based file you upload in a chat is immediately accessible. This includes Markdown, CSV, JSON, source code, and more, in addition to PDF text extraction and image analysis.

| Tool               | Always on? | What it does                                                                                              |
| ------------------ | ---------- | --------------------------------------------------------------------------------------------------------- |
| **Read workspace** | ✓ always   | List and read any file the agent's workspace (`uploads/` directory), including PDFs and images            |
| **Write files**    | optional   | Save files back to the agent's own workspace. Agents must explicitly request overwrite on existing files. |

The **Knowledge Base** section below the tools lets you select which directories under `/data/` this agent can also read. These are admin-curated directories mounted into the container — separate from the agent's own workspace. Every access request is validated at runtime against the configured paths.

### Web Search Tools

Web search tools give the agent access to live web information via the Brave Search API. These require a Brave Search API key configured in Settings → Integrations.

| Tool                | What it does                                                          |
| ------------------- | --------------------------------------------------------------------- |
| **Search the web**  | Query Brave Search and return ranked results (`pinchy_web_search`)    |
| **Fetch web pages** | Download and extract readable content from a URL (`pinchy_web_fetch`) |

When web search tools are enabled, additional per-agent filters appear: Domain restrictions (with Include/Exclude modes per domain), Freshness, Language, and Region. See [Set Up Web Search](/guides/web-search-setup/) for details.

:::caution[Data exfiltration risk]
If an agent has **Fetch web pages** enabled alongside access to sensitive data (files or Odoo records), Pinchy shows a security warning. A malicious web page could contain instructions that trick the agent into encoding private data into a URL. Mitigate this by adding **Include** domain restrictions that limit the agent to known, trusted sites.
:::

### Powerful Tools

Powerful tools give the agent **direct access to the server**. Only enable them if you understand the risks.

| Tool              | What it does                                      |
| ----------------- | ------------------------------------------------- |
| **Run commands**  | Execute shell commands on the server              |
| **Read any file** | Read any file on the system, without restrictions |

An agent with powerful tools enabled has significantly broader capabilities. Use these only for trusted, internal use cases.

## The Permissions tab

Admins configure tool permissions in the **Permissions tab** of a shared agent's settings page. To access it:

1. Open a shared agent's chat
2. Click the settings icon (gear) to open Agent Settings
3. Select the **Permissions** tab

The Permissions tab shows all available tools grouped by category. Check or uncheck tools to control what the agent can do, then click **Save**.

:::note
The Permissions tab is only visible to admins and only for shared agents. Personal agents (the auto-created Smithers each user gets) don't have this tab — they run with default tools only.
:::

For the full list of tabs in Agent Settings and who sees which, see [Agent Settings](/concepts/agent-settings/).

### Configuring directory access

The **Allowed Directories** picker appears in the Knowledge Base section of the Permissions tab. Select which directories under `/data/` this agent should be able to read — these are in addition to the agent's own workspace files.

For example, if you mounted your HR policies at `/data/hr-policies`, select that directory to let the agent read those documents — and nothing else.

See the [Mount Data Directories](/guides/mount-data-directories/) guide for instructions on making directories available.

## How permissions reach OpenClaw

Pinchy controls what tools an agent can use. OpenClaw's native tools (shell, file system, web) are not exposed directly — Pinchy replaces them with its own sandboxed tools and integration tools. This gives Pinchy full control over what each agent can do.

Under the hood, Pinchy converts its allow-list into a deny-list at config generation time using `computeDeniedGroups()`. This function takes the list of tool IDs an admin has enabled and returns all tool groups that should be blocked. The result is written into each agent's `tools.deny` array in the OpenClaw config.

This conversion runs automatically whenever the OpenClaw config is regenerated — admins never interact with the deny-list directly.

## Integration tools

### Odoo tools

When you connect Odoo and grant an agent access to it, Pinchy automatically enables the appropriate tools based on the access level you choose. You don't need to enable these tools manually — they're managed through the Permissions tab.

| Tool          | What it does                               | Access level required |
| ------------- | ------------------------------------------ | --------------------- |
| **schema**    | Discover available models and their fields | Read-only             |
| **read**      | Read records from a model                  | Read-only             |
| **count**     | Count records matching a filter            | Read-only             |
| **aggregate** | Run aggregations (sum, average, group by)  | Read-only             |
| **create**    | Create new records                         | Read & Write          |
| **write**     | Update existing records                    | Read & Write          |
| **delete**    | Delete records                             | Full                  |

For example, setting an agent to "Read-only" for an Odoo connection enables schema, read, count, and aggregate. Upgrading to "Read & Write" adds create and write. "Full" adds delete.

### Web Search tools

Web search tools are enabled individually per agent via checkboxes in the Permissions tab. Unlike Odoo tools, there are no access levels — you simply check the tools you want.

| Tool                | Tool ID             | What it does                            |
| ------------------- | ------------------- | --------------------------------------- |
| **Search the web**  | `pinchy_web_search` | Query Brave Search for relevant results |
| **Fetch web pages** | `pinchy_web_fetch`  | Download and read content from a URL    |

Each agent can also have per-agent filters (Domain restrictions with Include/Exclude modes, Freshness, Language, Region) that control what the agent can access. See [Set Up Web Search](/guides/web-search-setup/) for configuration details.

### Email tools

When you connect a Gmail account and grant an agent access to it, Pinchy enables email tools based on which operations you check. Each permission maps to a specific set of tools.

| Permission        | Tools enabled                              | What the agent can do                       |
| ----------------- | ------------------------------------------ | ------------------------------------------- |
| **Read messages** | `email_list`, `email_read`, `email_search` | List, read, and search emails               |
| **Create drafts** | above + `email_draft`                      | Create draft emails, including reply drafts |
| **Send messages** | above + `email_send`                       | Send emails immediately — cannot be undone  |

Permissions are additive — granting Send automatically includes Read and Draft. Each permission is selected per-agent, so you can have one agent that only reads email and another that can send on your behalf.

:::caution[Send is powerful]
**Send messages** lets the agent send email from the connected account without human review. Prefer **Create drafts** when a human can review before sending — it's safer by default.
:::

For the full setup walkthrough, see [Connect Email](/guides/connect-email/). For details on setting up connections in general, see [Integrations](/concepts/integrations/).

## Agent templates and default permissions

When you create an agent, you pick a template. Each template comes with different default tool permissions:

| Template           | Default tools                           | Use case                                           |
| ------------------ | --------------------------------------- | -------------------------------------------------- |
| **Knowledge Base** | `pinchy_ls`, `pinchy_read` (safe tools) | Answer questions from selected documents           |
| **Custom Agent**   | None                                    | Start from scratch, configure permissions manually |

After creating an agent, you can change its permissions at any time via the Permissions tab.

## Defense in depth

Pinchy does not rely on any single layer for security. Four layers work together:

1. **Docker volumes** — only directories explicitly mounted into the container are accessible at all
2. **Allow-list enforcement** — only tools an admin explicitly enables are available to the agent
3. **Plugin path validation** — the `pinchy-files` plugin checks every requested path against the agent's allowed directories
4. **Symlink resolution** — paths are resolved to their real location before validation, preventing symlink-based escapes

If any one layer fails, the others still prevent unauthorized access.

## Agent access control

Not every user can see every agent. Pinchy enforces access rules:

- **Admins** can access all agents — personal and shared
- **Users** can access shared agents (created by anyone) and their own personal agent
- Users **cannot** see or access other users' personal agents

Only admins can view and modify the Permissions tab. Regular users can chat with agents they have access to, but cannot change what tools those agents use.

:::note
All permission changes are logged in the [audit trail](/concepts/audit-trail/). When an admin enables or disables tools for an agent, the change is recorded with the admin's identity, the affected agent, and the old and new permissions.
:::

## The `/data/` convention

All agent-accessible files live under `/data/` inside the Pinchy container. This is mounted as a Docker volume, and you can bind-mount host directories into subdirectories of `/data/`.

For example, if you mount your company's HR policies at `/data/hr-policies`, an agent configured to access that directory can read those documents — and nothing else.

See the [Mount Data Directories](/guides/mount-data-directories/) guide for setup instructions.
