Configuration

Use this page to look up saved settings. For onboarding, use Quickstart. In Orek, locate files and inspect a specific value:

/config path

/config get ui.theme

/config and /config show list the keys you can set. In a shell, orek config show prints the combined configuration from Orek’s defaults and your files, with secrets hidden.

File locations

Use your user configuration for personal defaults and your project configuration for settings that belong with a repository. You only need to write values you want to change.

OREK_HOME relocates user-scoped configuration, cache, roaming data, and local data under config/, cache/, data/, and data-local/ beneath that root. Without it, macOS uses Apple’s Application Support/Caches paths rather than XDG.

Person-owned state is not configuration and never lives in the checkout: per-project workspace-root defaults saved with /add-dir <PATH> persist live at <user config>/workspace-roots/<project-hash>.toml. A repository cannot grant itself extra workspace roots by carrying a file; see TUI commands.

Before you begin

Open a terminal in your project directory and find the files Orek uses there:

orek config path

The output identifies your user file and the project’s .orek/config.toml, including whether each file exists. Orek searches upward for the nearest .orek directory; to give a nested project its own scope, create a .orek directory in that project’s root and check orek config path again.

Resolved view

1. Read the current value

orek config get ui.theme

This reads the combined value, including project overrides. To inspect all loaded settings with credentials redacted:

orek config show

Redaction covers provider credentials, gateway/cloud tokens, MCP environment and header values, and inline user:password@ URL credentials. Inside Orek, use /config get <key>; for example:

/config get index.retrieval.enabled

get reads any setting. set and unset accept the keys that the tables below mark User or Project; edit TOML settings in the file.

2. Save a personal default

This example saves a light terminal theme in your user configuration:

orek config set ui.theme light --scope user

The confirmation names the file that changed. Include --scope when the destination matters; without it, Orek chooses a default scope for that key.

3. Override it for this project

orek config set ui.theme dark --scope project

Check the value again from the same project:

orek config get ui.theme

The result is dark. The user file still says light; the project value takes precedence here. Restart any running Orek session to load external changes.

4. Remove an override

To use your personal default in this project again:

orek config unset ui.theme --scope project

Unsetting a value removes it from the selected file; it does not remove the default or a value in another file. orek config get ui.theme now reports light.

Editing config

For the normal write scope of a supported key, use Orek’s composer:

/config set ui.theme dark

/config set saves the setting and reports whether it applies immediately (such as ui.*, routing.pinned_model, and routing.pinned_provider) or on the next session (such as skills.*, tools.*, and compaction.auto_compact_threshold). Do not append CLI flags to a TUI /config set value; explicit scope overrides use the shell commands above.

Without --scope, each writable key has a default write scope. The reference tables use:

• User: set/unset writes user configuration by default.
• Project: set/unset writes project configuration by default.
• TOML: edit the configuration file; config set cannot change it.

Write scope is separate from precedence. A project value still overrides a user value, including after unset exposes the lower layer again, except for the user-only settings, which a project file cannot set at all. orek config set --scope project refuses them.

Edit structured settings in TOML

Table settings such as [[models]] or [mcp.servers.<name>] are edited directly in config.toml:

1. Run orek config path and open the complete path for the scope you want, preserving spaces, or run orek config init to create a starter .orek/config.toml.
2. Add or update the relevant TOML section.
3. Save the file, run orek config show to verify it parses cleanly, and restart Orek. A documented live reload or slash command may apply specific changes sooner.

For example, this has the same project effect as the theme command above:

[ui]
theme = "dark"

Configuration resolution

Saved settings

Orek reads saved configuration in this order, from lowest to highest priority:

For a single value, the later setting wins, except for the security and approval settings that only your user file can set. Tables combine their entries across scopes, so a project can change one setting while keeping the others from your user file. Removing a project value exposes the user value, or the built-in default if no user value exists.

How lists combine

Most lists replace the entire earlier list. A few lists add their entries:

An empty replacement list clears the earlier list; an empty additive list does not remove earlier entries.

Settings a project cannot change

A project’s .orek/config.toml can tighten approval but never loosen it. The file comes with the checkout, and in auto_review the model can write it without asking, so Orek ignores these keys in it and uses your user value or the built-in default:

• exec.default_approval_mode, exec.require_approval_for, every exec.auto_review key, exec.redact_exec_output and exec.sandbox_runtime_enabled;
• permissions.tool_rules, permissions.mcp_server_rules, permissions.path_scopes, permissions.url_allowlist, permissions.env_allowlist, permissions.sandbox_read_paths and permissions.sandbox_write_paths;
• tools.shell.default_shell and index.llama_server_path, which name programs Orek runs;
• index.models_dir, index.llama_server_device, index.llama_server_gpu_layers and index.llama_server_idle_timeout_secs, which choose the local model files, the hardware they run on, and how long they stay loaded;
• every ui.keymap key, because remapped approval keys could turn a checkout’s file into a way to approve for you.

Each ignored key is logged, and orek doctor lists it under Ignored project keys, for example: “.orek/config.toml sets exec.default_approval_mode, a user-only setting; project config cannot change it, so it was ignored. Set it in your user config.” Set these in your user configuration instead. A project may still add permissions.sensitive_patterns. Project policy files follow the same rule; see Project files.

Command and session settings

After loading saved settings, supported command-line options such as --model and --approval-mode select values for that invocation.

--reasoning-replay preserve|drop overrides agent.reasoning_replay until that command exits: an orek chat session and every session it switches to or resumes, an orek run, or every session an orek acp server starts. Without the flag, /config set agent.reasoning_replay in chat also changes the open session from its next model switch; with it, the saved value applies the next time you start Orek.

During chat, commands such as /model, /retrieval off, and /sandbox can change the corresponding active setting. These choices are temporary unless the command explicitly saves them. /retrieval clear, for example, removes the temporary choice and restores the configured value; choosing the configured value with /sandbox on|off does the same. orek config show shows saved settings only, not these session choices.

Model catalog

The model catalog is separate from general settings. Orek starts with its built-in model list, then applies user [[models]] entries, followed by project [[models]] entries. Entries can add models or update matching model IDs. Choosing a model with --model or /model selects from that catalog; it does not change the saved model definitions.

Provider credentials

Orek reads providers.<name>.api_key, with a project value taking priority over a user value. That value names exactly one place to get the key from:

Orek uses only that source. It reads an environment variable only when api_key names it, and a missing variable or credential-store entry does not fall back to another source or another configuration file. Use Credential storage to change the source.

Provider setup can detect a known environment variable and save its reference.

Provider addresses and environment references

For ordinary provider connections, Orek uses the merged providers.<name>.base_url value first, expanding any ${NAME} references. If base_url is absent, it uses that provider’s built-in address. Custom OpenAI-compatible connections without an address use http://localhost:8000/v1. Cloudflare AI Gateway instead constructs its address from the configured account, gateway, and route when no usable base_url is supplied.

For example, providers.ollama.base_url = "${OLLAMA_HOST}" selects the address stored in that environment variable. A literal HTTP address can be used instead.

Environment expansion is supported only in specific fields, such as provider addresses and the documented MCP connection fields. MCP also accepts ${NAME:-default}; provider api_key references require the exact ${NAME} form. Environment variables do not override settings in general; only specific ones, such as OREK_HOME and OREK_SANDBOX, have documented effects.

If the change does not take effect

The shape, at a glance

This is a customization example, not the complete default configuration. Put credentials and approval settings in user configuration:

[providers.openai]
api_key = "${OPENAI_API_KEY}"

[ui]
theme = "dark"

[exec]
default_approval_mode = "auto_review"

Project configuration can select a model and other project behavior:

[routing]
pinned_model = "openai/gpt-6-luna"

[index.retrieval]
enabled = false

Only select a model available through your configured provider. Disabling automatic retrieval does not disable explicit references or graph queries.

Setting reference

Tool discovery

Subagents use the same settings, limited by their profile’s tool list. Tool access and approval rules still apply to tools found by search. See tool discovery.

Provider request limits

The limit applies to one provider instance. A streamed response keeps its slot until it completes or is dropped. Unset local kinds (ollama, llama_cpp, lm_studio, vllm) use one slot; cloud providers have no default cap. Custom profile names follow their explicit provider kind. Set a positive integer and restart the session to override the default; unset the key to restore it.

Provider web tools

Provider web tools are web search and page fetching that run on the provider’s servers. They are on by default for every built-in OpenAI, Anthropic and Google model, including one you redefine in [[models]]. Other models, such as a new model ID you add, run without them, and Orek says so once. Change or turn them off for a whole provider (providers.<id>.provider_tools.enabled) or for one model (providers.<id>.provider_tools.models, where [] turns them off for that model and a tool list is accepted only for a built-in model). Restart Orek or start a new session after changing these settings.

orek config set providers.openai.provider_tools.enabled ""
orek config set providers.anthropic.provider_tools.models '"anthropic/claude-haiku-5-5" = ["web_search"]'
orek config set providers.google.provider_tools.models '"google/gemini-3.8-flash" = []'

Setting provider_tools.models changes only the models it names in that scope; unsetting provider_tools.enabled restores the provider’s built-in list. See provider examples.

Anthropic conversations

orek config set providers.anthropic.prefix_mismatch_behavior error
orek config set providers.anthropic.inline_system_messages false

Orek extends a Claude conversation without changing what it sent before. For an endpoint that rejects system messages mid-conversation, a Claude model entry can instead set append_only = false under [models.reasoning.replay]; see Reasoning replay fields and Anthropic Claude.

[providers.<name>]

Connection and authentication settings. The built-in provider names are openai, anthropic, google, mistral, kimi_code, ollama, and cloudflare_ai_gateway. Any other name, such as llamacpp or xai, needs provider_type = "openai_compatible" and its own [[models]] entries; see Providers.

orek config accepts providers.<name>.api_key and providers.<name>.api_key_ref for built-in and custom declared providers. orek providers setup changes connections and model entries without changing your pinned model or provider.

Credential storage

This terminal command writes an environment reference without touching the OS credential store:

orek config set providers.openai.api_key '${OPENAI_API_KEY}'

A literal key given to config set is stored in the OS credential store, and the configuration saves a reference to it, but the key may end up in shell history or process listings. Prefer orek providers setup openai --api-key-stdin or an interactive hidden prompt.

A credential-store reference looks like { managed = "orek-credential:v1:keyring:<opaque-id>" }. Let setup create it. providers.<name>.api_key_ref reads or removes that same entry; it cannot set a new one. A plain unset removes the reference from the configuration; adding --delete-secret also deletes the stored key and confirms it is gone.

Intentional plaintext storage is available through provider setup’s config storage choice or direct TOML editing. If the OS credential store fails, Orek reports an error instead of falling back to plaintext.

Provider cache limits

prompt_caching = false stops Orek sending cache markers, keys, headers and retention settings. It does not turn off caching the provider does on its own, and Orek cannot guarantee a cache hit either way. Generic OpenAI-compatible Chat Completions endpoints get a cache key only when the model’s entry declares one in [models.prompt_cache].

Custom model definitions

A [[models]] entry adds a model to Orek’s catalog. Use one for a model the catalog does not include: a newer model from a built-in provider, a local model, or a model from a service you declare yourself. See Providers for a minimal connection example and Local models for local-server walkthroughs.

Only id, provider, and context_window are required:

• New model ID: capabilities and reasoning default to off, and pricing defaults to unknown.
• Built-in model ID override: inherits display name, aliases, api_model_id, capabilities, [models.reasoning], and [models.prompt_cache] unless you replace them, but you must restate context_window, [models.pricing], and any provider API fields. Only supports_parallel_tools can be set to false on a built-in ID; to turn off other capabilities, use a new id. A [models.reasoning] block replaces the built-in one, except that a block setting only [models.reasoning.replay] keys keeps the built-in control and efforts. Each replay key you leave out keeps its built-in value, whatever else the block sets.

Copy this template and replace each value:

[[models]]
id = "example/coder-large"
provider = "example"
display_name = "Coder Large"
api_model_id = "coder-large"
context_window = 262144
max_output_tokens = 32768
supports_tools = true
supports_parallel_tools = true
supports_streaming = true
supports_vision = false
capability_source = "user_override"
capability_confidence = "high"
billing = "openai"

[models.pricing]
input_per_million_usd = 1.00
cached_read_per_million_usd = 0.10
output_per_million_usd = 4.00

[models.reasoning]
control = "controllable"
allowed_efforts = ["low", "medium", "high"]
default_effort = "medium"
supports_tools_with_reasoning = true

Model fields

Setting a capability to true describes the model; it does not add the capability. A model that cannot call tools still fails a tool call when supports_tools = true.

Tool calls in one response

Orek runs tool calls from a single model response in parallel up to agent.max_parallel_tool_calls (calls targeting the same file still run in order; see Several tool calls at once). Set supports_parallel_tools = false to run a model’s tool calls one at a time.

Malformed tool calls

If a model returns a tool call with a missing name or ID or invalid JSON arguments, Orek returns an error directly to the model instead of prompting or running a tool, allowing the model to correct the call and continue. Saved sessions also repair malformed historical tool calls automatically when resumed.

Pricing fields

[models.pricing] accepts per-million-token USD rates:

Prompt-length pricing

Use [[models.pricing.prompt_tiers]] when a provider charges higher rates for the entire request once total input tokens (including cached input) exceed above_input_tokens.

The bundled catalog includes these tiers for the three GPT-6 models and Claude Haiku 5.5. Haiku uses its higher rates above 100,000 input tokens, counting uncached input, cache reads, and cache writes together. Other models keep their declared flat rates unless their entry includes tiers.

For your own model, replace the example [models.pricing] table above with the provider’s base rates and any tiers. These sample values illustrate a model whose rates change above 100,000 input tokens:

[models.pricing]
input_per_million_usd = 1.00
cached_read_per_million_usd = 0.10
cache_creation_per_million_usd = 1.25
output_per_million_usd = 4.00

[[models.pricing.prompt_tiers]]
above_input_tokens = 100000
input_per_million_usd = 2.00
cached_read_per_million_usd = 0.20
cache_creation_per_million_usd = 2.50
output_per_million_usd = 6.00

Each tier accepts above_input_tokens, input_per_million_usd, optional cached_read_per_million_usd and cache_creation_per_million_usd, and output_per_million_usd. Orek selects the highest threshold exceeded by the request’s input (so 100000 applies at 100,001 tokens) and uses that tier’s rates for all input, cache, and output tokens. Tiers do not inherit cache rates from [models.pricing]; if a request uses cached tokens on a tier without cache rates (including free 0.0 models), its cost is marked incomplete (*).

Routing estimates cost from prompt length, while /usage sums the actual cost saved after each completed request without repricing older turns (* indicates incomplete pricing or token data; -- indicates no saved cost).

API fields for built-in providers

The default suits Kimi Code, Ollama, and any OpenAI-compatible service using Chat Completions, including a custom Mistral model on Chat Completions. A model using Responses (such as OpenAI’s or Mistral’s built-in models), Anthropic, or Google needs the fields that select that API:

Other wire_protocol values are open_ai_chat, open_ai_completions, and the provider formats above. Other endpoint_family values are completions, workers_ai_v1, embeddings, image_generation, and unsupported; use only a combination that your provider’s API supports.

Reasoning efforts

control = "controllable" lets you choose a reasoning effort per session. allowed_efforts lists the efforts Orek may send; an effort outside a non-empty list is left off the request, so the server’s default applies. An empty list allows every effort Orek supports for the model’s API, including none, unless an Anthropic entry sets anthropic_thinking_off = "unavailable".

List only effort values documented by your provider. Use control = "intrinsic" for models that always reason without an effort parameter, and omit [models.reasoning] for models that do not reason.

Reasoning replay fields

A [models.reasoning.replay] table declares how a model takes back earlier reasoning. Every key is optional; a key you leave out takes the default for the model’s provider and API.

A key you declare replaces the default, and /context no longer reports reasoning it leaves out as not verified yet. This example, for a vLLM provider declared as in Local models, lets the model read its own earlier reasoning from reasoning_content, and other models’ reasoning under preserve:

[[models]]
id = "vllm/qwen3-coder"
provider = "vllm"
api_model_id = "qwen3-coder"
context_window = 262144
supports_tools = true
supports_streaming = true
capability_source = "user_override"
capability_confidence = "high"

[models.reasoning]
control = "intrinsic"
supports_tools_with_reasoning = true

[models.reasoning.replay]
input = "reasoning_content"
foreign = "translate"

The removed replays_reasoning_content key has no effect and receives an unknown-key diagnostic. Set input under [models.reasoning.replay] as above.

[ui]

Keymap rules:

• User-only. ui.keymap belongs in your user config. A [ui.keymap] table in a project .orek/config.toml is ignored and reported (see settings a project cannot change), because a repository must not be able to remap your approval keys.
• One name per action. Each action has a single canonical id and belongs to exactly one context, as ui.keymap.<context>.<action>; there are no aliases. For example, search_transcript and clear_viewport live in [ui.keymap.composer]. Use /keys list to see every action under its context.
• Unknown names are errors. A misspelled context or a misspelled key under [ui.keymap] fails the load and lists the valid names. A misspelled action also names the closest valid action (did you mean `toggle_detail_pane`?) and lists the valid ones for that context.
• Bindings must be reachable. Orek rejects a binding that could never fire because another binding owns the same key where both can be active, for example transcript.scroll_up = "ctrl+t" behind the built-in global ctrl+t. Rebind or unbind the other action first.
• Approval keys are rebindable. approve, deny, confirm, and always_allow in [ui.keymap.approval] can be rebound like any other action. Esc stays reserved for cancelling the prompt, and Ctrl+C stays reserved. A bare printable approve key, such as y, can approve while you are typing ahead during an approval, so prefer a modified key unless you want that.
• Set values with orek config set ui.keymap.<context>.<action> <binding> or with the /keys editor; both validate the whole keymap before saving. none, unbind, unbound, or [] leaves an action unbound.
• Reset with orek config unset ui.keymap, or in the TUI with /keys reset (or R in the editor). Either removes the whole table, leader and chord timeout included, even when the saved keymap no longer loads. If it does not load, Orek refuses to start and the error ends with this command.

[routing]

Reasoning values are auto, none, minimal, low, medium, high, xhigh, and max. The selected model must support the requested value.

Subagents handle fallback on their own, regardless of cascade_enabled. Orek has no per-request cost cap. See Routing for pins, routes, and failure handling.

[compaction]

Manage long conversations. Its write scope is Project.

The limit is the smaller of auto_compact_threshold and 90% of the active model’s input window, its context window less its output limit; when unset it is that 90%. For a model with a 1,000,000-token window and a 128,000-token output limit, that is 784,800 tokens. A higher value is capped at 90%, and the limit follows the model after a switch. See automatic compaction for how the context is measured. Oversized tool results are cut when they are recorded, with no setting; see oversized tool output.

Summaries

Automatic compaction and /compact use the active model, unless the model that answered last has a larger window, as after a switch to a smaller model; then that model writes the summary. See switching to a smaller model. On Claude, when the same model wrote the conversation and its summary, the summary request reuses the prompt cache. When the history is too long for the summary request, its oldest messages are left out until it fits. See session history for cancellation and resume behavior.

[response_compression]

Ask the model for shorter replies. Compression is off until a [response_compression] section exists in your configuration; adding one turns it on with the ultra profile unless you choose another. The defaults below apply only inside that section. These keys default to Project write scope.

[exec]

Choose approvals, the OS sandbox, and limits on command output. See Permissions and security. default_approval_mode, require_approval_for, redact_exec_output, sandbox_runtime_enabled and every auto_review key are user-only: a project file cannot set them.

orek run follows default_sandbox like an interactive session, so it applies edits unless that setting says otherwise; its approval mode decides what needs approval. Kept output has its own limits, so it may not hold the complete original.

The OS sandbox is off by default. While it is off, shell and background commands run with the full inherited environment (including provider API keys) and without Seatbelt; approvals are the only protection. Language servers keep their own environment filter either way.

In the TUI, /sandbox on|off changes sandbox_runtime_enabled for the running session only, and /sandbox persist on|off saves it to user configuration. OREK_SANDBOX=off forces the sandbox off even when the setting is on, and the TUI warns while it does. On Windows, stopping a command still stops every process it started, with or without the sandbox.

default_sandbox is experimental and has no command, setup, or ACP control; only configuration sets it. Under dry_run and simulation, file edits and commands are previewed or described instead of applied. Models are not told the session runs in such a mode and tend to retry those edits in a loop, so keep approved unless you are experimenting. Setting another value with /config set prints a warning, and the status bar shows [DRY-RUN] or [SIMULATION] while one is active.

[agent]

Subagent and continuation limits, and how a model switch treats earlier reasoning. Project is the default write scope unless stated otherwise.

With an empty list, every skeptic uses the active model, and the result says so. See Subagents.

Each [agent.subagent_profiles.<name>] table accepts only these fields:

An unknown field, such as a misspelling, stops the configuration from loading.

[index]

The code index, and the context Orek finds in it automatically.

chunk_size must be positive and chunk_overlap must be smaller than it.

/retrieval off changes the current TUI session; /retrieval clear restores the configured value. /retrieval persist off writes the user default. For a project override:

orek config set --scope project index.retrieval.enabled false

This does not stop indexing, explicit references, graph queries, search_project, or orek index query diagnostics. See retrieval controls.

[index.embedding]

By default, Orek creates embeddings locally with embeddinggemma-2 (768 dimensions). Set these fields in TOML.

[index.embedding]
kind = "local-fastembed"
model = "embeddinggemma-2"

For kind = "openai-compatible":

If the service returns longer embeddings, Orek shortens them to dimension. Changing the model or dimension requires a full orek index build. Keep credentials in the OS credential store or user-scope environment references. Cloud embedding examples cover Mistral, OpenAI, rebuilds, and the data sent to providers.

[permissions]

These are TOML settings; see permission examples. Every key except sensitive_patterns is user-only. A project file may add sensitive_patterns, which only adds protected paths.

A rule in tool_rules, mcp_server_rules, or path_scopes that Orek cannot apply, such as an unknown decision or mode, stops your configuration from loading. The error names the rule, so you can correct it in your user config file. Orek still opens and shows the error, and other commands stop with it. Ignoring the rule would silently remove the restriction you wrote.

env_allowlist, sandbox_read_paths, and sandbox_write_paths shape the OS sandbox, so they apply only while exec.sandbox_runtime_enabled is on.

With the sandbox on, commands receive a basic set of variables, including common toolchain variables and, on Windows, system paths such as SystemRoot, ComSpec, TEMP, USERPROFILE, APPDATA, and LOCALAPPDATA so programs can start. Windows names match regardless of case. Add any other variable, such as a secret a command needs, to env_allowlist.

[tools.read_file]

These settings default to User write scope. Restart Orek after changing them.

[tools.search_project]

These experimental settings control search_project, the tool the model uses to search your project’s content. Restart Orek or start a new session after changing them.

Zero or a value outside these ranges stops the configuration from loading, and config set refuses it. Omitted fields keep their defaults; unsetting a project override restores the user value or built-in default. The tool searches the main project index with your embedding and retrieval settings, and reports a missing or out-of-date index instead of building one.

[tools.search_project]
enabled = true
max_tokens = 4096
max_bytes = 32768

To keep automatic context but take search_project away from the model:

orek config set tools.search_project.enabled false

index.retrieval.enabled, /retrieval off, and @!retrieve affect only automatic retrieval. index.enabled = false removes both search_project and code_graph_query; --no-tools disables all callable tools. See search arguments and result states.

[tools.memory]

See memory for storage and permission rules.

[tools.apply_patch]

To offer it to some models only, prefer a per-model revealed rule; see model tool access.

[tools.run_python]

With or without it, a shell command that pipes data into a Python script that also reads stdin from a heredoc (cmd | python3 - <<'EOF') is refused before approval with Not run:, because stdin cannot carry both.

[tools.web]

[tools.shell]

These TOML settings choose the program behind the shell tool. The tool keeps the name shell whether it runs PowerShell or a POSIX shell, and Orek tells the model which shell it is using. When Orek recognizes a shell error, it tells the model how to recover; it never rewrites or retries a command itself.

bash and powershell are aliases for shell. Permission rules, path scopes, loop-breaker exemptions, [tool_exposure] hidden and revealed lists, tier allowlists, and subagent profiles that use either name still match. Always allow saves toolName = "shell".

On Windows, automatic selection uses PowerShell 7 (pwsh.exe), then Windows PowerShell 5.1 (powershell.exe). Elsewhere it uses $SHELL, then bash.

Windows shell compatibility

When only Windows PowerShell 5.1 is available, Orek supports top-level &&/|| command chains and refuses malformed or nested chains without running them. If you choose cmd.exe, Orek cannot check its commands, so every command asks for approval outside yolo.

fish and other non-POSIX shells

Orek understands command syntax only for PowerShell (pwsh, powershell) and recognized POSIX shells (sh, bash, rbash, dash, zsh, ksh, ksh93, mksh, lksh, pdksh, oksh, loksh, ash, hush, busybox, yash, posh). Under any other shell—such as fish, csh, tcsh, nu, elvish, xonsh, or a renamed binary like pwsh-preview—or when a command names one of those shells (fish -c ..., ... | fish, echo fish), Orek runs the shell with -c and always prompts for approval outside yolo (commandPrefix rules, Always allow, and auto_review do not apply, and non-interactive runs fail at the first such command). Orek cannot detect such a shell when a command reaches it indirectly, for example through a variable, a renamed program, or a script, without naming it.

[observe]

Nothing is exported while no endpoint is set. To turn export off, remove the value from both scopes and restart:

orek config unset observe.otlp_endpoint --scope project
orek config unset observe.otlp_endpoint --scope user
orek config get observe.otlp_endpoint

Local logs, saved sessions, and model requests are not affected. Authentication uses OTEL_EXPORTER_OTLP_HEADERS, not a project secret. OTEL_SERVICE_NAME overrides the default orek-cli service name. See Disable remote export.

[update]

[skills]

The built-in code-review and performance-investigation skills contain instructions only, and a project or user skill with the same name replaces them. orek skills discover lists skills from other tools without activating them or changing search paths; orek skills import copies one you choose. See skills and activation.

[lsp]

Language-server diagnostics need enabled = true, and you must trust each server for each project with /lsp trust <server>. All three switches are off by default.

Trust grants are stored outside the repository, and editing a declaration never grants trust. See Language servers.

Server declaration and diagnostic details

Named server tables live under [lsp.servers.<name>] and are managed with orek lsp add / orek lsp remove, not with orek config set. Adding a table does not trust the server. The built-in catalog includes 16 language servers (rust-analyzer, gopls, pyright, typescript-language-server, clangd, jdtls, OmniSharp, kotlin-language-server, sourcekit-lsp, Dart analysis server, intelephense, ruby-lsp, Metals, elixir-ls, lua-language-server, R languageserver). rust-analyzer is the default when no override is declared. An unknown field in a [lsp.servers.<name>] table stops the configuration from loading. A declaration with a built-in server’s name keeps the built-in values only for fields it leaves out; an explicit empty list or map (args = [], language_id_map = {}, platforms = []) replaces them.

language_ids are Orek’s names for the languages a server handles; protocol_language_ids are the IDs sent to the server. When set, extensions, filenames, and shebangs are checked first. root_markers matches any single marker, while each entry in root_marker_groups requires every marker in that group. root_strategy is "nearest" by default and may be "outermost". String values in commands, arguments, explicit environment values, initialization options, and settings may use {project_root}, {root}, and {cache_dir}, which are replaced as plain text. {root} is not allowed in the server’s command, so the program you trusted cannot change.

Language servers start with a basic environment (PATH, home, user, shell, temp, terminal, locale, and common language-runtime variables) plus only the variables you declare in the server’s env map, so provider API keys are never passed on. A server that times out, fails to start, crashes, is not trusted, or does not support the file never reports the file as clean.

[tool_exposure]

Use TOML to control which tools a model sees.

Tiers are frontier, high, medium, low, and unknown. MCP tools, subagent and workflow tools (such as spawn_agent and run_workflow), and the task tools write_tasks and update_plan ignore tier allowlists. To hide them, use an exact per-model rule:

[[tool_exposure.per_model]]
provider = "ollama"
model = "ollama/qwen2.5-coder:7b"
hidden = ["write_tasks", "fanout"]

Per-model hidden always applies, even to those tools. write_tasks is visible by default, so it needs no revealed entry. See Plan and track work.

[mcp]

Use orek mcp add or named [mcp.servers.<name>] tables. An unknown field in a server table stops the configuration from loading. This HTTP example declares a server; it does not complete OAuth or grant project consent:

[mcp.servers.linear]
url = "https://mcp.linear.app/mcp"
auth = "oauth"
enabled = true
soft_fail = true
startup_timeout_secs = 30
tool_timeout_secs = 60
allowed_tools = []

command selects stdio; url selects streamable HTTP. An empty allowed_tools exposes every tool returned by that server. startup_timeout_secs limits connecting and fetching the server’s tool list (each page of the list has 15 seconds). tool_timeout_secs limits how long a tool call waits for a result or a progress update; each update restarts the wait, up to ten times tool_timeout_secs in total. Optional headers adds HTTP headers, and bearer_token_env names an environment variable holding a bearer token to use instead of OAuth. See MCP setup.

Expansion, environment, and consent

• Environment references: ${VAR} and ${VAR:-default} expand in commands, args, env values, URLs, and headers when the configuration loads.
• Server environment: Stdio MCP servers start with a basic environment (PATH, home, user, shell, temp, terminal, locale, and standard Windows system paths), so provider API keys never reach a server unless you pass them. Declare any secrets a server needs (GITHUB_TOKEN, custom variables) in its env map.
• Server & tool naming: Server names use [a-z0-9_-] (up to 64 characters, no doubled or leading/trailing underscores), and tools are named mcp__{server}__{tool} (shortened the same way every time when needed to fit 64 characters). An editor connected through ACP can pass a server with the same name; for that session Orek uses the editor’s connection but keeps your enabled, allowed_tools, timeouts, and permission rules, and never uses your saved headers, environment, or OAuth credentials. See IDE integration.
• Consent & permissions: Servers declared in a project’s .orek/config.toml ask for your approval before they first connect, and again if the declaration changes; servers in your user configuration connect without asking. Per-server tool rules live in [permissions.mcp_server_rules] (allow, ask_user, or deny), and MCP tool calls default to ask_user.