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

Run owlen config path to print the exact location on your machine. A default configuration file is created on the first run if one doesn't exist, and owlen config doctor can migrate/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.

• show_role_labels (boolean, default: true) Whether to show the user and bot role labels next to messages.

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

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 ships with two entries pre-populated: ollama for a local daemon and ollama-cloud for the hosted API. You can switch between them by changing general.default_provider.

[providers.ollama]
provider_type = "ollama"
base_url = "http://localhost:11434"
# api_key = "..."

[providers.ollama-cloud]
provider_type = "ollama-cloud"
base_url = "https://ollama.com"
# api_key = "${OLLAMA_API_KEY}"

• provider_type (string, required) The type of the provider. The built-in options are "ollama" (local daemon) and "ollama-cloud" (hosted service).

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

• api_key (string, optional) The API key to use for authentication, if required. Note: ollama-cloud now requires an API key; Owlen will refuse to start the provider without one and will hint at the missing configuration.

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

Using Ollama Cloud

Owlen now ships a single unified ollama provider. When an API key is present, Owlen automatically routes traffic to Ollama Cloud; otherwise it talks to the local daemon. A minimal configuration looks like this:

[providers.ollama]
provider_type = "ollama"
base_url = "http://localhost:11434"   # ignored once an API key is supplied
api_key = "${OLLAMA_API_KEY}"

Requests target the same /api/chat endpoint documented by Ollama and automatically include the API key using a Bearer authorization header. If you prefer not to store the key in the config file, you can leave api_key unset and provide it via the OLLAMA_API_KEY (or OLLAMA_CLOUD_API_KEY) environment variable instead. You can also reference an environment variable inline (for example api_key = "$OLLAMA_API_KEY" or api_key = "${OLLAMA_API_KEY}"), which Owlen expands when the configuration is loaded. The base URL is normalised automatically—Owlen enforces HTTPS, trims trailing slashes, and accepts both https://ollama.com and https://api.ollama.com without rewriting the host.

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          # Prompt for your API key (or use --api-key)
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. Subsequent invocations automatically load the key into the runtime environment so that the config file can remain redacted. If encryption is disabled, the key is stored under [providers.ollama-cloud].api_key as before.