owlen/docs/configuration.md

Owlen Configuration

Owlen uses a TOML file for configuration, allowing you to customize its behavior to your liking. This document details all the available options.

File Location

Owlen resolves the configuration path using the platform-specific config directory:

Platform	Location
Linux	~/.config/owlen/config.toml
macOS	~/Library/Application Support/owlen/config.toml
Windows	%APPDATA%\owlen\config.toml

Use owlen config init to scaffold the latest default configuration (pass --force to overwrite an existing file), owlen config path to print the resolved location, and owlen config doctor to migrate or repair legacy files automatically.

Configuration Precedence

Configuration values are resolved in the following order:

1. Defaults: The application has hard-coded default values for all settings.
2. Configuration File: Any values set in config.toml will override the defaults.
3. Command-Line Arguments / In-App Changes: Any settings changed during runtime (e.g., via the :theme or :model commands) will override the configuration file for the current session. Some of these changes (like theme and model) are automatically saved back to the configuration file.

Validation runs whenever the configuration is loaded or saved. Expect descriptive Configuration error messages if, for example, remote_only mode is set without any [[mcp_servers]] entries.

---

General Settings ([general])

These settings control the core behavior of the application.

• default_provider (string, default: "ollama") The name of the provider to use by default.

• default_model (string, optional, default: "llama3.2:latest") The default model to use for new conversations.

• enable_streaming (boolean, default: true) Whether to stream responses from the provider by default.

• project_context_file (string, optional, default: "OWLEN.md") Path to a file whose content will be automatically injected as a system prompt. This is useful for providing project-specific context.

• model_cache_ttl_secs (integer, default: 60) Time-to-live in seconds for the cached list of available models.

UI Settings ([ui])

These settings customize the look and feel of the terminal interface.

• theme (string, default: "default_dark") The name of the theme to use. See the Theming Guide for available themes.

• word_wrap (boolean, default: true) Whether to wrap long lines in the chat view.

• max_history_lines (integer, default: 2000) The maximum number of lines to keep in the scrollback buffer for the chat history.

• role_label (string, default: "above") Controls how sender labels are rendered next to messages. Valid values are "above" (label on its own line), "inline" (label shares the first line of the message), and "none" (no label).

• wrap_column (integer, default: 100) The column at which to wrap text if word_wrap is enabled.

• input_max_rows (integer, default: 5) The maximum number of rows the input panel will expand to before it starts scrolling internally. Increase this value if you prefer to see more of long prompts while editing.

• scrollback_lines (integer, default: 2000) The maximum number of rendered lines the chat view keeps in memory. Set to 0 to disable trimming entirely if you prefer unlimited history.

• syntax_highlighting (boolean, default: false) Enables lightweight syntax highlighting inside fenced code blocks when the terminal supports 256-color output.

• keymap_profile (string, optional) Set to "vim" or "emacs" to pick a built-in keymap profile. When omitted the default Vim bindings are used. Runtime changes triggered via :keymap ... are persisted by updating this field.

• keymap_path (string, optional) Absolute path to a custom keymap definition. When present it overrides keymap_profile. See crates/owlen-tui/keymap.toml or crates/owlen-tui/keymap_emacs.toml for the expected TOML structure.

Storage Settings ([storage])

These settings control how conversations are saved and loaded.

• conversation_dir (string, optional, default: platform-specific) The directory where conversation sessions are saved. If not set, a default directory is used:

  • Linux: ~/.local/share/owlen/sessions
  • Windows: %APPDATA%\owlen\sessions
  • macOS: ~/Library/Application Support/owlen/sessions

• auto_save_sessions (boolean, default: true) Whether to automatically save the session when the application exits.

• max_saved_sessions (integer, default: 25) The maximum number of saved sessions to keep.

• session_timeout_minutes (integer, default: 120) The number of minutes of inactivity before a session is considered for auto-saving as a new session.

• generate_descriptions (boolean, default: true) Whether to automatically generate a short summary of a conversation when saving it.

Input Settings ([input])

These settings control the behavior of the text input area.

• multiline (boolean, default: true) Whether to allow multi-line input.

• history_size (integer, default: 100) The number of sent messages to keep in the input history (accessible with Ctrl-Up/Down).

• tab_width (integer, default: 4) The number of spaces to insert when the Tab key is pressed.

• confirm_send (boolean, default: false) If true, requires an additional confirmation before sending a message.

Provider Settings ([providers])

This section contains a table for each provider you want to configure. Owlen now ships with four entries pre-populated—ollama_local, ollama_cloud, openai, and anthropic. Switch between them by updating general.default_provider.

[providers.ollama_local]
enabled = true
provider_type = "ollama"
base_url = "http://localhost:11434"
list_ttl_secs = 60
default_context_window = 8192

[providers.ollama_cloud]
enabled = false
provider_type = "ollama_cloud"
base_url = "https://ollama.com"
api_key_env = "OLLAMA_API_KEY"
hourly_quota_tokens = 50000
weekly_quota_tokens = 250000
list_ttl_secs = 60
default_context_window = 8192

[providers.openai]
enabled = false
provider_type = "openai"
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"

[providers.anthropic]
enabled = false
provider_type = "anthropic"
base_url = "https://api.anthropic.com/v1"
api_key_env = "ANTHROPIC_API_KEY"

• enabled (boolean, default: true) Whether the provider should be considered when refreshing models or issuing requests.

• provider_type (string, required) Identifies which implementation to use. Local Ollama instances use "ollama"; the hosted service uses "ollama_cloud". Third-party providers use their own identifiers ("openai", "anthropic", ...).

• base_url (string, optional) The base URL of the provider's API.

• api_key / api_key_env (string, optional) Authentication material. Prefer api_key_env to reference an environment variable so secrets remain outside of the config file.

• list_ttl_secs (integer, default: 60) Time-to-live for the cached model list used by the picker. Increase it to reduce background traffic or decrease it if you rotate models frequently.

• default_context_window (integer, optional) Expected maximum prompt length (tokens) for the provider. Owlen uses this to render the context usage gauge and warn when you approach the limit.

• hourly_quota_tokens / weekly_quota_tokens (integer, optional) Soft limits that drive the cloud usage gauge and :limits readout. Owlen tracks actual usage locally and compares it to these thresholds to raise 80% / 95% toasts.

• extra (table, optional) Any additional, provider-specific parameters can be added here.

Using Ollama Cloud

Owlen now separates the local daemon and the hosted API into two providers. Enable ollama_cloud once you have credentials, while keeping ollama_local available for on-device workloads. A minimal configuration looks like this:

[general]
default_provider = "ollama_local"

[providers.ollama_local]
enabled = true
base_url = "http://localhost:11434"

[providers.ollama_cloud]
enabled = true
base_url = "https://ollama.com"
api_key_env = "OLLAMA_API_KEY"
hourly_quota_tokens = 50000
weekly_quota_tokens = 250000
list_ttl_secs = 60
default_context_window = 8192

Key points to keep in mind:

• Base URL normalisation – Owlen accepts https://ollama.com, https://ollama.com/api, https://ollama.com/v1, and the legacy https://api.ollama.com, canonicalising them to the correct HTTPS host. Local deployments get the same treatment for http://localhost:11434, /api, or /v1. You only need to customise base_url when the service is proxied elsewhere.
• Credential precedence – The resolver prefers an inline api_key first, then api_key_env, then the process environment in the order OLLAMA_API_KEY, OLLAMA_CLOUD_API_KEY, and OWLEN_OLLAMA_CLOUD_API_KEY. Set exactly one source to avoid surprises. When the ollama (local) provider is selected, any API key is ignored.
• Transport security – Hosted requests must use HTTPS unless the development-only flag OWLEN_ALLOW_INSECURE_CLOUD=1 is set. Leave this unset in production to avoid leaking credentials over cleartext channels.
• Web search endpoint – By default Owlen calls /api/web_search. If your deployment exposes the tool at /v1/web/search (Codex CLI style) or any other path, set providers.ollama_cloud.extra.web_search_endpoint. The session layer reuses the same normalisation logic, so whatever URL the provider accepts will also be used for tool consent checks.

The quota fields are optional and purely informational—they are never sent to the provider. Owlen uses them to display hourly/weekly token usage in the chat header, emit pre-limit toasts at 80% and 95%, and power the :limits command. Adjust the numbers to reflect the soft limits on your account or remove the keys altogether if you do not want usage tracking.

If your deployment exposes the web search endpoint under a different path, set web_search_endpoint in the same table. The default (/api/web_search) matches the Ollama Cloud REST API documented in the web retrieval guide. Tools must be registered with spec-compliant identifiers (for example web_search, browser_fetch); dotted names are rejected.citeturn11search0

Toggle the feature at runtime with :web on / :web off from the TUI or owlen providers web --enable/--disable on the CLI; both commands persist the change back to config.toml. See docs/mcp-reference.md for the full connector bundle, installation commands, and health checks.citeturn1search6turn1search8

Tip: If the official ollama signin flow fails on Linux v0.12.3, follow the Linux Ollama sign-in workaround in the troubleshooting guide to copy keys from a working machine or register them manually.

Managing cloud credentials via CLI

Owlen now ships with an interactive helper for Ollama Cloud:

owlen cloud setup --api-key <KEY>   # Configure your API key (uses stored value when omitted)
owlen cloud status         # Verify authentication/latency
owlen cloud models         # List the hosted models your account can access
owlen cloud logout         # Forget the stored API key

When privacy.encrypt_local_data = true, the API key is written to Owlen's encrypted credential vault instead of being persisted in plaintext. The vault key is generated and managed automatically—no passphrase prompts are ever shown—and subsequent invocations hydrate the runtime environment from that secure store. If encryption is disabled, the key is stored under [providers.ollama_cloud].api_key as before.