Configuration and providers

This page documents source commit 01dabf2fedd1826362162ead9757232e89d9bfa5. Osprey combines command-line interface (CLI) options, environment variables, project configuration, and user configuration.

Precedence

Osprey applies this general precedence from highest to lowest:

1. Command-line interface (CLI) options
2. Environment variables
3. The nearest project .osprey/config.toml
4. The global $OSPREY_HOME/config.toml
5. Built-in defaults

Only supported project fields participate in the project layer. Some settings have fewer layers. Each setting below states its applicable precedence.

Osprey loads environment values from a discovered .env file before CLI parsing. The .env loader does not replace process environment variables that already exist.

Default paths

OSPREY_HOME selects the Osprey state directory. The default is $HOME/.osprey. If no home directory exists, Osprey uses .osprey under the current directory. The terminal user interface (TUI) writes hourly logs to files.

Path	Purpose
$OSPREY_HOME/config.toml	Global user configuration
$OSPREY_HOME/sessions.db	Default SQLite session database
$OSPREY_HOME/logs/	Hourly TUI log files
$OSPREY_HOME/processes/	Preserved process records
$OSPREY_HOME/approvals.toml	Persistent tool approvals
$OSPREY_HOME/workflow_trust.toml	Approved workflow digests
$OSPREY_HOME/trust.toml	Trust digests for project extension artifacts
$OSPREY_HOME/personas/	User persona files
$OSPREY_HOME/workflows/	User workflow scripts and run data
$OSPREY_HOME/cache/	Cached provider model catalogs

Subcommands write logs to standard error.

Global and project files

The global file accepts every active configuration section. The file stores no provider secrets. config.toml uses Tom's Obvious Minimal Language (TOML) syntax.

The project file accepts only these sections:

• [tool_results]
• [roles]
• [extensions]
• [agent]
• [workflows]
• [images]

The project parser rejects every other top-level key or section. Keep database_url, driver, provider tables, [web_search], [lsp], and [memory] in the global file.

Osprey searches upward from the working directory. The nearest project .osprey/config.toml wins over more distant project files. Project values merge over global values one field at a time.

Minimal global configuration

The following configuration selects OpenRouter and the source default model. The file contains no key.

driver = "openrouter"

[openrouter]
model = "minimax/minimax-m2.7"

Set OSPREY_OPENROUTER_API_KEY in the process environment before launch.

Without database_url, Osprey uses SQLite at $OSPREY_HOME/sessions.db. Without driver, Osprey starts with OpenRouter as the configured provider.

Provider configuration

Osprey supports five provider types. An application programming interface (API) key authenticates a provider. A Uniform Resource Locator (URL) identifies a provider endpoint.

Provider	driver value	API key variable	Base URL variable	Built-in model default
Anthropic	anthropic	OSPREY_ANTHROPIC_API_KEY	OSPREY_ANTHROPIC_BASE_URL	claude-sonnet-4-20250514
OpenAI	openai	OSPREY_OPENAI_API_KEY	OSPREY_OPENAI_BASE_URL	gpt-4o
OpenRouter	openrouter	OSPREY_OPENROUTER_API_KEY	OSPREY_OPENROUTER_BASE_URL	minimax/minimax-m2.7
Nous	nous	OSPREY_NOUS_API_KEY	OSPREY_NOUS_BASE_URL	nousresearch/hermes-4-405b
Z.AI Coding Plan	zai-coding-plan	OSPREY_ZAI_API_KEY	OSPREY_ZAI_BASE_URL	glm-5.2

Z.AI Coding Plan is marked experimental in the source.

The built-in Anthropic API root is https://api.anthropic.com. The built-in OpenAI API root is https://api.openai.com/v1. The built-in OpenRouter API root is https://openrouter.ai/api/v1. The built-in Nous API root is https://inference-api.nousresearch.com/v1. The built-in Z.AI API root is https://api.z.ai/api/coding/paas/v4.

Osprey appends each provider endpoint path to a configured root. Anthropic appends /v1/messages. OpenAI appends /responses or /chat/completions according to the selected model path. The other providers append /chat/completions.

Each provider table requires model when the table exists. Optional fields are base_url, temperature, and reasoning.

driver = "openai"

[openai]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
temperature = 0.2
reasoning = { effort = "medium", max_tokens = 4096, exclude = false }

The matching base URL environment variable overrides base_url. The CLI --temperature overrides OSPREY_TEMPERATURE and provider temperature. Anthropic omits temperature from its requests.

Reasoning effort accepts none, minimal, low, medium, high, xhigh, or max. An unknown config value produces a warning. Osprey removes only the effort override.

Provider selection and authentication

Osprey reads API keys only from environment variables. Never place an API key in config.toml.

If the configured provider has no key, Osprey searches available keys in this order:

1. Anthropic
2. OpenAI
3. OpenRouter
4. Nous
5. Z.AI Coding Plan

Osprey reports a provider substitution during startup. The selected provider uses its configured model or built-in model default.

The TUI starts without a provider key. It displays configuration guidance. A headless model request fails when no usable provider exists.

Role bindings

[roles] assigns a provider and model to a runtime role. Unconfigured roles use the top-level provider and model.

The supported role keys are action, thinking, critique, compact, and vision.

[roles]
action = { driver = "openrouter", model = "minimax/minimax-m2.7" }
thinking = { driver = "anthropic", model = "claude-sonnet-4-20250514" }
compact = { driver = "openai", model = "gpt-4o-mini" }

Every referenced provider requires its matching environment key.

Runtime limits

The following keys live at the global top level.

Key	Default	Precedence and behavior
max_turns	TUI unlimited, headless 150	CLI overrides config. Zero is invalid.
turn_timeout_secs	300 for headless	CLI, then OSPREY_TURN_TIMEOUT, then config. Zero is invalid.
stream_idle_timeout_secs	60	CLI overrides config. Config zero disables the watchdog.
question_timeout_secs	3600	Config zero resets to 3600 with a warning.
agent_timeout_secs	No complete-session limit	OSPREY_AGENT_TIMEOUT_SEC overrides config.
streaming_timeout_secs	No transport timeout	CLI overrides config. Config zero becomes no timeout.
empty_completion_threshold	2	CLI overrides config. Config zero resets to 2.
driver_max_retries	3	CLI overrides config. Zero disables retries.
cache_preference	default	Accept default, bypass, or extended. Unknown values warn and use default.

Tool-result handling

[tool_results] controls truncation, storage, and optional compression.

Key	Default	Behavior
cap	32768	Maximum bytes per result. Zero disables the byte cap.
head	12288	Bytes retained from the result start.
tail	12288	Bytes retained from the result end.
max_lines	0	Maximum lines. Zero disables the line trigger.
sidecar_dir	No configured directory	Override the TUI directory for complete capped results. The bare TUI otherwise uses $OSPREY_HOME/raw.
retention_days	7	Maximum age for files in the TUI sidecar directory.
compress_context	False	Compress large non-streaming results before context insertion.
compress_min_bytes	2048	Minimum result size for compression.

Headless tool-result size and compression options override their corresponding section fields. The headless command does not use sidecar_dir for raw spills. It writes complete capped results only when --tool-result-raw-dir or an ATIF sibling raw directory supplies the destination.

[archival].idle_days defaults to 30. The TUI archives session trees that exceed the configured idle age before listing them.

Agent and workflow sections

Agent Trajectory Interchange Format (ATIF) is the trajectory output format.

[agent] accepts these fields:

Key	Default	Behavior
max_subagents	8	Set the child concurrency cap. CLI overrides config.
llm_rpm	No rate limit	Set the shared request rate. CLI overrides config.
ultracode	False	Enable workflow preference and xhigh reasoning. CLI true overrides config.
default_persona	default	Select the persona when no CLI option exists.
atif_system_prompt_plaintext	False	Store prompt text with the ATIF digest. CLI overrides config.

[workflows] accepts these fields:

Key	Default	Behavior
enabled	True	False removes workflow composition. The disable environment variable also wins.
max_concurrent	16	Limit concurrent workflow agent calls.
max_total	1000	Limit total workflow agent calls in one run.
run_retention_days	Keep forever	Delete older workflow run directories when set above zero.

run_retention_days = 0 also keeps workflow runs forever. Deleting workflow run directories can remove raw outputs referenced by saved transcripts. Set run_retention_days only in the global file for this source target. The project parser accepts that field. The project merge discards its value at the audited commit.

Web search

[web_search] is global-only. The section accepts provider and optional endpoint.

Provider values are exa, brave, searxng, and none. none disables the tool even when search credentials exist.

Provider	Required environment input
Exa	EXA_API_KEY
Brave	BRAVE_SEARCH_API_KEY
SearXNG	SEARXNG_URL unless config supplies endpoint

Without a configured section, Osprey detects Exa, then Brave, then SearXNG. Without matching configuration or environment input, Osprey omits the web_search tool.

Language servers

[lsp] is global-only. The section is disabled by default. Language Server Protocol (LSP) tools provide code navigation.

[lsp]
enabled = true

[[lsp.servers]]
name = "rust-analyzer"
command = "rust-analyzer"
args = []
extensions = ["rs"]
root_markers = ["Cargo.toml"]

Each custom server requires a nonempty command and at least one file extension. An invalid server configuration stops launch.

Images

[images].read controls image attachments from read_file. An absent value follows the action provider capability. false always disables image attachments. true requires a provider that delivers tool-result images.

At the audited commit, Anthropic provides that delivery path. An incompatible true value stops launch.

Memory

[memory].provider accepts builtin, hindsight, or none. The default provider is builtin.

Builtin memory uses these limits:

Key	Default characters
memory_char_limit	2200
user_char_limit	1375

Hindsight accepts a nested [memory.hindsight] table.

Key	Default
mode	cloud
api_url	Provider URL for the selected mode
bank_id	osprey
recall_budget	mid
timeout_secs	120

Supported modes are cloud and local_external. Cloud mode defaults to https://api.hindsight.vectorize.io. Local external mode defaults to http://localhost:8888. Cloud mode requires HINDSIGHT_API_KEY. Recall budget accepts low, mid, or high. An invalid Hindsight field or value stops memory initialization.

Mixture of Agents

[moa] stores named Mixture of Agents presets. Each preset defines reference slots and one aggregator slot. Each slot requires provider and model. The optional investigate field defaults to false.

Preset defaults are:

Key	Default
reference_temperature	0.6
aggregator_temperature	0.4
reference_max_tokens	Unset
enabled	True
investigation_max_turns	4

The section also accepts default_preset and save_traces. An unknown default preset or an empty reference list fails validation.

Extension policy

[extensions] accepts project_doc_max_bytes and trust_agent_authored. The parser accepts both fields. Neither field changes runtime behavior at the audited commit. System prompt composition currently uses a fixed 32768-byte project document limit.

Project extension artifacts use separate files under .osprey/. These files include SYSTEM.md, APPEND_SYSTEM.md, hooks.toml, and toolsets.toml. They also include tool-descriptions.toml and tools/*.toml.

OSPREY_SYSTEM_PROMPT_FILE has priority over the nearest SYSTEM.md and the selected persona. All visible APPEND_SYSTEM.md files append in project-first order.

Repository sandbox configuration

The workspace root can contain a separate .osprey.toml file. The sandbox sidecar reads the file when --sandbox starts.

[sandbox.network].allow accepts literal host:port strings. The macOS Seatbelt backend enforces those network entries. The Linux backend leaves network egress open. It warns about configured entries.

[commands] accepts root command strings and named command groups. Each named group can set a relative root directory.

[exec].deny_patterns is advisory metadata. The runner does not reject commands from those text patterns.

The parser rejects these inactive settings:

• [sandbox].image
• Top-level [network] allowlist fields
• [exec].timeout_secs
• [agent].ignore

A malformed .osprey.toml stops normal sandbox provisioning. Fix the file before you retry --sandbox.

User-relevant environment variables

Variable	Purpose and precedence
OSPREY_HOME	Override the complete state directory.
OSPREY_DATABASE_URL	Override global database_url.
OSPREY_MODEL	Override the active provider model unless CLI supplies --model.
OSPREY_TEMPERATURE	Override provider temperature unless CLI supplies --temperature.
OSPREY_TURN_TIMEOUT	Override config unless CLI supplies --turn-timeout.
OSPREY_AGENT_TIMEOUT_SEC	Override the complete headless session limit.
OSPREY_BASH_TIMEOUT	Set the default Bash tool timeout. Per-call input wins.
OSPREY_DISABLE_WORKFLOWS	Disable workflows for 1, true, yes, or on.
OSPREY_SKILL_DIR	Add one extra skill root unless CLI supplies roots.
OSPREY_LOG	Set the logging filter. It overrides RUST_LOG.
RUST_LOG	Set the logging filter when OSPREY_LOG is absent.
OSPREY_MODELS_URL	Override the https://models.dev catalog base.
OSPREY_SYSTEM_PROMPT_FILE	Replace the persona base with a readable file.
OSPREY_TOOL_DESCRIPTIONS_FILE	Override layered tool descriptions with a TOML file.
EXA_API_KEY	Enable or authenticate Exa search.
BRAVE_SEARCH_API_KEY	Enable or authenticate Brave search.
SEARXNG_URL	Enable SearXNG or supply its endpoint.
HINDSIGHT_API_KEY	Authenticate Hindsight cloud memory.
VISUAL	Select the TUI external editor. It overrides EDITOR.
EDITOR	Select the TUI external editor when VISUAL is absent.
SSL_CERT_FILE	Select a certificate file for transport trust.
SSL_CERT_DIR	Select a certificate directory for transport trust.
SSH_CONNECTION, SSH_TTY	Select remote clipboard handling.
TMUX	Wrap remote clipboard output for tmux.

Provider API key and base URL variables appear in the provider table above.

AGENT_RUNNER_BIND and OSPREY_AGENT_RUNNER_PORT configure the operational sidecar. These variables are not normal application settings.

Skill path limit

Current source and current help text disagree about the user-global skill directory. Runtime discovery scans a directory under OSPREY_HOME. CLI help names $HOME/.agents/skills instead.

Do not depend on either user-global path for this source target. Use a project .agents/skills directory or explicit --skill-dir options. OSPREY_SKILL_DIR supplies one extra directory, not a repeatable environment list.

Setup behavior

osprey setup reads provider keys from the current environment. The wizard never prompts for or stores a key.

The command can read provider model catalogs over the network. The command writes database_url, driver, and the selected provider model. The command preserves unrelated keys and comments in a valid existing file.

The wizard defaults to SQLite. It tests the selected database. The wizard saves configuration after a failed database test. Correct the stored URL before the next launch.

Parse failures and recovery

A missing global config file is a normal first-run state. Osprey uses built-in defaults in that state.

An unreadable or malformed global file produces a warning. Osprey discards the complete global file and uses defaults. Fix the TOML syntax before you rely on any stored setting.

An unreadable, malformed, or unsupported project file stops launch. Move global-only keys to $OSPREY_HOME/config.toml. Keep only the six allowed project sections in .osprey/config.toml.

A malformed existing global file also stops osprey setup from overwriting the file. Fix or remove the malformed file. Then run setup again.

Back to Osprey