Version: Next

Configuration Schema Reference

:::warning Alpha — Configuration Options May Change The configuration schema is still being refined. Options may be added, renamed, or removed between releases as we finalize the feature set. :::

Complete reference for the Invowk™ configuration file schema.

Overview

The configuration file uses CUE format and is located at:

Platform	Location
Linux/other Unix-like	`$XDG_CONFIG_HOME/invowk/config.cue` when set, otherwise `~/.config/invowk/config.cue`
macOS	`~/Library/Application Support/invowk/config.cue`
Windows	`%APPDATA%\invowk\config.cue`

Configuration files are validated as closed structs, so unknown fields cause a validation error. The schema is the full effective configuration shape: user files may omit defaulted fields, and CUE materializes those defaults before Go validation runs.

Schema Definition

// Root configuration structure
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
})

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

// Virtual runtime family configuration
#VirtualConfig: close({
    utilities: *#VirtualUtilitiesConfig | #VirtualUtilitiesConfig
})

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

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

// LLM configuration
#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
})

// OpenAI-compatible API configuration
#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)
})

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

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

Config

The root configuration object.

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

Fields marked as not required below may be omitted from a user-authored config.cue; they are still present in the effective Config after schema defaults are applied.

container_engine

Type: "podman" | "docker" Required: No 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] Required: No Default: []

Additional modules to include in command discovery. Each entry specifies a path to an *.invowkmod directory with an optional alias for collision disambiguation.

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

Path requirements:

Paths must be absolute and end with .invowkmod
Non-existent paths are silently ignored
Duplicate paths are rejected

Alias rules:

Aliases are optional, for collision disambiguation
Each alias must be unique across all includes entries
Aliases override the module's declared identifier for collision resolution

Discovery priority (highest to lowest):

Current directory invowkfile
Local modules (*.invowkmod in current directory)
Configured includes (in order) — explicit includes outrank the user directory
~/.invowk/cmds (modules only, non-recursive)

default_runtime

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

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

default_runtime: "native"

Value	Description
`"native"`	Execute using the system's native shell
`"virtual-sh"`	Execute using Invowk's built-in shell interpreter
`"virtual-lua"`	Execute using Invowk's built-in Lua interpreter
`"container"`	Execute inside a container

virtual

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

Configuration for the virtual runtime family.

virtual: {
    utilities: {
        enabled: true
    }
}

ui

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

User interface configuration.

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

llm

Type: #LLMConfig Required: No Default: {}

Default LLM backend configuration for LLM-aware commands. invowk agent cmd create uses this config when no LLM flags are passed. invowk audit still requires explicit opt-in with --llm or --llm-provider before it sends script content to an LLM.

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

Use llm.api for OpenAI-compatible endpoints when you want to configure an API backend without storing raw secrets in config.cue.

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

container

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

Container runtime configuration.

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

VirtualConfig

Configuration for the virtual runtime family.

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

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

utilities.enabled

Type: bool Required: No Default: true

Enables u-root utilities in virtual-sh and command helpers in virtual-lua.

virtual: {
    utilities: {
        enabled: true
    }
}

Available utilities when enabled (28 total):

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

UIConfig

User interface configuration.

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

color_scheme

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

Sets the color scheme for terminal output.

ui: {
    color_scheme: "auto"
}

Value	Description
`"auto"`	Detect from terminal (respects `COLORTERM`, `TERM`, etc.)
`"dark"`	Colors optimized for dark terminals
`"light"`	Colors optimized for light terminals

verbose

Type: bool Required: No Default: false

Enables verbose output by default for all commands.

ui: {
    verbose: true
}

Equivalent to always passing --ivk-verbose on the command line.

interactive

Type: bool Required: No Default: false

Enables interactive mode by default (alternate screen buffer with PTY).

ui: {
    interactive: true
}

LLMConfig

Common LLM defaults and backend configuration. DefaultConfig() derives this from CUE and produces an empty defaults-only llm: {} object until the user configures a provider or API endpoint.

import "strings"

#LLMTimeoutDurationString: string & =~"^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$" & strings.MaxRunes(64)

#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
})

provider

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

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

model

Type: string Required: No Default: (unset)

Overrides the provider model. CLI harnesses use their own default when omitted.

timeout

Type: Go duration string Required: No Default: (unset in config; resolver fallback: 2m)

Sets the per-request timeout for LLM-backed commands.

concurrency

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

Limits concurrent LLM requests. Set 0 or omit the field to use the resolver fallback.

api

Type: #LLMAPIConfig Required: No Default: (unset)

OpenAI-compatible API endpoint configuration. provider and api are mutually exclusive. If api is present, set at least one of base_url, model, or api_key_env.

LLMAPIConfig

Configuration for an OpenAI-compatible API backend.

import "strings"

#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)
})

base_url

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

OpenAI-compatible API base URL.

model

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

Model name sent to the API endpoint.

api_key_env

Type: string Required: No Default: (unset)

Name of the environment variable containing the API key. Use this instead of storing raw API keys in config.cue.

ContainerConfig

Configuration for container runtime behavior.

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

auto_provision

Type: #AutoProvisionConfig Required: No Default: {enabled: true, strict: false, binary_path: "", includes: [], inherit_includes: true, cache_dir: ""}

Controls automatic provisioning of invowk resources into containers.

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"
    }
}

With auto-provisioning enabled, Invowk builds a cached, derived image by attaching a small provisioned layer on top of your base image. This runs for every container execution (interactive or not); if provisioning fails, Invowk warns and uses the base image.

AutoProvisionConfig

Auto-provisioning configuration for container images.

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

enabled

Type: bool Required: No Default: true

Enables auto-provisioning of the invowk binary and modules into containers.

strict

Type: bool Required: No Default: false

Makes provisioning failure a hard error instead of falling back to the unprovisioned base image. When false (the default), provisioning failure logs a warning and continues with the base image.

binary_path

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

Overrides the path to the invowk binary to provision.

includes

Type: [...#IncludeEntry] Required: No 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).

inherit_includes

Type: bool Required: No 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.

cache_dir

Type: string Required: No 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

A fully documented configuration file:

// 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: ""
    }
}

Minimal Configuration

If you're happy with defaults, a minimal config might be:

// Just override what you need
container_engine: "docker"

Or even an empty file (all defaults):

// Empty config - use all defaults

Validation

You can validate your configuration file using CUE:

cue vet ~/.config/invowk/config.cue

Or check it with Invowk:

invowk config show

If there are any errors, Invowk will report them when loading the configuration.

Overview​

Schema Definition​

Config​

container_engine​

includes​

default_runtime​

virtual​

ui​

llm​

container​

VirtualConfig​

utilities.enabled​

UIConfig​

color_scheme​

verbose​

interactive​

LLMConfig​

provider​

model​

timeout​

concurrency​

api​

LLMAPIConfig​

base_url​

model​

api_key_env​

ContainerConfig​

auto_provision​

AutoProvisionConfig​

enabled​

strict​

binary_path​

includes​

inherit_includes​

cache_dir​

Complete Example​

Minimal Configuration​

Validation​

Overview

Schema Definition

Config

container_engine

includes

default_runtime

virtual

ui

llm

container

VirtualConfig

utilities.enabled

UIConfig

color_scheme

verbose

interactive

LLMConfig

provider

model

timeout

concurrency

api

LLMAPIConfig

base_url

model

api_key_env

ContainerConfig

auto_provision

AutoProvisionConfig

enabled

strict

binary_path

includes

inherit_includes

cache_dir

Complete Example

Minimal Configuration

Validation