Skip to main content
Every action in OpenSwarm has a permission policy that determines how the agent interacts with it. Permissions give you fine-grained control over agent behavior — from fully autonomous operation to human-in-the-loop approval for sensitive actions.

​
Permission Policies

There are three policies:
PolicyIconBehavior
Always AllowGreen checkmarkThe agent executes the action without asking. Silent and autonomous.
AskYellow handThe agent pauses and asks the user for approval before executing.
DenyRed blockThe agent cannot use this action at all. It won’t appear in the agent’s available tools.
The default policy for most built-in core actions is always_allow. For MCP integration actions, the default is ask — so newly discovered third-party tools always require approval until you explicitly allow them.

​
Permission Granularity

Permissions can be set at four levels, from broadest to most specific:

​
1. Section Level

Each action set (Core Actions, Extended Actions, Browser, Apps) has an enable/disable toggle in its card header. Disabling a section sets every action in it to deny. Re-enabling sets them all to always_allow.

​
2. Category Level

Within a section, actions are grouped by category (e.g., Filesystem, System, Search, Interaction). Each category header has its own permission toggle that applies to all actions in that category at once. For example, setting the Filesystem category to ask changes Read, Edit, and Write to all require approval. If actions within a category have mixed policies, the category toggle shows a mixed state.

​
3. Individual Action Level

Every action has its own permission toggle. This is the most granular level — you can set Read to always_allow while keeping Write on ask and Bash on deny.

​
4. Integration Level

Integrations (Google Workspace, xbird, custom servers) have an additional layer of granularity. After tool discovery, each integration’s actions are organized by:
  • Read vs. Write — actions are automatically categorized based on their name prefix (e.g., get_, list_, search_ → read; create_, delete_, send_ → write)
  • Service — actions are grouped by the service they belong to (e.g., Gmail, Calendar, Drive, Sheets for Google Workspace; Tweets, Timeline, Network for Twitter)
  • Service Group — services are further grouped by provider (e.g., all Google services under “Google”)
This lets you do things like:
  • Allow all read actions but require approval for writes
  • Enable Gmail but deny Calendar access
  • Allow searching tweets but block posting

​
Bulk Permission Actions

​
Read-Only Mode

For MCP integrations, you can quickly set all read actions to always_allow while leaving write actions on ask. This is useful when you want the agent to freely gather information but require approval before making changes.

​
Reset to Defaults

Resetting permissions on an MCP integration sets all individual action permissions back to ask — the safe default for third-party tools.

​
How Permissions Affect Agent Behavior

When an agent encounters a deny action, it simply doesn’t have access to that tool — it won’t attempt to use it or mention it. When an agent encounters an ask action, it will:
  1. Prepare the tool call with all arguments
  2. Pause execution and display an approval bar in the chat
  3. Wait for the user to approve or reject
  4. Continue only if approved
A good starting configuration: set Core Actions to always_allow for a smooth experience, keep Extended Actions on always_allow, and leave MCP integration write actions on ask until you trust the workflow.

​
Permission Storage

Permissions are persisted across sessions:
  • Built-in action permissions are stored in a central JSON file at the configured BUILTIN_PERMISSIONS_PATH.
  • MCP integration permissions are stored per-tool inside each tool’s JSON definition file, under the tool_permissions field. This includes the auto-categorized read/write mappings, service groupings, and per-action policies.