---
title: How to Configure Agent Permissions (public)
description: Write session permission policies that allow, deny, or require approval for agent actions.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/configure-permissions/
last_updated: "2026-09-23"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# How to Configure Agent Permissions (public)

DigitalOcean Harness Runtime provides managed, hardware-isolated microVM sandboxes with built-in tools such as Chromium to run harnesses and execute arbitrary code. Rich lifecycle APIs preserve conversational history and working state across sessions, letting you pause, resume, and fork work to control costs and adapt to the nonlinear nature of agentic workflows. Scale complete agents such as Claude Code or use sandboxes independently for code execution, all through the same service. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for example use cases.

By default, agents ask you to approve most or all of what they do, which can be slow. Permission policies control what a session may do without interruption. They let you pre-approve routine actions, require approval for sensitive ones, and block dangerous ones outright, so the agent can work at a natural pace while you stay in control. Add a permissions block to your agent, validate it, then confirm behavior on a live session. For details on how agents evaluate permissions, see [Permission Policy](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/overview/index.html.md#permission-policy).

**Warning**:

  You set and own the permission policy. `allow` runs the tool immediately. For Action Gateway tools (`do.actions/*`), the `claude-code` and `codex` adapters support gateway approval prompts for `ask` decisions. Other adapters handle approvals differently. Verify the behavior with the adapter you deploy. See [Connect Action Gateway to Harness Runtime](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/connect-action-gateway/index.html.md).

## Add a Permissions Block

Open your environment spec and add rules under `permissions`. The following example allows the agent to run any git command and write anywhere in its workspace without asking; never run `rm -rf`; and anything not listed falls back to `default`, which in this example is `ask`:

```yaml
permissions:
  default: ask
  rules:
    - tool: bash
      match: { command: "git *" }
      action: allow
    - tool: bash
      match: { command: "rm -rf *" }
      action: deny
    - tool: file.write
      match: { path: "/workspace/**" }
      action: allow
```

For native Harness Runtime actions, the last matching rule in the list wins. A later rule overrides an earlier one regardless of how specific either rule is. Action Gateway evaluates its projected tool rules separately using [most-specific matching rules](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/tool-policies/index.html.md), not list order. Verify both kinds of permissions when an agent uses gateway tools.

**Note**:

  Rules match literally, against specific commands or paths, not against your intent. A denied action doesn’t block the goal behind it. For example, if you deny `ls` on a directory or reading a particular file, the agent may still reach the same result another way (for example with `find`, or by reading the file through a different tool). To constrain a capability, cover the other commands that could achieve it, and confirm the result on a live session.

## Validate the Policy Without Starting a Session

First, validate the policy without starting a session:

```shell
curl -X POST https://api.digitalocean.com/v2/agents/sessions/policy/validate \
  -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @your-spec.yaml
```

A response with `ok: true` means the policy is accepted. It does not prove runtime behavior for every agent. Validation is a useful first check, then confirm with live commands. If the response shows `ok: false`, fix the reported rule and validate again. Acceptance does not guarantee identical runtime behavior across adapters.

## Confirm Behavior on a Live Session

Deploy a session (or sessions) and ask the agent to run the commands, and confirm each one is allowed, prompted, or blocked as you intended to validate the real behavior on the exact agent you’re using.

1. Start and attach to the session.
2. Ask the agent to run commands covered by your allow, ask, and deny rules.

Answer approval prompts in the terminal with `Enter` or `y`, or reject with `n`.

To resolve a pending approval without attaching, run:

```shell
doctl harness-runtime approve <session-id-or-name> <request-id> approve
```

Replace `approve` with `reject` or `defer` as needed.

3. Confirm each outcome matches your intent.
4. Adjust rules and repeat.

**Note**:

  If no rule matches, the action uses `permissions.default`. File-level rules may be unsupported on some adapters. Always verify on the adapter you deploy.