Rules let you define policies that control what your agents are allowed to do. Instead of giving an agent unrestricted access to every service it has credentials for, you can set boundaries: block certain operations entirely, or rate-limit them so damage is contained.
Why rules matter
Credentials get an agent through the door. Rules decide what it can do once inside.
Without rules, an agent with Gmail credentials can read, send, and delete emails with no limit. That’s useful, but it’s also how you get an agent mass-deleting an inbox before anyone can stop it. Rules let you say things like “this agent can access Gmail, but it can only delete 3 messages per hour.”
Deterministic enforcement, not prompts
You can tell an agent “never delete emails without my approval” in a system prompt. But a prompt is a suggestion, not a guarantee. Agents are non-deterministic. They can be manipulated through prompt injection, they can misinterpret instructions, or they can be too eager to please and take actions you didn’t intend. Writing “please don’t do that” in a prompt gives you no certainty that it won’t happen.
Rules are different. They’re enforced outside the agent, at the gateway level, before the request ever reaches the external service. No amount of prompt manipulation, jailbreaking, or overly helpful behavior can bypass a rule. If a rule says “block DELETE requests to Gmail,” that request is blocked. Every time, deterministically, regardless of what the agent was told or tricked into doing.
This is the difference: rules move security boundaries from a place the agent controls (its own context) to a place it can’t touch (the proxy layer). That’s what makes them a real safety mechanism instead of a best-effort instruction.
Creating a rule
From the dashboard, go to Rules and click + New Rule. A rule has two parts:
Step 1: Endpoint
Define which requests the rule applies to.
| Field | Description | Example |
|---|
| Name | A human-readable label for the rule | Block Gmail deletes |
| Host pattern | The API hostname to match. Use *.example.com for wildcard subdomains | gmail.googleapis.com |
| Path pattern | (Optional) The URL path to match. Use /path/* for prefix matching | /gmail/v1/users/*/messages/* |
| Method | The HTTP method to match: GET, POST, PUT, PATCH, DELETE, or any | DELETE |
| Scope | Which agents this rule applies to: a specific agent or all agents | All agents |
Step 2: Action
Choose what happens when a request matches.
| Action | Behavior |
|---|
| Block | Deny the request entirely. The agent receives a 403 response. |
| Rate Limit | Allow up to N requests per time window, then block. Excess requests return 429. Each agent tracks its own counter. |
| Manual Approval | Hold the request and wait for a human to approve or deny it. The agent’s connection stays open until a decision is made (up to 5 minutes). |
Monitor action is coming soon. It will log matching requests without blocking, useful for auditing before enforcing.
Rate limit options
When you select Rate Limit, you configure:
- Request count: How many requests to allow (e.g.,
20)
- Time window: The period over which the count resets (
minute, hour, day)
Each agent has its own counter. If you set 20 requests per hour, each agent gets its own 20.
Examples
Block all email deletions
A rule that prevents any agent from deleting Gmail messages:
| Field | Value |
|---|
| Host pattern | gmail.googleapis.com |
| Path pattern | /gmail/v1/users/*/messages/* |
| Method | DELETE |
| Scope | All agents |
| Action | Block |
Rate-limit Slack messages
Allow agents to post to Slack, but cap it at 10 messages per hour:
| Field | Value |
|---|
| Host pattern | slack.com |
| Path pattern | /api/chat.postMessage |
| Method | POST |
| Scope | All agents |
| Action | Rate Limit, 10 requests per hour |
Require approval before sending emails
Require human sign-off before any agent sends a Gmail message:
| Field | Value |
|---|
| Host pattern | gmail.googleapis.com |
| Path pattern | /gmail/v1/users/me/messages/send |
| Method | POST |
| Scope | All agents |
| Action | Manual Approval |
Block a specific agent from accessing a service
Prevent your “research-agent” from touching your GitHub repos:
| Field | Value |
|---|
| Host pattern | api.github.com |
| Method | Any |
| Scope | research-agent |
| Action | Block |
Conditions
Rules can include conditions that inspect the request body for finer-grained matching. Without conditions, a rule matches any request to the specified host/path/method. With conditions, the rule only applies when the request body matches all specified conditions.
Adding conditions
Each condition has:
| Field | Description | Required |
|---|
| Target | What to inspect. Currently body (the request body). | Yes |
| Operator | How to match. Currently contains (substring match). | Yes |
| Value | The string to search for. | Yes |
| Key | A JSON key path to scope the match to a specific field. If omitted, the entire body is searched. | No |
Examples
Block emails containing sensitive keywords:
| Field | Value |
|---|
| Host pattern | gmail.googleapis.com |
| Path pattern | /gmail/v1/users/me/messages/send |
| Method | POST |
| Action | Block |
| Condition | target: body, operator: contains, value: CONFIDENTIAL |
| Field | Value |
|---|
| Host pattern | api.stripe.com |
| Path pattern | /v1/charges |
| Method | POST |
| Action | Manual Approval |
| Condition | target: body, operator: contains, value: 10000, key: amount |
How rules interact with credentials
Rules and credentials are independent. An agent needs matching credentials to authenticate with a service, and rules add a policy layer on top. If an agent has Gmail credentials but a rule blocks DELETE requests to Gmail, the request is blocked before credentials are ever injected.
The evaluation order is:
- Request comes in from the agent
- Rules are checked in priority order: Block > Manual Approval > Rate Limit
- If blocked → 403. If rate-limited → 429. If manual approval → held until approved or denied.
- Credentials are matched by host and path
- Credentials are injected and the request is forwarded
Manual Approval
Manual Approval lets a human review and approve or deny agent requests before they reach the external service. When a request matches a manual approval rule, the gateway holds the agent’s connection open (up to 5 minutes) while it waits for a decision.
How it works
- An agent makes a request that matches a manual approval rule
- The gateway holds the request. The agent’s HTTP connection stays open, waiting for a response.
- Your application polls the gateway for pending approvals via the Node.js SDK
- A human reviews the request details (method, URL, headers, body preview) and approves or denies
- The gateway either forwards the request to the upstream service (approve) or returns a 403 (deny)
If nobody responds within 5 minutes, the request is automatically denied.
What the reviewer sees
The approval metadata includes:
- Method and URL: what the agent is trying to do (e.g.,
POST https://gmail.googleapis.com/.../send)
- Headers: sanitized request headers (credentials are stripped)
- Body preview: the first 4KB of the request body, so reviewers can see the actual content (e.g., the email being sent)
- Agent identity: which agent made the request
Integrating with the SDK
Manual approval requires an application that polls for pending approvals and submits decisions. The Node.js SDK provides configureManualApproval() for this. See the SDK docs for the full integration guide.
App Permissions
App permissions are a higher-level way to control what agents can do with specific integrations, without writing individual rules by hand. Instead of manually specifying host patterns, paths, and methods, you select from a pre-defined list of operations for each integration and set their permission level.
How it works
For supported integrations, OneCLI provides a curated list of operations grouped into read and write categories. Each operation maps to a specific API endpoint. Organization admins can set each operation to one of three permission levels:
| Permission | Behavior |
|---|
| Allow | The operation is permitted (default) |
| Manual Approval | The operation requires human approval before executing |
| Block | The operation is denied |
Supported integrations
App permissions are available for: Affinity, AWS, Cloudflare, Datadog, Dropbox, Fly.io, HubSpot, LinkedIn, Microsoft OneNote, Microsoft Word, Monday.com, MongoDB Atlas, Outlook Calendar, Outlook Mail, Sentry, Supabase, and Zoom.
Setting app permissions
From the OneCLI Cloud dashboard, navigate to Organization > Rules > App Permissions, select an integration, and configure the permission level for each operation.
You can also manage app permissions via the API:
# Get current permissions for an integration
curl https://api.onecli.sh/v1/org/rules/permissions/hubspot \
-H "Authorization: Bearer $API_KEY"
# Update permissions
curl -X PUT https://api.onecli.sh/v1/org/rules/permissions/hubspot \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"changes": [{"toolId": "create_contact", "permission": "manual_approval"}]}'
App permissions vs custom rules
App permissions and custom rules serve different purposes:
- App permissions are org-level defaults that apply to all agents. They provide a quick way to set up guardrails for an integration without writing pattern-matching rules.
- Custom rules offer finer control: per-agent scoping, rate limiting, conditions, and arbitrary host/path patterns.
Both are evaluated at the gateway. If a request matches both an app permission and a custom rule, the most restrictive action wins.
Coming soon
- Monitor action: Log matching requests without blocking, useful for auditing before enforcing
- Time-bound access: Grant access only during specific time windows
