Exec approvals are the companion app / node host guardrail for letting a sandboxed agent run commands on a real host (gateway or node). Commands run only when policy + allowlist + (optional) user approval all agree. Approvals stack on top of tool policy and elevated gating. Gateway full-session and qualifying elevated-full paths can skip host approval evaluation. See the strict inline-eval exceptions.

For a mode-first overview of deny, allowlist, ask, auto, full, Codex Guardian mapping, and ACPX harness permissions, see Permission modes.

Where it applies

Exec approvals are enforced locally on the execution host:

• Gateway host -> apus process on the gateway machine.
• Node host -> node runner (macOS companion app or headless node host).

The claude-cli backend also checks native Bash commands against the agent's exec allowlist when ask: "on-miss". This authorizes command arguments while Claude Code owns execution. It does not provide Apus sandboxing. See Native Bash and the exec allowlist for matching, prompting, and binding restrictions.

Trust model

• Gateway-authenticated callers are trusted operators for that Gateway.
• Paired nodes extend that trusted operator capability onto the node host.
• Approvals reduce accidental execution risk, but are not a per-user auth boundary or filesystem read-only policy.
• Once approved, a command can mutate files according to the selected host or sandbox filesystem permissions.
• Approved node-host runs bind canonical execution context: cwd, exact argv, env binding when present, and pinned executable path when applicable.
• Gateway approval-backed commands bind every resolved command-segment executable before review and re-check it before launch. Node hosts capture these identities during local policy evaluation and re-check before dispatch. This does not cover inner shell executables across a remote human approval wait. Protected executables use resolved real-path identity only. Writable executables also use a content hash. A changed resolution during the bound window, including a new executable earlier on PATH, denies the run. Identity-only binding preserves otherwise eligible allow-always decisions. See Interpreter/runtime commands.
• For shell scripts and direct interpreter/runtime file invocations, Apus also tries to bind one concrete local file operand. If that file changes after approval but before execution, the run is denied instead of executing drifted content.
• File binding is best-effort, not a complete model of every interpreter/runtime loader path. If exactly one concrete local file cannot be identified, Apus refuses to mint an approval-backed run rather than pretend full coverage.

macOS split

• The node host service forwards system.run to the macOS app over local IPC.
• The macOS app enforces approvals and executes the command in UI context.

Inspecting the effective policy

Tool availability and command approvals are separate: a messaging tool profile can exclude exec and process even when approvals permit commands. exec-policy show explains local exclusions offline and identifies the policy source. --session <key> previews tools from saved session settings. Inclusion does not guarantee execution, and absence does not prove a tool is disabled. Verify execution in a run; command approvals still apply. Use --agent <id> to select an agent and --verbose for all approval scopes.

Full CLI reference (flags, JSON output, allowlist add/remove): Approvals CLI.

When a local scope requests host=node, exec-policy show reports that scope as node-managed at runtime instead of treating the local approvals file as the source of truth.

If the companion app UI is not available, any request that would normally prompt is resolved by the ask fallback (default: deny).

For native chat approval surfaces, a node exec waits for the decision within the originating tool call and returns the command output there. Closing or cancelling that turn invalidates its pending authority. A late approval cannot restart it. A typed SYSTEM_RUN_DENIED result means the node rejected execution, not that the command may have run.

Settings and storage

Approvals live in the shared SQLite state database on the execution host. When APUS_STATE_DIR is set, the database follows that state directory. Otherwise it uses the default Apus state directory:

$APUS_STATE_DIR/state/apus.sqlite#exec_approvals_config
# otherwise
~/.apus/state/apus.sqlite#exec_approvals_config

The #exec_approvals_config suffix is a display locator for the singleton SQLite row, not part of the database filename. The row keeps the JSON document shown below as its authoritative value, so CLI and Gateway compare-and-swap hashes remain stable.

The default approval socket follows the same root: $APUS_STATE_DIR/exec-approvals.sock, or ~/.apus/exec-approvals.sock when the variable is unset.

State directories are independent trust scopes. When APUS_STATE_DIR points somewhere else, Apus never imports or archives approvals from the default state directory. Configure approvals separately for the custom state directory. If the active state directory still contains a legacy exec-approvals.json, stop the Gateway and run apus doctor --fix once to import it. Doctor also imports legacy plugin-binding-approvals.json only when it belongs to the active state directory.

Legacy allowlist entries may contain null for lastUsedAt or lastUsedCommand. Doctor treats those two usage fields as absent during import, including when the config still needs repair. This does not relax canonical policy validation: other malformed fields or conflicting legacy policies remain preserved for operator recovery, and exec approvals stay blocked until the legacy file is resolved. After repair, verify with apus approvals get using the same state directory.

Example schema:

{
  "version": 1,
  "socket": {
    "path": "~/.apus/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/path/to/**/bin/rg",
          "argPattern": "sha256:argv:...",
          "source": "allow-always",
          "lastUsedAt": 1737150000000,
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        },
        {
          "pattern": "~/path/to/**/bin/git"
        }
      ],
      "mcpTools": [
        {
          "server": "project-docs",
          "tool": "publish_page",
          "source": "allow-always",
          "addedAt": 1737150000000
        }
      ]
    }
  }
}

Policy knobs

tools.exec.mode

tools.exec.mode is the preferred normalized policy surface for host exec:

Doctor migrates supported legacy tools.exec.security / tools.exec.ask pairs to tools.exec.mode. If a deploy script, template, or config generator still sends the old fields, config patch and Gateway config.patch reject the mixed policy without changing the file. Update that source in the same exec object named by the error, including agents.entries.<agentId>.tools.exec for an agent override. Replace security / ask with the suggested mode value when an exact equivalent exists. For example, security: "full", ask: "off" becomes mode: "full".

An incomplete pair needs an explicit choice of the intended policy before conversion. Pairs with ask: "always", or security: "full", ask: "on-miss", have no exact mode equivalent: retain both legacy fields and remove mode from that same object to keep their policy. Preserve other exec settings when replacing an object. Run apus doctor --fix for a saved file that still needs migration. Running it again does not update a stale deployment source.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Examples that strict mode catches: python -c, node -e/--eval/-p, ruby -e, perl -e/-E, php -r, lua -e, osascript -e (also awk, sed, make, find -exec, and xargs inline forms).

On that approval path, these commands need reviewer or explicit approval. With tools.exec.mode: "auto", eligible commands receive an allow, deny, or ask verdict. The reviewer may grant one low- or medium-risk execution, return a denial reason to the agent, or ask a human. Gateway commands must pass mutable-file binding checks, but do not need a rendered command with pinned paths to receive review. POSIX login or interactive shell wrappers skip the reviewer and require human approval when binding succeeds because their implicit startup files are outside operand binding. Existing binding rejections, including interactive code-loading forms, remain denied. See Exec modes for binding limits and escalation. Codex app-server command approvals that reach the reviewer fallback ask a human because their approval requests do not expose an enforceable resolved executable. allow-always does not persist new allowlist entries for inline-eval commands.

Configured tools.exec.mode: "full" alone does not bypass this setting. On the Gateway, a full-permission session with effective security full and ask off skips host approval evaluation. Permitted elevated-full execution also skips it when both exec and host approval policies allow full/off. Those paths skip strict inline-eval detection. Ask-only tightening of a full session restores the approval path while retaining its host-file-floor exception. See Inline eval.

tools.exec.commandHighlighting

Set globally under tools.exec.commandHighlighting or per agent under agents.entries.*.tools.exec.commandHighlighting.

YOLO mode (no-approval)

To run host exec without approval prompts, open both policy layers: requested exec policy in Apus config (tools.exec.*) and host-local approvals policy in the execution host approvals document.

For ordinary configured full-mode execution of recognized inline-eval forms without prompts, leave tools.exec.strictInlineEval unset or set it to false (the default). If detection runs with strict mode enabled, askFallback: "full" does not replace reviewer or explicit approval. The Gateway session and elevated exceptions described above skip that detection.

Omitted askFallback defaults to deny. Set host askFallback to full explicitly when a no-UI approval prompt should fall back to allow.

For Apus-managed Claude sessions, Apus launches Claude Code in its default permission mode. Apus's effective exec policy remains authoritative through native tool hooks and permission requests, including YOLO and restrictive policies, even if raw Claude backend args request bypassPermissions.

If you want a more conservative setup, tighten Apus exec policy back to allowlist / on-miss or deny.

Persistent gateway-host "never prompt" setup

```bash
apus config set tools.exec.host gateway
apus config set tools.exec.mode full
apus config set tools.exec.strictInlineEval false
apus gateway restart
```

```bash
apus approvals set --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF
```

Local shortcut

apus exec-policy preset yolo

Updates both local tools.exec.host/security/ask and the local approvals file defaults (including askFallback: "full"). It is intentionally local-only and requires exclusive offline ownership of the selected state. Stop a running Gateway through its service owner before using exec-policy set or preset; these commands refuse before changing policy while another live Gateway owns the state. To change gateway-host or node-host approvals remotely, use apus approvals set --gateway or apus approvals set --node <id|name|ip>.

A Gateway policy change that withdraws permission may be refused while a cron command is starting. Retry after command startup settles; the refusal leaves the previous policy in place.

Other built-in presets: cautious (host=gateway, security=allowlist, ask=on-miss, askFallback=deny) and deny-all (host=gateway, security=deny, ask=off, askFallback=deny). Apply the same way: apus exec-policy preset cautious.

To set individual fields instead of a full preset, use apus exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full> with any subset of those flags.

Node host

Apply the same approvals document on the node instead:

apus approvals set --node <id|name|ip> --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

Session and turn shortcuts

• /exec security=full ask=off <task> requests that policy for the current message only. Include the task in the same message. A standalone directive does not affect the next message. Session permission modes and host policy can still restrict the request.
• /elevated full is a break-glass shortcut that skips exec approvals only when both the requested policy and the host approvals document resolve to security: "full" and ask: "off". A stricter host file, such as ask: "always", still prompts.

Outside the full-permission Gateway session exception, if the host approvals document stays stricter than config, the stricter host policy still wins.

Allowlist (per agent)

Allowlists are per agent. If multiple agents exist, switch which agent you are editing in the macOS app. Patterns are glob matches.

Patterns can be resolved binary path globs or bare command-name globs. Bare names match only commands invoked through PATH, so rg can match /opt/homebrew/bin/rg when the command is rg, but not ./rg or /tmp/rg. Use a path glob to trust one specific binary location.

Saved policies that still use the legacy agents.default key or commandText fields are not converted on load. Apus refuses them until apus doctor --fix moves agents.default to agents.main and drops commandText; apus update runs the same Doctor pass. Plugin and operator APIs still accept the legacy shape as input and normalize it before saving. See Exec approval policy. Shell chains such as echo ok && pwd still need every top-level segment to satisfy allowlist rules.

Examples:

• rg
• ~/path/to/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Restricting arguments with argPattern

Add argPattern when an allowlist entry should match a binary and a specific argument shape. Apus uses ECMAScript (JavaScript) regular expression semantics on every host and evaluates the expression against the parsed command arguments, excluding the executable token (argv[0]). For hand-authored entries, arguments are joined with a single space, so anchor the pattern when you need an exact match.

{
  "version": 1,
  "agents": {
    "main": {
      "allowlist": [
        {
          "pattern": "python3",
          "argPattern": "^safe\\.py$"
        }
      ]
    }
  }
}

That entry allows python3 safe.py. python3 other.py is an allowlist miss. If a path-only entry for the same binary is also present, unmatched arguments can still fall back to that path-only entry. Omit the path-only entry when the goal is to restrict the binary to the declared arguments.

Entries saved by approval flows use an internal separator format for exact argv matching. Prefer the UI or approval flow to regenerate those entries instead of hand-editing the encoded value. If Apus cannot parse argv for a command segment, entries with argPattern do not match.

Generated allow-always entries are bound to both the exact argv and the working directory where you approved them. Choosing Always allow here authorizes the same command only in that directory. Running it elsewhere is an allowlist miss.

Generated entries saved before 2026.8.1 are not directory-bound and are inactive after upgrading. apus update removes them during its automatic Doctor pass, or you can run apus doctor --fix yourself. Rerun an affected workflow and choose Always allow here to create the replacement. Manual allowlist rules are not changed. For a manual path-only rule, omit both source and argPattern.

Each allowlist entry supports:

MCP tool grants

For Gateway-hosted Codex runs, Allow Always can save a durable grant for one MCP tool on a server configured in mcp.servers. The Gateway writes the grant to agents.<agentId>.mcpTools in this same approvals document. It covers the exact agent, configured server name, and tool name, with any arguments. It does not grant access to other agents, servers, or tools.

Each entry has server, tool, source: "allow-always", and addedAt (Unix milliseconds). lastUsedAt is optional. Codex apps, native plugin servers, and computer-use servers do not receive Apus MCP tool grants. Apus only mints when durable persistence is offered and it can unambiguously match the approval to a live Gateway-owned tool call. Missing or ambiguous correlation retains Codex's existing native/session behavior instead.

Grants apply when the server's codex.defaultToolsApprovalMode is auto or unspecified. Explicit prompt wins over a stored grant and keeps asking. Explicit approve already bypasses per-call approval. See Codex tool approvals.

The durable grant is read when Apus next prepares the Codex thread configuration and hook registration, such as for a new session or after a restart. The current session continues using Codex's remembered decision. Apus does not reload grants for every tool call.

To inspect grants, run apus approvals get --gateway. To revoke one, export the document, remove its entry from agents.<agentId>.mcpTools, and replace the document with the existing set command:

apus approvals get --gateway --json | jq '.file' > approvals.json
# Edit approvals.json, preserving other settings, allowlists, and grants.
apus approvals set --gateway --file approvals.json

Omit --gateway from both commands to edit local approvals. Revocation takes effect at the next thread preparation/registration too. Start a new session or restart to discard the active session's remembered approval. If Codex also persisted a separate approval in its native config, remove that native grant there as well.

Standing grants for automations

Approvals raised by gateway-host automation (cron) runs are delivered only to connected exec approval clients: the Control UI, the macOS/iOS/Android apps, and API clients that declare the approvals or exec-approvals capability. The TUI does not render exec approval cards, and chat channels never receive automation approvals, which would repeat a card on every occurrence. While a reviewer surface is connected, the scheduled run waits for the decision like an interactive run. Automations are single-flight, so at most one card per job is pending at a time. With no approval surface connected, the request is denied immediately and the run's error explains the policy fix. Node-host automation execs keep the fully headless policy (no cards) until node execution gains its own standing-grant path.

When an approval originates from an automation's isolated run, resolving it with Always allow does not write a JSON allowlist entry. Instead the Gateway mints a scoped standing grant bound to that exact agent, automation, job configuration, and operation (command text, working directory, and requested environment). Later occurrences of the same job execute that exact operation without prompting while the grant is valid. The approval card says so up front: automation approvals carry a scope line describing exactly what Always allow will mint.

What a grant covers, and when it stops

A grant fails closed back to a normal prompt when the job is deleted or its substantive definition changes, even if a later edit restores the earlier definition. Pausing and re-enabling the unchanged automation preserves the grant. The grant also stops matching when the command, working directory, or environment differs by even one byte, when it is revoked or expired, or when the original approval record is gone. The check runs immediately before the process spawns, so a revocation or job edit that lands mid-flight still wins. Mutable file operands and commands that require explicit review (heredocs, strict inline eval, audit suppression) keep prompting per occurrence. Non-automation approvals are unchanged.

Grant lifetime

By default a grant lives until revoked — the same meaning Always allow has everywhere else in the product. Terms freeze at mint time and never change retroactively:

• tools.exec.grantExpiryDays (unset by default) sets the default lifetime, in days, for future grants. Existing grants keep the terms they were minted with. Use revocation to retire them early. This is the fleet-policy knob for managed deployments that require periodic re-approval.
• A resolving surface may override the default per grant with the grantExpiresInDays field on approval.resolve / exec.approval.resolve, or apus approvals resolve <id> allow-always --expires-in-days <n>. The override wins over the config default.
• Expired grants fall back to prompting and are pruned opportunistically.

Listing and revoking

Every standing grant is visible and revocable:

• Control UI: Settings → Approvals shows the standing-grant ledger — automation, exact command, use count, and state (until revoked, expires in N days, expired, revoked) — with a Revoke action per active row.
• CLI: apus approvals grants list renders the same ledger. apus approvals grants revoke <grant-id> revokes one grant. Revocation is idempotent and takes effect at the next occurrence's spawn boundary — that occurrence prompts again.
• Deleting or substantively editing the automation, or reversing the minting approval, also invalidates the grant without touching the grants surface. Pausing and re-enabling the unchanged automation does not.

The minting operator_approvals row remains the sole authorization owner: a grant is derivative correlation, revalidated against the live approval row, automation row, and revocation state on every use.

Auto-allow skill CLIs

When Auto-allow skill CLIs (autoAllowSkills) is enabled, executables referenced by known skills are treated as allowlisted on nodes (macOS node or headless node host). This uses skills.bins over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists.

Skill trust belongs to the Gateway that supplied it. Switching Gateways retires the previous cache, including the Mac app's trusted-binary list and an approval check that is still in progress. A failed refresh can keep the last known trust from the same Gateway. It cannot import another Gateway's trust.

The Mac's Exec Approvals pane refreshes its trusted binaries and agent choices when the selected Gateway connects. Local policy, the selected scope, and unfinished allowlist edits stay on the Mac.

Safe bins and approval forwarding

For safe bins (the stdin-only fast-path), interpreter binding details, and how to forward approval prompts to Slack/Discord/Telegram (or run them as native approval clients), see Exec approvals - advanced.

Control UI editing

Use the Control UI -> Nodes -> Exec approvals card to edit defaults, per-agent overrides, and allowlists. Pick a scope (Defaults or an agent), tweak the policy, add/remove allowlist patterns, then Save. The UI shows last-used metadata per pattern so you can keep the list tidy.

The target selector chooses Gateway (local approvals) or a Node. Nodes must advertise system.execApprovals.get/set (macOS app or headless node host). If a node does not advertise exec approvals yet, edit its local approvals document directly.

Some node hosts, including the Windows companion, own a different approval policy format. Control UI shows these host-native policies read-only. Use the companion app or apus approvals set --node <id|name|ip> with the native policy shape to edit them. See Approvals CLI.

CLI: apus approvals supports gateway or node editing - see Approvals CLI.

Approval flow

When a prompt is required, the gateway broadcasts exec.approval.requested to operator clients. The Control UI and macOS app resolve it via exec.approval.resolve, then the gateway forwards the approved request to the node host.

An approval accepted before its prompt deadline remains valid during the Gateway's live handoff window. Crossing the prompt deadline during dispatch does not undo that decision. Closed runs, expired handoff windows, and reused Allow Once approvals still reject execution.

The macOS approval panel keeps ordinary commands compact, with the supplied agent and host in one summary. It shows the working directory beneath the full, wrapping command. Longer commands scroll. Expand Details to inspect the executable path. Directory and executable paths remain fully selectable. Copy copies the displayed command, including visible escapes for control and invisible characters. The host comes from the request. A gateway or node can be remote from the Mac displaying the panel.

Choose Allow Once or press Command-Return to approve one execution. Return alone does not approve. Escape dismisses the panel, denying the request when Don't Allow is available. Otherwise it closes without a decision. Always Allow Here appears only when the request's policy permits durable approval.

For host=node, approval requests include a canonical systemRunPlan payload. The gateway uses that plan as the authoritative command/cwd/session context when forwarding approved system.run requests:

• The node exec path prepares one canonical plan up front.
• The approval record stores that plan and its binding metadata.
• Once approved, the final forwarded system.run call reuses the stored plan instead of trusting later caller edits.
• Edits to command, rawCommand, cwd, agentId, or sessionKey after the approval request was created are discarded: the gateway forwards the stored values instead. Changed env overrides are still rejected as an approval mismatch.

Approval scope summaries

An approval owner can attach a typed, display-only scope describing the action's blast radius. Apus renders the sanitized summary on channel approval cards and includes the bounded scope in the safe approval presentation available to Control UI clients. Standalone approval links display the supplied scope before the decision buttons, including automation grant terms. Scope never grants authorization or changes approval policy.

• message-send: destination, recipient count, optional recipient preview, and whether the audience is internal or external.
• payment: exact decimal amount, currency, and payee or payment system.
• external-post: destination and whether the post is public or restricted.

For example, an email approval might show Send to 3 recipients via email (external): alice@example.com, bob@example.com, +1 more. Owners supply these facts. Channels never infer them from commands or message text. Without a declared scope, approval cards render exactly as before.

System events and denials

When an approval can be delivered, ordinary agent runs wait for the decision and receive the exec result in the same turn. The final reply uses the original delivery path, including an inbound A2A task. An operator denial returns a denied tool result without running the command.

Diagnostic and export commands that explicitly use asynchronous execution retain their separate follow-up delivery. For those workflows:

Exec lifecycle posts an Exec finished system message to the agent's session after the node reports completion. Apus can also emit an in-progress notice once an approval is granted, after tools.exec.approvalRunningNoticeMs elapses (default 10000, 0 disables it). Denied exec approvals are terminal for the host command: the command does not run.

• For main-agent async approvals with an originating session, Apus posts the denial back into that session as an internal followup so the agent can stop waiting on the async command and avoid a missing-result repair.
• If there is no session or the session cannot be resumed, Apus can still report a concise denial to the operator or direct chat route.
• Denials for subagent and cron sessions are not posted back into that session.

Gateway-host exec approvals emit the same completion lifecycle event. Approval-gated execs reuse the approval id to correlate the pending request with its completion/denial message (Exec finished (gateway id=...) / Exec denied (gateway id=...)).

Implications

• full is powerful. Prefer allowlists when possible.
• ask keeps you in the loop while still allowing fast approvals.
• Per-agent allowlists prevent one agent's approvals from leaking into others.
• Approvals only apply to host exec requests from authorized senders. Unauthorized senders cannot issue /exec.
• /exec security=full <task> is a current-turn request by an authorized operator, subject to effective session and host policy. To hard-block exec, deny the exec tool via tool policy. See session overrides for the full-access session exception to host approval floors.

Related

Safe bins, interpreter binding, and approval forwarding to chat.

Shell command execution tool.

Break-glass path that also skips approvals.

Sandbox modes and workspace access.

Security model and hardening.

When to reach for each control.

Skill-backed auto-allow behavior.