AgentOS markAgentOS

Approvals and Permissions


Approvals and permissions control how AgentOS tools are allowed to act. They matter most when an agent can write files, run shell commands, publish artifacts, post into channels, or call external services.

Use this page before running unattended automation or giving a channel-connected agent broad tool access.

Permission Profiles

Single-shot automation accepts an explicit permission profile:

agentos agent --permissions restricted -m "Inspect this repo"
agentos agent --permissions on -m "Run with host execution and approvals"
agentos agent --permissions bypass -m "Trusted local automation"
agentos agent --permissions full -m "Fully trusted local automation"

Practical meaning:

ProfileUse when
restricted / offThe task should stay conservative and avoid elevated execution.
onHost execution is allowed, but approval checks still matter.
bypassYou trust the task enough to auto-grant approvals while keeping sensitive-path checks.
fullYou fully trust the task and environment. Use sparingly.

For automation, prefer the narrowest profile that can complete the task.

These profiles apply to interactive CLI and Web turns. For cron turns (unattended automation), the default elevated execution posture is controlled by permissions.cron_default_mode (which defaults to bypass). By default, cron jobs of kind agent_turn run elevated (under bypass), whereas other job kinds (like reminders and script runs) are never elevated. You can explicitly override this default for any individual job by passing --no-elevated (to opt out of elevation) or --elevated-mode {bypass,full} (to pick a specific mode) during job creation or update. See CLI Reference for details and security implications.

Workspace Containment

Set a workspace for file and shell work:

agentos agent \
  --workspace /path/to/project \
  --workspace-strict \
  -m "Summarize this repo"

Contain writes to the workspace or scratch directory:

agentos agent \
  --workspace /path/to/project \
  --workspace-lockdown \
  --scratch-dir /path/to/project/.scratch \
  -m "Investigate and prepare a minimal patch"

Use --workspace-lockdown for unattended runs where accidental writes outside the project would be unacceptable.

Interactive Approvals

Interactive chat surfaces can pause sensitive tool calls for a human decision. The terminal chat supports:

/approvals
/approvals reset
/permissions status
/permissions on
/permissions off
/permissions bypass
/permissions full
/forget

Use these commands when you need to inspect or reset cached approval decisions during a chat.

Cached Intents

Approving a destructive action caches the intent — kind plus target path — rather than the literal command, so a paraphrased retry (rm /tmp/x followed by os.remove("/tmp/x")) proceeds without a second prompt.

The kind carries a set of escalation capabilities, and a cached approval covers a retry only when its capability set is a superset of the retry's. The capabilities are independent — they are not a single ladder:

CapabilityMeaningGranted by
(none)delete this one pathrm X, os.remove, os.unlink, os.rmdir, Path(X).unlink(), Path(X).rmdir()
recursivedelete the whole tree below itrm -r/-R/--recursive, shutil.rmtree(X)
parentsmay also delete empty ancestorsos.removedirs(X)
forcerm's -f/--forcerm -f/--force

So a delete:recursive approval covers a plain rm X, but a delete:force approval does not cover shutil.rmtree(X) — force says nothing about recursion. Escalation always re-prompts: approving rm /tmp/logs does not authorize rm -rf /tmp/logs.

/approvals lists cached entries as scope kind:target, and /forget <path> drops every grade recorded for that path.

The Web UI also provides an approvals surface for reviewing pending actions outside the message scrollback.

Image Flow Spend Prompts

An agent's flow_run (docs/flows.md) asks before it spends more than [flows].agent_cost_limit_usd on one run, or an amount that cannot be estimated, in its own namespace, flow. Every surface offers only Allow once and Deny: no "Always Allow", no "Bypass" / "Stop Asking", and the gateway ignores both for this namespace if a client sends them, so a spend approval never unlocks further spend or elevates the session. A session-wide bypass (/elevated, or "Stop Asking" on a shell prompt) releases pending exec prompts only, never a spend. A denial sticks: for 30 minutes every later flow_run of that flow in that session asks again, whatever its inputs or cost.

Coding-Harness (ACP) Prompts

Coding harnesses started with sessions_spawn(runtime="acp") (Claude Code, Codex, Gemini CLI, ...) ask for permission through the same approval queue, in two extra namespaces:

NamespaceWhat it isApprove meansDeny / timeout means
acpThe harness wants to run a command, edit a file, fetch a URL, ... Shown as "<harness> wants to <kind>: <title>", for example Codex wants to run: git push.Allow this one call.Reject this call; the harness carries on without it.
acp_elicitationThe harness asks a question (a small form) or asks you to finish a step in the browser (a link). Shown as "<harness> asks: <message>" or "<harness> asks you to open a link: <url>".Answer: forms send their values as the resolve payload {"content": {"<field>": <value>}}; a link means "I finished the step".Decline.

How a harness prompt is answered depends on [acp].permission_mode:

permission_modeBehaviour
ask (default)Every prompt waits in the approval queue for up to [acp].approval_timeout_s (default 900 s); no answer rejects it.
approve-readsReads, searches, fetches and thinking are allowed without asking; anything else is asked as above.
approve-allEverything is allowed without asking.
deny-allEverything is rejected without asking.

A spawn may pick a stricter mode than the configured one, never a looser one. When nobody can answer (an unattended cron or channel run), ask follows [acp].non_interactive_permissions: fail (default) ends the harness turn with ACP_PERMISSION_PROMPT_UNAVAILABLE, deny rejects the prompt and lets the harness continue. Questions are always declined when nobody can answer.

Choosing Always (or Bypass) on an acp prompt remembers the grant for that harness session only, per tool kind and, for commands, per program and subcommand (git push): it never changes the session's elevated mode and is forgotten when the harness session closes. Forms are asked at most three questions at a time, a secret field always on its own; answers are cleared from the queue as soon as the harness has them and are never logged. Questions time out after 15 minutes.

Over RPC, approval.list lists pending approvals of every namespace with a readable title (params.namespace narrows it), and exec.approval.resolve (or POST /api/approvals/resolve) accepts an optional payload object for form answers.

Where a prompt reaches you

Every pending approval is listed on the console's approvals page and in the desktop app's approval dialog. Beyond that:

  • Web Push. In the web console, Settings → Push notifications for approvals subscribes this browser (it asks for notification permission; it needs HTTPS or localhost). Each new approval is pushed with a link to the approvals page; when it is resolved a replacement notice says how — granted, denied, expired, or cancelled because its run was stopped. The push goes out from the same queue write that announces approval.resolved to consoles. Messages are encrypted for the subscribed browser, expire with the approval and carry only its title. Turn it off per gateway with [push] web_enabled = false.
  • Parent sessions. An approval records audience_session_keys: the session that asked, then the sessions that spawned it (a coding harness's or subagent's parent, and that session's parent). The approval.requested event and GET /api/approvals carry it, and the chat view of any of those sessions shows the turn as waiting for approval while the child's prompt is pending. When the nearest such parent is delivered on Telegram, Discord or Slack, the prompt with Approve / Deny buttons is also sent to that chat.
  • Channel custody. On Telegram, Discord and Slack, Approve / Deny works only in the chat the approval's session is delivered to — a DM session answers to its own sender, a group or channel session to members of that chat, a child session to its parent's chat, and the shared main DM session to the chat it last delivered to. A paired sender cannot resolve a prompt that belongs to the web console, the desktop or another chat.

Sandbox Posture

Inspect sandbox posture:

agentos sandbox status
agentos sandbox status --json

Set posture:

agentos sandbox on
agentos sandbox bypass
agentos sandbox full
agentos sandbox reset

Restart the gateway after changing global sandbox posture:

agentos gateway restart
SituationRecommended approach
First run in a repo--workspace plus --workspace-strict
Read-only investigation--permissions restricted
Local patch with tests--workspace-lockdown plus a scratch directory
Web UI task with writesKeep approvals visible and review sensitive actions
Channel-connected agentConservative permissions and explicit channel setup
Unattended automationBound timeout/iterations and choose the narrowest workable permissions

Troubleshooting

If a tool is denied:

agentos sandbox status
agentos doctor

Then check:

  • whether the surface supports live approvals;
  • whether the workspace path is correct;
  • whether cached approvals need to be reset;
  • whether the task should run with a different permission profile.

Read next: