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

By default, Owlen looks for its configuration file at ~/.config/owlen/config.toml.

A default configuration file is created on the first run if one doesn't exist.

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.

---

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.

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

Using Ollama Cloud

To talk to Ollama Cloud, point the base URL at the hosted endpoint and supply your API key:

[providers.ollama-cloud]
provider_type = "ollama-cloud"
base_url = "https://ollama.com"
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.