Tool Security

Configure security sandboxes, rate limiting, circuit breakers, and observability for this agent's tool usage.

Overview
How It Works
Key Concepts
Best Practices
Troubleshooting
Related Pages

Overview

For Everyone

Agents use tools to interact with the world — reading files, browsing the web, running commands, calling APIs. Tool Security controls what each agent is allowed to do with its tools. It's like giving an employee a key card that only opens certain doors: you define which directories they can access, which websites they can visit, which commands they can run, and how fast they can work.

For Developers

A single endpoint provides the merged view:

GET /agents/:id/tool-security — Returns { orgDefaults, agentOverrides, toolSecurity } where toolSecurity is the merged result.
PATCH /agents/:id/tool-security — Saves overrides as { toolSecurity: overrides, updatedBy: 'dashboard' }.

The save process computes a diff between the current merged config and org defaults — only changed sections are stored as overrides. The "Reset to Org Defaults" action sends an empty {} as overrides.

Tool security is split into two domains:

Security — pathSandbox, ssrf, commandSanitizer
Middleware — audit, rateLimit, circuitBreaker, telemetry

How It Works

Load — Org defaults, agent overrides, and the merged config are fetched from a single endpoint.
View — Each section shows an "ORG DEFAULT" badge for inherited settings. If agent overrides exist, an indicator banner lists which sections are customized.
Configure — Modify any setting. Changes are tracked in the merged config.
Save — Only the diff from org defaults is saved as agent overrides. A sticky save bar appears at the bottom when changes exist.
Reset — "Reset to Org Defaults" removes all agent-level overrides, reverting everything to org defaults.

Key Concepts

Override Model

Tool security follows a layered inheritance model:

Org Defaults — Base settings that apply to all agents.
Agent Overrides — Per-agent modifications that take precedence.
Merged Config — The effective configuration (org defaults + agent overrides).

When you modify a setting, it becomes an agent-level override. Fields labeled "ORG DEFAULT" are inherited and not stored at the agent level.

Path Sandbox

Restricts file system access. Prevents agents from reading sensitive files like .env, SSH keys, or system configs.

Enable path sandboxing — Master toggle.
Allowed Directories — List of paths the agent can access (e.g., /home/user/project). Tag input for easy management.
Blocked Patterns — Regex patterns for files to block (e.g., \.env$, \.ssh/). Applied even within allowed directories.

SSRF Protection

Server-Side Request Forgery protection prevents agents from accessing internal infrastructure.

Allowed Hosts — Whitelist of external hosts the agent can access (e.g., api.example.com).
Blocked CIDRs — IP ranges to block (e.g., 10.0.0.0/8, 169.254.0.0/16 for cloud metadata).

Command Sanitizer

Controls shell command execution. Full-width card because command security deserves extra attention.

Mode:
- Blocklist — Block specific dangerous patterns. Easier to configure — just block what's dangerous.
- Allowlist — Only permit specific safe commands. More secure but requires listing every allowed command.
Allowed Commands — Commands permitted in allowlist mode (e.g., git, npm, node).
Blocked Patterns — Regex patterns to block in blocklist mode (e.g., curl.*\|.*sh, rm -rf).

Audit Logging

Records every tool invocation for compliance and debugging.

Keys to Redact — Sensitive parameter names to redact from logs (e.g., password, api_key, custom_secret).

Rate Limiting

Per-tool call limits using a token bucket algorithm. Each tool has:

Max/min — Maximum calls allowed in the bucket.
Refill/min — How many calls are replenished per minute.

Default limits vary by tool type:

Tool	Default Max	Default Refill
`bash`	10/min	10/min
`browser`	20/min	20/min
`web_fetch`, `web_search`	30/min	30/min
`read`, `write`, `edit`, `glob`, `grep`, `memory`	60/min	60/min

Circuit Breaker

Automatically stops calling a tool after consecutive failures. Prevents wasting tokens on broken integrations.

After N consecutive failures, the circuit "opens" (tool disabled).
After a cooldown period, the circuit "closes" (tool re-enabled for testing).

Telemetry

Collects execution timing, success rates, and usage patterns. Useful for identifying slow tools, optimizing workflows, and capacity planning.

Best Practices

Always enable path sandboxing — No agent should have unrestricted file system access. Whitelist only the directories it needs.
Block cloud metadata endpoints — Add 169.254.0.0/16 to blocked CIDRs to prevent credential theft via cloud metadata.
Use blocklist mode for commands — It's practical. Block dangerous patterns like rm -rf /, curl | sh, and chmod 777.
Set lower rate limits for expensive tools — Browser and bash are resource-intensive. Keep their limits conservative.
Enable circuit breakers — They prevent cascading failures and token waste when external services go down.
Only override what you need — Use "Reset to Org Defaults" to clean up unnecessary overrides. Fewer overrides = easier maintenance.
Enable telemetry for optimization — The data helps you understand which tools the agent uses most and which are slowest.

Troubleshooting

Agent can't read a file it should access

Check the Path Sandbox allowed directories. The file's parent directory must be in the whitelist. Also check blocked patterns — a broad regex like \.json$ could block needed config files.

Tool being rate limited

The agent is calling the tool faster than the configured rate. Increase the max/refill values for that tool, or investigate why the agent is making so many rapid calls.

Circuit breaker keeps opening

The underlying tool or API is failing repeatedly. Fix the root cause (API down, wrong credentials, etc.) rather than disabling the circuit breaker.

Reset to Org Defaults didn't work

The reset sends empty overrides to the server. If values still appear customized, refresh the page. The merged view may be showing org defaults that look different from what you expected.

Sticky save bar won't appear

The save bar only appears when the merged config differs from what was loaded. If you changed a value back to its original, the dirty state clears. Make a definitive change to trigger it.

Agent Security Agent Guardrails Agent Activity Log Agent Deployment

AgenticMail Enterprise Documentation Report an issue