Documentation
¶
Overview ¶
Package config loads zot's configuration, layering built-in defaults, an optional YAML file, and environment variables (defaults < file < env).
Index ¶
- func ConfigDir(path string) string
- func DefaultConfigPath() string
- func DefaultSessionDir() string
- func Portable() bool
- func ProviderCredential(provider ProviderConfig) string
- func ProviderDriver(name string, provider ProviderConfig) string
- func ProviderModels(name string, provider ProviderConfig) []string
- func ScrubProviderSecrets(cfg Config)
- type Agent
- type Attribution
- type Config
- type ModelConfig
- type ProviderConfig
- type UI
- type UpdateCheck
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConfigDir ¶
ConfigDir returns the directory that holds the config file - and any global AGENTS.md / skills - for the given --config value ("" uses the default path).
func DefaultConfigPath ¶
func DefaultConfigPath() string
DefaultConfigPath returns the resolved config file path using a fallback chain:
- $ZOT_CONFIG environment variable (if set and non-empty)
- $XDG_CONFIG_HOME/zot/config.yaml (if XDG_CONFIG_HOME is set)
- ~/.config/zot/config.yaml
func DefaultSessionDir ¶
func DefaultSessionDir() string
DefaultSessionDir returns where session logs are written:
- $ZOT_SESSION_DIR (if set and non-empty)
- $XDG_STATE_HOME/zot/sessions (if XDG_STATE_HOME is set)
- ~/.local/state/zot/sessions
State rather than config, because a session log is something zot produces and may prune, not something the user edits. Keeping run logs out of the config directory also means a synced dotfiles setup does not carry transcripts of every run to every machine.
func Portable ¶ added in v0.8.0
func Portable() bool
Portable reports whether this binary carries a compiled-in configuration - a portable build (see portableConfig). Surfaced on `zot --version` so "why is it ignoring my config file" is answerable without reading the source.
func ProviderCredential ¶ added in v0.11.0
func ProviderCredential(provider ProviderConfig) string
ProviderCredential returns the credential configured for a provider.
func ProviderDriver ¶ added in v0.11.0
func ProviderDriver(name string, provider ProviderConfig) string
ProviderDriver resolves which implementation a named provider uses.
A provider named after a driver uses that driver, so the common case needs no configuration at all. An aliased connection states its driver explicitly.
func ProviderModels ¶ added in v0.11.0
func ProviderModels(name string, provider ProviderConfig) []string
ProviderModels returns the names exposed by a provider. An explicit custom list replaces the built-in catalogue for that connection; otherwise the provider's resolved driver selects its built-in models.
func ScrubProviderSecrets ¶ added in v0.11.0
func ScrubProviderSecrets(cfg Config)
ScrubProviderSecrets removes every resolved provider credential, both provider-level and per-model, from the process environment. Config retains the resolved values used by the SDK client, while shell commands launched by the agent no longer inherit those credentials.
Types ¶
type Agent ¶
type Agent struct {
// Model is the model name driving the agent.
Model string `yaml:"model"`
// MaxIterations caps how many plan/act/observe cycles the agent may run
// before it is forced to stop.
MaxIterations int `yaml:"max_iterations"`
// MaxSettles bounds how many times the agent is nudged to record an outcome
// (call success or failure) before the run is surfaced as unsettled. This
// is "how hard we push the model to finish properly". Zero uses the built-in
// default.
MaxSettles int `yaml:"max_settles"`
// MaxCalls caps the total number of tool calls across a run, independently of
// iterations (one iteration can request several). Zero is unbounded - only
// max_iterations is a finite default.
MaxCalls int `yaml:"max_calls"`
// MaxTime caps the wall-clock time of a run, as a duration string ("30m",
// "2h", "90s"). Empty is unbounded.
MaxTime string `yaml:"max_time"`
// MaxTokens caps the output tokens of a single model response. Zero is
// unbounded - like max_calls and max_time, zot sends no cap, so the model
// produces its full output. A positive value caps a single response.
MaxTokens int `yaml:"max_tokens"`
// MaxToolOutput caps the bytes a single tool result may return before it is
// truncated. Zero uses the built-in default. Lower it for a model served by
// an endpoint with a small context window, where one large result can
// overflow the whole request and be rejected wholesale.
MaxToolOutput int `yaml:"max_tool_output"`
// MaxContinuations caps CONSECUTIVE recovery attempts - a truncated
// response, or a retriable provider error - with no good turn between
// them; a turn that comes back whole resets the count. Zero uses the
// built-in default.
MaxContinuations int `yaml:"max_continuations"`
// MaxRecoveries caps recovery attempts across a whole run, however they are
// spaced - where max_continuations catches a provider refusing right now,
// this catches one that answers just often enough to keep resetting it.
// Zero uses the built-in default.
MaxRecoveries int `yaml:"max_recoveries"`
// MaxCycles is how many times the loop nudges the model out of a detected
// repetition before giving up. Zero uses the built-in default. A safety
// guard - the default encodes a real failure, so raise it with care.
MaxCycles int `yaml:"max_cycles"`
// MaxEmpties caps consecutive empty turns before the run bails. Zero uses the
// built-in default.
MaxEmpties int `yaml:"max_empties"`
// LimitCheckpoints are the percentages of a bounded limit (iterations, calls,
// time) at which the model is told it is approaching that limit, so it can
// pace itself. Unset uses the built-in default (50, 80, 90); an explicit
// empty list turns the notices off.
LimitCheckpoints []int `yaml:"limit_checkpoints"`
// ContextStrategy decides what happens when the conversation approaches the
// model's context window: "compact" summarises the older history into a
// checkpoint (an extra model call, higher fidelity), "truncate" simply drops
// the oldest messages to fit. Empty uses the default, "compact".
ContextStrategy string `yaml:"context_strategy"`
// CompactMinTokens is the floor of estimated input tokens below which the
// compact strategy does not bother summarising - a short conversation is
// cheaper to carry whole than to summarise. Zero uses the built-in default.
CompactMinTokens int `yaml:"compact_min_tokens"`
// CompactMinMessages is the floor on how many messages must be eligible for
// summarising before the compact strategy runs. Zero uses the default.
CompactMinMessages int `yaml:"compact_min_messages"`
// CompactTriggerRatio is the fraction of the context window at which the
// compact strategy fires (0.9 = compact once the estimate reaches 90% of the
// window). Zero uses the default. Must be within (0, 1].
CompactTriggerRatio float64 `yaml:"compact_trigger_ratio"`
// Instructions optionally overrides the built-in system prompt. Leave
// empty to use zot.DefaultInstructions. An override replaces the prompt
// but not zot's non-interactive contract, which is re-attached to whatever
// a run resolves to: the run has no input channel to opt back into.
Instructions string `yaml:"instructions"`
}
Agent holds the knobs that shape an autonomous run.
type Attribution ¶ added in v0.17.1
type Attribution struct {
// Name is the app name a gateway lists. Empty sends "zot".
Name string `yaml:"name"`
// URL is the project link a gateway lists. Empty sends zot's repository.
URL string `yaml:"url"`
// Disabled sends no attribution headers at all.
Disabled bool `yaml:"disabled"`
}
Attribution is the app identity sent to gateways that publish rankings from it - OpenRouter's site rankings, Vercel's AI Gateway leaderboards. Nothing about the user or the run travels with it: it is the same two values for every zot in the world, and it is sent only to those gateways.
type Config ¶
type Config struct {
Agent Agent `yaml:"agent"`
UI UI `yaml:"ui"`
// Skills discovered from the context directories. Not configured directly:
// LoadProjectContext fills this from the SKILL.md files it finds, and the
// engine describes them in the system prompt.
Skills []agent.SkillDefinition `yaml:"-"`
// DefaultProvider is the provider used when --provider is not given.
DefaultProvider string `yaml:"default_provider"`
// Providers are the named model-provider connections a run can target. zot
// ships with one for each provider it knows, and a config file can override
// their credentials or endpoint, or add custom model entries.
Providers map[string]ProviderConfig `yaml:"providers"`
// Attribution is how zot names itself to a gateway that ranks the apps
// calling it. The zero value sends zot's own name and project URL.
Attribution Attribution `yaml:"attribution"`
// UpdateCheck controls the release check a run makes against GitHub. The
// zero value checks.
UpdateCheck UpdateCheck `yaml:"update_check"`
}
Config is the fully-resolved zot configuration.
func Defaults ¶
func Defaults() Config
Defaults returns the built-in configuration used when nothing else is set.
zot talks to model providers directly: export the provider's key and it runs, with no account anywhere else.
@note the default model and provider have to agree - glm-5.2 is served natively by Z.AI, so that is the provider. A default pair that cannot actually talk to each other is worse than no default, because the failure arrives as a provider error rather than as a configuration one.
type ModelConfig ¶
type ModelConfig struct {
// Driver overrides the provider's driver for this model, so one provider
// connection can front several implementations.
Driver string `yaml:"driver"`
// Model is the underlying model id to send. Lets a custom name alias a real
// model; leave empty to use the selected name as-is.
Model string `yaml:"model"`
// MaxIterations overrides the global iteration cap for this model.
MaxIterations int `yaml:"max_iterations"`
// APIKey is this model's own credential, overriding the provider's. Useful
// where one gateway fronts several providers, each wanting its own key.
// Supports "$ENV_VAR".
APIKey string `yaml:"api_key"`
// Context overrides the model's total context window, in tokens. The
// escape hatch for a serving endpoint whose real ceiling is smaller than
// the model's card - an uncatalogued model is assumed large, so a small
// upstream rejects the request before compaction ever fires, and an
// upstream that reports overflow opaquely gives the recovery path nothing
// to detect. Zero uses the catalogue.
Context int `yaml:"context"`
// Vision, Tools and Reasoning override what the catalogue believes this
// model can do. Unset defers to the catalogue, which is why they are
// pointers: "not stated" and "stated as false" are different answers, and
// only the second should be able to turn a capability off.
//
// The catalogue cannot know about a private deployment, a gateway that
// strips capabilities on the way through, or a model released after this
// binary was built. Vision is the one that matters most in practice:
// an uncatalogued model is assumed blind, so a model that can in fact see
// needs saying so here before it is offered a tool for looking.
Vision *bool `yaml:"vision"`
Tools *bool `yaml:"tools"`
Reasoning *bool `yaml:"reasoning"`
}
ModelConfig is a custom model definition under a provider. Any field set here overrides the run's defaults when the model is selected.
func (ModelConfig) Capabilities ¶ added in v0.17.0
func (m ModelConfig) Capabilities(base catalogue.Model) catalogue.Model
Capabilities applies this model's overrides to what the catalogue believes.
The resolution order is the same one Context follows: an explicit setting wins, otherwise the catalogue, otherwise its conservative default.
type ProviderConfig ¶ added in v0.11.0
type ProviderConfig struct {
// Driver names the provider implementation this connection uses: "openai",
// "anthropic", "groq", "ollama" and so on. Empty infers it from the
// provider's own name, so a provider called "groq" needs no further
// configuration.
//
// zot speaks the OpenAI-compatible chat-completions API to every provider, so
// a provider connection is a URL and a credential rather than a protocol of
// its own. The driver selects endpoint defaults and provider-specific quirks.
Driver string `yaml:"driver"`
// BaseURL overrides the API endpoint. Empty uses the built-in default.
BaseURL string `yaml:"base_url"`
// APIKey is the provider credential. Supports "$ENV_VAR" references, so no
// secret need be written to disk.
APIKey string `yaml:"api_key"`
// Models is an optional custom model list for this provider. When omitted,
// callers can use the built-in catalogue. When present, its keys are the
// selectable names and each entry may alias or override that model.
Models map[string]ModelConfig `yaml:"models"`
}
ProviderConfig is a named model-provider connection zot can run against. Every provider authenticates with a Bearer credential.
type UI ¶
type UI struct {
// Diff, when true, renders a framed, syntax-highlighted before/after diff
// panel beneath every edit/write the agent makes.
Diff bool `yaml:"diff"`
// Plain forces the unstyled streaming renderer (no full-screen TUI). Without
// a terminal Zot also streams, with styling decided separately by Color.
Plain bool `yaml:"plain"`
// Color controls ANSI styling for automatic non-interactive streams: auto,
// always, or never. Plain still forces unstyled output, and Color never
// enables terminal input.
Color string `yaml:"color"`
// Scrollback caps how many log lines the full-screen viewer keeps on screen.
// Zero uses the built-in default; raise it to keep more of a long run visible
// (at more memory). The full run is always in the session log regardless.
Scrollback int `yaml:"scrollback"`
// Stats selects which fields the header bar shows, and in what order (see
// tui.KnownStats: provider, model, dir, iter, tools, edits, elapsed,
// tokens, tps, pace, task, order). Order matters - the bar drops what does
// not fit, so earlier fields survive a narrower terminal. Empty
// uses the default set.
Stats []string `yaml:"stats"`
}
UI holds presentation options for the read-only viewer.
type UpdateCheck ¶ added in v0.19.1
type UpdateCheck struct {
// Disabled makes no release lookup at all.
Disabled bool `yaml:"disabled"`
}
UpdateCheck configures the one call a run makes that is not to the configured provider: a lookup of the latest release on GitHub, so an out-of-date binary can say so when the run ends. Nothing about the user or the run travels with it, and every failure is dropped silently - but an air-gapped host, a locked-down CI job, or anyone who would rather zot spoke to nothing but the provider can turn it off.
Source Files