Versão: 0.14.0

Referência de Schema de Configuração

:::warning Alpha — Opções de Configuração Podem Mudar O schema de configuração ainda está sendo refinado. Opções podem ser adicionadas, renomeadas ou removidas entre releases enquanto finalizamos o conjunto de funcionalidades. :::

Referência completa para o schema do arquivo de configuração do Invowk™.

Visão Geral

O arquivo de configuração usa formato CUE e está localizado em:

Plataforma	Localização
Linux/outros Unix-like	`$XDG_CONFIG_HOME/invowk/config.cue` quando definido; caso contrário `~/.config/invowk/config.cue`
macOS	`~/Library/Application Support/invowk/config.cue`
Windows	`%APPDATA%\invowk\config.cue`

Arquivos de configuração são validados com structs fechadas, então campos desconhecidos geram erro de validação. O schema descreve a forma efetiva completa da configuração: arquivos de usuário podem omitir campos com padrão, e o CUE materializa esses padrões antes da validação em Go.

Definição do Schema

// 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

O objeto de configuração raiz.

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

Campos marcados como não obrigatórios abaixo podem ser omitidos em um config.cue escrito pelo usuário; eles ainda ficam presentes no Config efetivo depois que os padrões do schema são aplicados.

container_engine

Tipo: "podman" | "docker" Obrigatório: Não Padrão: "podman"

Especifica qual container runtime usar para execução de comandos baseada em container.

container_engine: "podman"

Se a engine preferida não estiver disponível, o Invowk faz fallback para a outra quando o runtime container é necessário.

includes

Tipo: [...#IncludeEntry] Obrigatório: Não Padrão: []

Módulos adicionais para incluir na descoberta de comandos. Cada entrada especifica um caminho para um diretório *.invowkmod com um alias opcional para desambiguação de colisões.

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

Requisitos de caminho:

Caminhos devem ser absolutos e terminar com .invowkmod
Caminhos inexistentes são ignorados silenciosamente
Caminhos duplicados são rejeitados

Regras de alias:

Aliases são opcionais, para desambiguação de colisões
Cada alias deve ser único entre todas as entradas includes

Prioridade de descoberta (maior para menor):

invowkfile do diretório atual
Módulos locais (*.invowkmod no diretório atual)
includes configurados (em ordem) — includes explícitos superam o diretório do usuário
~/.invowk/cmds (apenas módulos, não-recursivo)

default_runtime

Tipo: "native" | "virtual-sh" | "virtual-lua" | "container" Obrigatório: Não Padrão: "native"

Define o modo de runtime padrão global para comandos que não especificam um runtime preferido.

default_runtime: "native"

Valor	Descrição
`"native"`	Executar usando o shell nativo do sistema
`"virtual-sh"`	Executar usando o interpretador de shell embutido do Invowk
`"virtual-lua"`	Executar usando o interpretador Lua embutido do Invowk
`"container"`	Executar dentro de um container

virtual

Tipo: #VirtualConfig Obrigatório: Não Padrão: {utilities: {enabled: true}}

Configuração para a família de runtimes virtuais.

virtual: {
    utilities: {
        enabled: true
    }
}

ui

Tipo: #UIConfig Obrigatório: Não Padrão: {color_scheme: "auto", verbose: false, interactive: false}

Configuração de interface do usuário.

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

llm

Tipo: #LLMConfig Obrigatório: Não Padrão: {}

Configuração padrão de backend LLM para comandos que usam LLM. invowk agent cmd create usa essa configuração quando nenhuma flag LLM é passada. invowk audit ainda exige opt-in explícito com --llm ou --llm-provider antes de enviar conteúdo de script para uma LLM.

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

Use llm.api para endpoints compatíveis com OpenAI quando quiser configurar um backend de API sem armazenar segredos brutos em config.cue.

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

container

Tipo: #ContainerConfig Obrigatório: Não Padrão: {auto_provision: {enabled: true, strict: false, binary_path: "", includes: [], inherit_includes: true, cache_dir: ""}}

Configuração para o runtime container.

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

VirtualConfig

Configuração para a família de runtimes virtuais.

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

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

utilities.enabled

Tipo: bool Obrigatório: Não Padrão: true

Habilita utilitários u-root no virtual-sh e helpers de comando no virtual-lua.

virtual: {
    utilities: {
        enabled: true
    }
}

Utilitários disponíveis quando habilitado (28 no total):

Wrappers upstream (12): base64, cat, cp, find, gzip, ls, mkdir, mv, rm, shasum, tar, touch
Implementações customizadas (16): basename, cut, dirname, grep, head, ln, mktemp, realpath, seq, sleep, sort, tail, tee, tr, uniq, wc

UIConfig

Configuração de interface do usuário.

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

color_scheme

Tipo: "auto" | "dark" | "light" Obrigatório: Não Padrão: "auto"

Define o esquema de cores para saída de terminal.

ui: {
    color_scheme: "auto"
}

Valor	Descrição
`"auto"`	Detectar do terminal (respeita `COLORTERM`, `TERM`, etc.)
`"dark"`	Cores otimizadas para terminais escuros
`"light"`	Cores otimizadas para terminais claros

verbose

Tipo: bool Obrigatório: Não Padrão: false

Habilita saída verbose por padrão para todos os comandos.

ui: {
    verbose: true
}

Equivalente a sempre passar --ivk-verbose na linha de comando.

interactive

Tipo: bool Obrigatório: Não Padrão: false

Habilita o modo interativo por padrão (buffer de tela alternativo com PTY).

ui: {
    interactive: true
}

LLMConfig

Defaults comuns de LLM e configuração de backend. DefaultConfig() deriva esse valor do CUE e produz um objeto llm: {} vazio, apenas com defaults, até o usuário configurar um provedor ou endpoint de API.

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

Tipo: "auto" | "claude" | "codex" | "gemini" | "ollama" Obrigatório: Não Padrão: (não definido)

Seleciona um provedor ou harness CLI suportado. auto procura Ollama local, credenciais de API cloud e ferramentas CLI na ordem de provedores.

model

Tipo: string Obrigatório: Não Padrão: (não definido)

Substitui o modelo do provedor. Harnesses CLI usam seu próprio padrão quando omitido.

timeout

Tipo: string de duração Go Obrigatório: Não Padrão: (não definido na configuração; fallback do resolvedor: 2m)

Define o timeout por requisição para comandos com LLM.

concurrency

Tipo: int Obrigatório: Não Padrão: (não definido na configuração; fallback do resolvedor: 2)

Limita requisições LLM concorrentes. Defina 0 ou omita o campo para usar o fallback do resolvedor.

api

Tipo: #LLMAPIConfig Obrigatório: Não Padrão: (não definido)

Configuração de endpoint de API compatível com OpenAI. provider e api são mutuamente exclusivos. Se api estiver presente, defina pelo menos um de base_url, model ou api_key_env.

LLMAPIConfig

Configuração para um backend de API compatível com OpenAI.

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

Tipo: string Obrigatório: Não Padrão: (não definido na configuração; fallback do resolvedor: http://localhost:11434/v1)

URL base da API compatível com OpenAI.

model

Tipo: string Obrigatório: Não Padrão: (não definido na configuração; fallback do resolvedor: qwen2.5-coder:7b)

Nome do modelo enviado ao endpoint de API.

api_key_env

Tipo: string Obrigatório: Não Padrão: (não definido)

Nome da variável de ambiente que contém a chave de API. Use isso em vez de armazenar chaves brutas em config.cue.

ContainerConfig

Configuração para comportamento do runtime container.

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

auto_provision

Tipo: #AutoProvisionConfig Obrigatório: Não Padrão: {enabled: true, strict: false, binary_path: "", includes: [], inherit_includes: true, cache_dir: ""}

Controla o provisionamento automático de recursos do invowk dentro de 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"
    }
}

Com o auto-provisionamento habilitado, o Invowk cria uma imagem derivada em cache ao anexar uma pequena camada de provisionamento sobre a imagem base. Isso ocorre em toda execução de container (interativa ou não); se o provisionamento falhar, o Invowk avisa e usa a imagem base.

AutoProvisionConfig

Configuração de auto-provisionamento para imagens container.

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

enabled

Tipo: bool Obrigatório: Não Padrão: true

Habilita o provisionamento automático do binário do invowk e módulos em containers.

strict

Tipo: bool Obrigatório: Não Padrão: false

Faz com que falhas de provisionamento sejam erros fatais em vez de fazer fallback para a imagem base sem provisionamento. Quando false (o padrão), falhas de provisionamento geram um aviso e continuam com a imagem base.

binary_path

Tipo: string Obrigatório: Não Padrão: (vazio; usa o binário do invowk em execução)

Sobrescreve o caminho do binário do invowk para provisionar.

includes

Tipo: [...#IncludeEntry] Obrigatório: Não Padrão: []

Módulos adicionais para provisionar em containers. Usa o mesmo formato #IncludeEntry do includes raiz (cada entrada tem um path terminando com .invowkmod e um alias opcional).

inherit_includes

Tipo: bool Obrigatório: Não Padrão: true

Quando true, as entradas de includes do nível raiz são automaticamente herdadas pelo auto-provisionamento. Defina como false para provisionar apenas os módulos listados explicitamente em container.auto_provision.includes.

cache_dir

Tipo: string Obrigatório: Não Padrão: (vazio — usa o padrão específico da plataforma, tipicamente ~/.cache/invowk/provision)

Sobrescreve o diretório pai usado para contextos de build de provisionamento e metadados de imagens em cache.

Exemplo Completo

Um arquivo de configuração totalmente documentado:

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

Configuração Mínima

Se você está satisfeito com os padrões, uma configuração mínima pode ser:

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

Ou até mesmo um arquivo vazio (todos os padrões):

// Empty config - use all defaults

Validação

Você pode validar seu arquivo de configuração usando CUE:

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

Ou verificá-lo com Invowk:

invowk config show

Se houver algum erro, Invowk irá reportá-los ao carregar a configuração.

Visão Geral​

Definição do Schema​

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​

Exemplo Completo​

Configuração Mínima​

Validação​

Visão Geral

Definição do Schema

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

Exemplo Completo

Configuração Mínima

Validação