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:
| Profile | Use when |
|---|---|
restricted / off | The task should stay conservative and avoid elevated execution. |
on | Host execution is allowed, but approval checks still matter. |
bypass | You trust the task enough to auto-grant approvals while keeping sensitive-path checks. |
full | You 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.
Only you answer a prompt
Answering a prompt, changing how prompts are answered, forgetting remembered
answers, raising a session's permission mode and pairing a new channel sender
are refused to a connection the gateway recognizes as an agent's
(approvals.operator_required, HTTP 403): one that carries an agent token,
comes from a process the gateway spawned (Linux), or opened while an agent's
shell, background process or execute_code run was going. That covers
exec.approval.resolve, plugin.approval.resolve, exec.approvals.set,
exec.approvals.node.set, exec.approval.forget, channels.pairing.approve,
POST /api/approvals/resolve, POST /api/approvals/settings and
POST /api/elevated-mode; an elevated hint on chat.send /
sessions.send from such a connection is ignored. The desktop app (it holds
the operator secret) is never refused. A web console that connected while an
agent's shell was running is: reload it once the shell has finished, or answer
in the app.
The approval queue's database is not a way around this: a decision counts only if the gateway process that asked made it, through one of the surfaces above, on the same parameters. A row approved by writing the database directly is read as a denial.
Skill Signing Prompts
The bundled skills that sign with a hot-wallet key of their own —
senior-unilp-manager (UNIV4_LP_PRIVATE_KEY), poolsdotfun-token-launcher
(POOLSFUN_PRIVATE_KEY) and the GMGN skills (GMGN_PRIVATE_KEY) — never get
that key in a process the agent drives: not its shell, execute_code, a cron
script, an MCP server, a coding harness or a lifecycle hook, and an agent's
connection cannot env.reveal it. AgentOS hands it out only for a direct
command running that skill's own entry point (one command; no pipe, redirect,
substitution or VAR= prefix), and runs its own packaged copy of the script —
or the pinned gmgn-cli@1.7.1 — without a shell.
When that command moves funds — lp_write.py/pools_write.py --broadcast,
ratchet.py arm --confirm or clear-attention, gmgn-cli swap,
multi-swap, order strategy create|cancel, cooking create — it waits for
you on an ordinary exec prompt that names the key and, where there is one, the
payout recipient. Unlike every other exec prompt, bypass, /elevated full,
auto-approve, a cached intent and "Stop Asking" on another prompt do not answer
it, and an unattended run (cron) is refused instead of asked. Approve each one
yourself. The unattended ratchet.py tick --broadcast is the exception: it
needs no prompt, but fires only the mandates whose arm you approved, with
the bounds you approved.
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:
| Capability | Meaning | Granted by |
|---|---|---|
| (none) | delete this one path | rm X, os.remove, os.unlink, os.rmdir, Path(X).unlink(), Path(X).rmdir() |
recursive | delete the whole tree below it | rm -r/-R/--recursive, shutil.rmtree(X) |
parents | may also delete empty ancestors | os.removedirs(X) |
force | rm's -f/--force | rm -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:
| Namespace | What it is | Approve means | Deny / timeout means |
|---|---|---|---|
acp | The 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_elicitation | The 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_mode | Behaviour |
|---|---|
ask (default) | Every prompt waits in the approval queue for up to [acp].approval_timeout_s (default 900 s); no answer rejects it. |
approve-reads | Reads, searches, fetches and thinking are allowed without asking; anything else is asked as above. |
approve-all | Everything is allowed without asking. |
deny-all | Everything 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 log): it never changes the session's elevated mode and is
forgotten when the harness session closes. Interpreters, shells, package
runners (npx, uvx, uv run), make, docker, curl, rm-style
programs and git push/reset/clean/checkout/restore are never
remembered and always ask (ACP agents). 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; params.display: true
answers exactly as GET /api/approvals does), and exec.approval.resolve
(or POST /api/approvals/resolve) accepts an optional payload object for
form answers.
A prompt always shows the call that will actually run. When a tool hook rewrote the call's arguments (see "Tool and request hooks" in Tools and Sandbox), the prompt and the pending result on the tool card show the rewritten command; the model is told only which of its arguments were adjusted.
Where a prompt reaches you
Every pending approval is listed in the web console (the approval tray on every page, the Inbox and Settings › Approvals) and in the desktop app's approval dialog. Beyond that:
- Web Push. In the web console, Settings › Notifications › 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 that opens it in the console's Inbox; 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 announcesapproval.resolvedto 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). Theapproval.requestedevent andGET /api/approvalscarry 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
Recommended Defaults
| Situation | Recommended 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 writes | Keep approvals visible and review sensitive actions |
| Channel-connected agent | Conservative permissions and explicit channel setup |
| Unattended automation | Bound 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: