Skip to main content
Version: Next

Configuration Options

This page documents all available configuration options for Invowk™.

Configuration Schema​

The configuration file uses CUE format and follows the full effective config schema. You can omit defaulted fields in your own config.cue; CUE materializes those defaults before Go validation runs.

import "strings"

#ContainerEngineType: "podman" | "docker"
#ConfigRuntimeType: "native" | "virtual-sh" | "virtual-lua" | "container"
#ColorSchemeType: "auto" | "dark" | "light"
#LLMProviderType: "auto" | "claude" | "codex" | "gemini" | "ollama"
#LLMTimeoutDurationString: string & =~"^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$" & strings.MaxRunes(64)

#Config: close({
    container_engine: *"podman" | #ContainerEngineType
    includes: *([]) | [...#IncludeEntry]
    default_runtime: *"native" | #ConfigRuntimeType
    virtual: *#VirtualConfig | #VirtualConfig
    ui: *#UIConfig | #UIConfig
    container: *#ContainerConfig | #ContainerConfig
    llm: *#LLMDefaultsConfig | #LLMConfig
})

#IncludeEntry: close({
    path:   string  // Must be absolute and end with .invowkmod
    alias?: string  // Optional, for collision disambiguation
})

#VirtualConfig: close({
    utilities: *#VirtualUtilitiesConfig | #VirtualUtilitiesConfig
})

#VirtualUtilitiesConfig: close({
    enabled: *true | bool
})

#UIConfig: close({
    color_scheme: *"auto" | #ColorSchemeType
    verbose: *false | bool
    interactive: *false | bool
})

#LLMConfig: #LLMDefaultsConfig | #LLMProviderConfig | #LLMAPIBackendConfig

#LLMCommonConfig: {
    model?: string & !="" & strings.MaxRunes(256)
    timeout?: #LLMTimeoutDurationString
    concurrency?: int & >=0
}

#LLMDefaultsConfig: close({
    #LLMCommonConfig
})

#LLMProviderConfig: close({
    #LLMCommonConfig
    provider: #LLMProviderType
})

#LLMAPIBackendConfig: close({
    #LLMCommonConfig
    api: #LLMAPIConfig
})

#LLMAPIConfig: close({
    base_url?: string & !="" & strings.MaxRunes(2048)
    model?: string & !="" & strings.MaxRunes(256)
    api_key_env?: string & =~"^[A-Za-z_][A-Za-z0-9_]*$" & strings.MaxRunes(256)
})

#ContainerConfig: close({
    auto_provision: *#AutoProvisionConfig | #AutoProvisionConfig
})

#AutoProvisionConfig: close({
    enabled: *true | bool
    strict: *false | bool
    binary_path: *"" | (string & !="")
    includes: *([]) | [...#IncludeEntry]
    inherit_includes: *true | bool
    cache_dir: *"" | (string & !="")
})

Unknown fields are rejected, so keep config files limited to the schema-defined options.

Options Reference​

container_engine​

Type: "podman" | "docker" Default: "podman"

Specifies which container runtime to use for container-based command execution.

container_engine: "podman"

If the preferred engine is not available, Invowk falls back to the other engine when container runtime is needed.

includes​

Type: [...#IncludeEntry] Default: []

Additional modules to include in command discovery. Each entry is an #IncludeEntry with a required path (must end with .invowkmod) and optional alias.

includes: [
    {path: "/home/user/.invowk/modules/tools.invowkmod"},
    {path: "/home/user/projects/shared.invowkmod", alias: "shared"},
    {path: "/opt/company/tools.invowkmod"},
]

Path requirements:

  • Must be absolute (e.g., /home/user/modules/tools.invowkmod)
  • On Windows, use an absolute Windows path (e.g., C:\Users\alice\modules\tools.invowkmod or a UNC path)
  • Must end with .invowkmod
  • Duplicate paths are rejected

Alias rules:

  • Optional, for collision disambiguation
  • Must be unique across all includes entries

Discovery Order:

  1. Current directory invowkfile (always searched first, highest priority)
  2. Local modules (*.invowkmod in current directory)
  3. Each entry in includes in order
  4. ~/.invowk/cmds/ (modules only, non-recursive)

When multiple includes define commands with the same name, they become ambiguous. Use @source prefix or --ivk-from flag to disambiguate.

default_runtime​

Type: "native" | "virtual-sh" | "virtual-lua" | "container" Default: "native"

Sets the global default runtime mode for commands that don't specify a runtime.

default_runtime: "native"

Runtime Options:

  • "native" - Execute using the system's native shell (bash, zsh, PowerShell, etc.)
  • "virtual-sh" - Execute using Invowk's built-in shell interpreter (mvdan/sh)
  • "virtual-lua" - Execute using Invowk's built-in Lua interpreter
  • "container" - Execute inside a container (requires Docker or Podman)
note

Commands can override this default by specifying their own runtime in the implementations field.

virtual​

Type: #VirtualConfig Default: {utilities: {enabled: true}}

Configures the virtual runtime family behavior.

virtual: {
    utilities: {
        enabled: true
    }
}

virtual.utilities.enabled​

Type: bool Default: true

Enables u-root utilities in virtual-sh and command helpers in virtual-lua. When enabled, 28 additional POSIX-compliant commands become available to virtual-sh:

Upstream wrappers (12): base64, cat, cp, find, gzip, ls, mkdir, mv, rm, shasum, tar, touch

Custom implementations (16): basename, cut, dirname, grep, head, ln, mktemp, realpath, seq, sleep, sort, tail, tee, tr, uniq, wc

This makes virtual-sh self-contained for common file, text, and utility operations without requiring external binaries on the host system. In virtual-lua, the same setting controls whether those utilities are available through invowk.cmd and invowk.capture; host binaries still require allowed_binaries.

tip

u-root utilities are enabled by default. Set to false only if you want virtual scripts to use explicitly allowed host binaries or reduce binary size.

ui​

Type: #UIConfig Default: {color_scheme: "auto", verbose: false, interactive: false}

Configures the user interface settings.

ui: {
    color_scheme: "auto"
    verbose: false
    interactive: false
}

ui.color_scheme​

Type: "auto" | "dark" | "light" Default: "auto"

Sets the color scheme for Invowk's output.

ui: {
    color_scheme: "auto"
}

Options:

  • "auto" - Detect from terminal settings (respects COLORTERM, TERM, etc.)
  • "dark" - Use colors optimized for dark terminals
  • "light" - Use colors optimized for light terminals

ui.verbose​

Type: bool Default: false

Enables verbose output by default. When enabled, Invowk prints additional information about command discovery, dependency validation, and execution.

ui: {
    verbose: true
}

This is equivalent to always passing --ivk-verbose on the command line.

ui.interactive​

Type: bool Default: false

Enables interactive mode by default. When enabled, commands run in an alternate screen buffer with full PTY support, allowing interactive programs like password prompts, confirmations, and other stdin-based interactions to work properly.

ui: {
    interactive: true
}

This is equivalent to always passing --ivk-interactive on the command line.

llm​

Type: #LLMConfig Default: {}

Configures a default LLM backend for LLM-aware commands. invowk agent cmd create uses this config automatically when no LLM flags are passed. invowk audit still requires explicit opt-in with --llm or --llm-provider before any script content is sent to an LLM.

Use a supported provider harness:

llm: {
    provider: "codex"
    model: "gpt-5.1-codex" // optional for CLI harnesses
    timeout: "2m"
    concurrency: 2
}

Or use an OpenAI-compatible API endpoint:

llm: {
    api: {
        base_url: "https://api.openai.com/v1"
        model: "gpt-5.1"
        api_key_env: "OPENAI_API_KEY"
    }
}

llm.provider and llm.api are mutually exclusive. Do not store raw API keys in config.cue; use llm.api.api_key_env to name an environment variable instead.

llm.provider​

Type: "auto" | "claude" | "codex" | "gemini" | "ollama" Default: (unset)

Selects a supported provider/harness. auto probes local Ollama, cloud credentials, and CLI tools in provider order.

llm.model​

Type: string Default: (unset)

Sets the common model default for the configured backend. CLI harnesses use their own current default when omitted, and API/Ollama flows use the resolver fallback qwen2.5-coder:7b when no model is configured or flagged. When llm.api.model is also set, the API-specific model overrides this value.

llm.timeout​

Type: Go duration string (#LLMTimeoutDurationString, max 64 runes) Default: (unset in config; resolver fallback: 2m)

Sets the per-request timeout used by LLM-backed commands.

llm.concurrency​

Type: int Default: (unset in config; resolver fallback: 2)

Limits concurrent LLM requests. Set 0 or omit the field to use the built-in default.

llm.api​

Type: #LLMAPIConfig Default: (unset)

Configures an OpenAI-compatible API endpoint with base_url, model, and api_key_env. If api is present, set at least one of those fields.

llm.api.base_url​

Type: string Default: (unset in config; resolver fallback: http://localhost:11434/v1)

OpenAI-compatible API base URL.

llm.api.model​

Type: string Default: (unset in config; resolver fallback: qwen2.5-coder:7b)

Model name sent to the API endpoint. When set, this overrides the common llm.model default for API-backed execution.

llm.api.api_key_env​

Type: string Default: (unset)

Environment variable name that holds the API key.

container​

Type: #ContainerConfig Default: {auto_provision: {enabled: true, strict: false, binary_path: "", includes: [], inherit_includes: true, cache_dir: ""}}

Configures container runtime behavior.

container: {
    auto_provision: {
        enabled: true
        strict: false
        binary_path: "/usr/local/bin/invowk"
        includes: [
            {path: "/opt/company/modules/tools.invowkmod"},
        ]
        inherit_includes: true
        cache_dir: "/tmp/invowk/provision"
    }
}

container.auto_provision.enabled​

Type: bool Default: true

Enables automatic provisioning of the invowk binary and modules into container images. When enabled, Invowk builds a cached, derived image for every container run by attaching a small provisioned layer on top of your base image. If provisioning fails, Invowk warns and uses the base image.

container.auto_provision.binary_path​

Type: string Default: (empty; uses the running invowk binary)

Overrides the path to the invowk binary to provision into containers.

container.auto_provision.includes​

Type: [...#IncludeEntry] Default: []

Additional modules to provision into containers. Uses the same #IncludeEntry format as root includes (each entry has a path ending with .invowkmod and an optional alias).

container.auto_provision.inherit_includes​

Type: bool Default: true

When true, the root-level includes entries are automatically inherited by auto-provisioning. Set to false to provision only the modules explicitly listed in container.auto_provision.includes.

container.auto_provision.strict​

Type: bool Default: false

When true, auto-provisioning failures are treated as hard errors instead of warnings. By default, if provisioning fails, Invowk warns and runs the base image. With strict: true, the command fails immediately on provisioning failure.

container.auto_provision.cache_dir​

Type: string Default: (empty — uses platform-specific default, typically ~/.cache/invowk/provision)

Overrides the parent directory used for provision build contexts and cached image metadata.

Complete Example​

Here's a complete configuration file with all options:

// Invowk Configuration File
// =========================
// Location: ~/.config/invowk/config.cue

// Container Engine
// ----------------
// Which container runtime to use: "podman" or "docker"
container_engine: "podman"

// Includes
// --------
// Additional modules to include in discovery.
// Each entry specifies a path to an *.invowkmod directory.
// Modules may have an optional alias for collision disambiguation.
includes: [
    // Personal modules
    {path: "/home/user/.invowk/modules/tools.invowkmod"},

    // Team shared module (with alias)
    {path: "/home/user/work/shared.invowkmod", alias: "team"},

    // Organization-wide module
    {path: "/opt/company/tools.invowkmod"},
]

// Default Runtime
// ---------------
// The runtime to use when a command doesn't specify one
// Options: "native", "virtual-sh", "virtual-lua", "container"
default_runtime: "native"

// Virtual Runtime Configuration
// ---------------------------
// Settings for the virtual runtime family
virtual: {
    utilities: {
        // Enable built-in utilities for virtual runtimes
        // Provides ls, cat, grep, etc. in virtual-sh and command helpers in virtual-lua
        enabled: true
    }
}

// UI Configuration
// ----------------
// User interface settings
ui: {
    // Color scheme: "auto", "dark", or "light"
    // "auto" detects from terminal settings
    color_scheme: "auto"
    
    // Enable verbose output by default
    // Same as always passing --ivk-verbose
    verbose: false

    // Enable interactive mode by default
    interactive: false
}

// Example LLM backend override
// ----------------------------
// Used by invowk agent cmd create and by invowk audit --llm.
// Default config uses llm: {} until a provider or API is configured.
// Bare invowk audit remains deterministic and does not call LLMs.
llm: {
    provider: "codex"
    model: "gpt-5.1-codex"
    timeout: "2m"
    concurrency: 2
}

// Container provisioning
// ----------------------
container: {
    auto_provision: {
        enabled: true
        strict: false
        binary_path: ""
        includes: []
        inherit_includes: true
        cache_dir: ""
    }
}