Permissions and security

Two controls affect a tool call: the approval mode decides when Orek asks you first, and permission rules restrict what can run at all. The opt-in OS sandbox adds containment for shell commands. A tool runs only after these checks pass.

Open /doctor in Orek (or run orek doctor) to see the active settings. Review the action and any file diff in approval prompts before confirming, and use /setup provider or orek providers setup to enter credentials rather than pasting keys into chat.

In the TUI, switch the session’s approval mode with /permissions (or press Alt+Y for yolo):

/permissions auto_review

When an action asks for approval, review the preview, use Tab or the arrow keys to highlight a choice, and press Enter to confirm (Esc denies). Approval prompts in the TUI, orek run, and editor sessions name the agent asking.

The approval mode, Plan mode, the execution policy, and the OS sandbox apply to the whole session, including running subagents and workflow steps. Switching to yolo also approves any requests already waiting (except while drafting a plan in /plan). See the interface tour.

Approval modes

Set exec.default_approval_mode in your user configuration file, or pass --approval-mode <mode>. You cannot change this key with orek config set; edit the file and restart Orek. A project’s .orek/config.toml cannot set it; see Project files can only tighten.

/plan turns Plan mode on and off without changing your approval mode, and choosing plan as the approval mode starts Orek in Plan mode. Changing the approval mode while planning never lifts Plan mode’s read-only limits; it sets the mode the approved plan runs under. Plan mode still lets the memory tool save facts outside the workspace, and it blocks checklist changes. See Plan mode.

Always-ask tool groups

To require approval for a group of tools in every mode except yolo, list the group in exec.require_approval_for. The list is empty by default.

For example, orek config set exec.require_approval_for file_write makes auto_review ask before every file edit. These groups override the built-in allow behavior of default and auto_review. Your own permission rules, Always allow choices, and yolo mode override the groups.

Approve or deny actions

Approval prompts show the command, file path, or URL. You can allow the action once, allow it for the session, save an Always allow rule, or edit the request before approving. When you deny an action, Orek tells the model to change its approach or ask you rather than retry the same call. A tool call the model formats incorrectly returns an error to the model without prompting you or running anything.

In orek run, default and auto_review prompt on an interactive terminal. When input is not a terminal, a run that needs approval fails immediately.

Experimental: execution policy

The experimental exec.default_sandbox key controls whether approved actions actually run:

• approved (default): runs permitted actions normally, with no status-bar chip.
• dry_run: blocks execution and returns a preview from tools that support one; shows [DRY-RUN] in the status bar.
• simulation: describes each action without running it; shows [SIMULATION] in the status bar.

Both dry_run and simulation stop file edits, shell commands, and local web fetches. Reads and model requests still run, so neither mode works offline. The model is not told about these modes and may retry edits that did not apply. Set them only through configuration, for example /config set exec.default_sandbox dry_run.

Permission rules

Add rules to your user configuration; a project’s .orek/config.toml cannot set them. This example denies write_file and confines the listed tools to the src folder:

[[permissions.tool_rules]]
tool_name = "write_file"
decision = "deny"
deny_message = "File writes are disabled."

[[permissions.path_scopes]]
tools = ["write_file", "apply_patch", "search_replace", "git_inspect"]
root = "src"

A deny always wins over an approval. An allow rule can remove the usual prompt, but path, sensitive-file, and URL checks still apply. Run orek doctor to see the loaded rules.

Shell commands and run_python

Orek splits POSIX and PowerShell scripts into separate commands and applies the strictest matching rule. Syntax Orek cannot check, such as command substitutions, redirects, or an unquoted POSIX (, asks for approval. An allow rule for all of shell skips this per-command check, so prefer narrow command rules when you want each part of a compound script checked.

Under bash, zsh, or another POSIX shell, a narrow command rule does not cover a command with an unquoted (: a subshell, an array assignment, a function definition, or zsh code such as ls *(e:'...':) or cat =(...). Such a command asks instead.

When your configured shell is fish or another shell that is neither POSIX nor PowerShell (such as csh, tcsh, nu, elvish, or xonsh), Orek cannot read its syntax, so no allow rule removes the prompt for its commands outside yolo. The same applies under any shell to a command that names one of those shells, such as fish -c ..., env nu -c ..., or ... | fish.

run_python runs arbitrary Python, so denying the whole shell also denies and hides it. That means a permissions.tool_rules entry, or a policy rule for shell, bash, or powershell without commandPrefix. Shell allow rules and command-prefix rules do not apply to its script. Its input_command is checked like a shell command, and its cwd follows shell path limits. See Controls Orek enforces itself.

OS sandbox

/sandbox controls exec.sandbox_runtime_enabled. On every platform, the sandbox passes shell commands only an allowed set of environment variables, which leaves out provider API keys; on macOS it also confines commands with Seatbelt, the built-in macOS sandbox. The sandbox is off by default. While it is off, shell and background commands receive Orek’s full environment, including provider API keys, and on macOS can reach files outside the workspace such as ~/.ssh. When it is on, the status bar shows [sandbox].

Every agent in the session, including subagents and workflow steps, shares the session’s sandbox setting. An editor session reads the saved setting when it starts. Language servers always run with a filtered environment; see Language-server containment.

Several tool calls at once

When a model asks for several tool calls in one response, Orek runs them at the same time, up to agent.max_parallel_tool_calls (8 by default), and returns the results in the order the model wrote them:

• Approvals and questions: shown one at a time in the TUI and in orek run. A mode change applies to calls that have not started yet.
• Denials: denying a call, or a deny rule, skips the calls after it in the same response that have not started. Calls already running finish unless you stop the turn.
• One at a time: a model with supports_parallel_tools = false (see Add your own model) or agent.max_parallel_tool_calls = 1 runs tool calls one at a time.

Containment and platform limits

These controls do not prevent prompt injection, make a malicious installed tool safe, or limit CPU and memory use. Output limits cap text, not resources. When you need a stronger boundary, run Orek in a container or VM.

Controls Orek enforces itself

The execution policy, approval decisions, tool and path rules, sensitive-file checks, webfetch URL checks, output limits, and secret redaction are enforced by Orek itself, not by the operating system.

OS containment by platform

Windows and Linux have no operating-system limits on what commands can access.

With the sandbox on, macOS commands can reach the project, temporary and system folders, and common developer-tool and cache folders. Grant more with permissions.sandbox_read_paths and permissions.sandbox_write_paths; these can be outside the project.

Language-server containment

Language-server diagnostics are off by default (lsp.enabled = false). Enabling them does not let a server start: each project needs your consent with /lsp trust, saved in lsp-consent.json outside the repository. Changing the server’s configuration, its executable, the project folder, or (on macOS) the sandbox setting requires consent again.

A trusted language server can run project code, such as build scripts and macros, and write build or cache files. Orek refuses edits a server asks to make, but the server process can still write to disk.

Language servers always run with a filtered environment, plus Seatbelt when the OS sandbox is on. Toggling /sandbox on macOS restarts running servers; if you have not yet trusted the server under the new setting, run /lsp trust again.

LSP process cleanup

When Orek stops a language server, it asks the server to exit, waits up to two seconds, then force-stops it and its child processes. On Linux, a child process that detaches from the server can keep running.

Diagnostics for files outside the project or matching sensitive patterns are hidden from the model. A server that is unavailable, untrusted, timed out, or crashed is never reported as finding no problems. See Language servers.

Project files can only tighten

A project’s files arrive with the repository, so they can make Orek ask more, never less:

<user-config> is the folder that holds your user config.toml; see File locations.

URL allowlist

Orek checks local webfetch URLs against permissions.url_allowlist:

[permissions]
url_allowlist = [
  "https://api.github.com",
  "https://docs.rs",
]

Redirects are checked before each request. An empty list blocks local webfetch requests and, with the OS sandbox on macOS, also blocks network access for shell and background commands. Otherwise, this setting does not limit network use inside a shell and does not affect model providers or MCP connections.

For provider web tools:

• Allowlist conflict: Orek cannot enforce permissions.url_allowlist inside a provider’s own search or fetch service, so setting url_allowlist turns provider web tools off with an error that explains why. Orek has no local web search to fall back on.
• Permission rules: websearch and webfetch rules govern the matching provider tools on OpenAI, Anthropic, and Google. OpenAI’s web search checks both, because it can search and open pages.
• Prompts and modes: an ask approval covers that provider, model, and tool for the current turn. Provider web tools can run in Plan mode when your rules allow, and are refused in dry_run and simulation.

Sensitive paths

permissions.sensitive_patterns holds regular expressions, not globs. Tool calls on matching paths require approval in default and auto_review (and are approved without asking in yolo). Matching files named in @ references are left out, because a reference cannot ask for approval.

For example, add a rule for a project’s private credentials folder:

[permissions]
sensitive_patterns = ['(^|/)private-credentials(/|$)']

Your patterns are added to the built-in ones, which cover .env files, common private-key formats, and package-manager credentials. Paths use / as the separator, and matching ignores case on every platform for tools, indexing, and language servers. An invalid regular expression is a configuration error. Use a deny rule when an action must be refused even after approval.

Credentials at rest

Output handling and redaction

Shell output is limited before it reaches the model. These are the defaults:

[exec]
truncation_policy = "bytes"
truncation_limit = 65536
max_allowed_limit = 262144
retain_truncated_output = true
retained_output_max_bytes = 1048576
retained_output_session_max_bytes = 16777216
redact_exec_output = true
max_background_jobs = 64

The model sees up to 64 KiB of output per result and can ask for up to 256 KiB on one command. Orek keeps up to 1 MiB of each truncated result, and 16 MiB per session, so the model can read more with read_exec_output. Redaction is on by default, including for those reads, but finds only recognized secret formats. A truncation_policy of "tokens" is read as "bytes".

Redaction coverage by surface

Pattern matching can miss custom secrets. Keep credentials out of prompts and source files, and check where external requests go and what they send.

Trust boundaries

Agent isolation

Orek does not isolate agents from each other. Subagents, including workflow steps, work in the session’s project folder with the session’s tools, approval mode, and permission rules, so agents editing in parallel need separate files. A profile’s tool list keeps an agent focused; it is not a security boundary. Any agent can message any other agent and stop or resume any subagent. All agents run as the same OS user on the same machine and network.

Run Orek in a container or VM when all its agents need stronger isolation. See Subagents and Workflows.

Prompt injection and untrusted content

Files, web pages, and tool results can contain instructions meant to redirect the model. No setting fully prevents this, and telling a model to ignore such instructions does not enforce anything.

Deny rules, sensitive-path checks, reviewing prompted actions, and the macOS sandbox can limit the damage. Approval helps only when a prompt actually appears and you read it. Redaction reduces secret exposure but cannot guarantee privacy. An allowed network host can still receive whatever is sent to it.

Recommended starting settings

See also

• Execution configuration
• Agent tools
• Language servers
• Provider setup