config

type AgentConfig ¶

type AgentConfig struct {
	MaxSteps int `json:"max_steps,omitempty"`
}

AgentConfig tunes runtime agent behavior.

type AnthropicConfig ¶

type AnthropicConfig struct {
	APIKey string        `json:"api_key,omitempty"`
	Vertex *VertexConfig `json:"vertex,omitempty"`
}

AnthropicConfig holds Claude-specific settings for the anthropic provider family. APIKey is used by the first-party "anthropic" provider (api.anthropic.com); Vertex is used by "anthropic-vertex" (Claude served via Google Vertex AI).

type AttachConfig ¶ added in v1.8.0

type AttachConfig struct {
	// Server-side: where the attach listener binds. Set at most one.
	Listen     string `json:"listen,omitempty"`      // e.g. "0.0.0.0:7777"
	UnixSocket string `json:"unix_socket,omitempty"` // e.g. "/var/run/core-agent.sock"

	// TLS material. TLSCert + TLSKey enable HTTPS; ClientCA additionally
	// enables mTLS (client cert required). Paths only — keys live on disk.
	TLSCert  string `json:"tls_cert,omitempty"`
	TLSKey   string `json:"tls_key,omitempty"`
	ClientCA string `json:"client_ca,omitempty"`

	// TokenEnv is the name of the env var that holds the bearer token
	// clients must present. The secret itself never lives in config.
	TokenEnv string `json:"token_env,omitempty"`

	// ReadOnly disables POST /inject and /wake; read endpoints stay open.
	ReadOnly bool `json:"readonly,omitempty"`

	// PeerHub turns on the peer-registration endpoints on this listener.
	PeerHub bool `json:"peer_hub,omitempty"`

	// Peer-side: this agent registers with a remote hub.
	RegisterTo       string `json:"register_to,omitempty"`       // hub URL
	RegisterEndpoint string `json:"register_endpoint,omitempty"` // expanded via os.ExpandEnv
	RegisterName     string `json:"register_name,omitempty"`     // defaults to hostname when empty
}

AttachConfig holds defaults for the attach-mode listener and the peer-registration client. Every field is also exposed as a CLI flag (--attach-*); the CLI flag wins when set, otherwise the config value supplies the default. Fields holding URLs / addresses pass through os.ExpandEnv so per-pod values like "https://${POD_IP}:7777" can live in a shared ConfigMap.

BearerToken is intentionally NOT a field here. The CLI flag form is --attach-token=ENVVAR (the name of the env var holding the secret), not the secret itself, and that env-var indirection should not be duplicated in a config file. Configure the env var via your secret manager (K8s Secret, sealed-secret, etc.) and set TokenEnv if you want to nail the env-var name down per-deployment.

type Config ¶

type Config struct {
	Version     int               `json:"version"`
	Model       ModelConfig       `json:"model"`
	Permissions PermissionsConfig `json:"permissions,omitempty"`
	PathScope   PathScopeConfig   `json:"path_scope,omitempty"`
	Agent       AgentConfig       `json:"agent,omitempty"`
	ToolOutput  ToolOutputConfig  `json:"tool_output,omitempty"`
	Tools       ToolsConfig       `json:"tools,omitempty"`
	Mock        MockConfig        `json:"mock,omitempty"`
	OTEL        OTELConfig        `json:"otel,omitempty"`
	URLScope    URLScopeConfig    `json:"url_scope,omitempty"`
	Attach      AttachConfig      `json:"attach,omitempty"`
}

Config is the in-memory representation of `.agents/config.json`.

All sub-sections except Model have sensible zero-valued defaults, so a minimal `config.json` only needs to set what the user wants to override.

func DefaultConfig() *Config

func Load(agentsDir string) (*Config, error)

func LoadOrDefault(startDir string) (cfg *Config, agentsDir string, err error)

func (c *Config) Validate() error

type MockConfig ¶

type MockConfig struct {
	Script string `json:"script,omitempty"`
	Strict bool   `json:"strict,omitempty"`
	Record string `json:"record,omitempty"`
}

MockConfig configures the mock providers (echo, scripted) and the orthogonal recording wrapper.

Script is the path to a JSONL transcript consumed by the scripted provider; it's required when model.provider is "scripted".

Strict makes the scripted provider assert that each incoming request's Contents JSON-equal the recorded request. Off by default — the typical use is replaying without caring about prompt drift.

Record is a path to write a JSONL recording of every LLM turn. Works with any provider, not just the mocks; lives in MockConfig because it shares the file format the scripted provider consumes.

type ModelConfig ¶

type ModelConfig struct {
	Provider  string           `json:"provider,omitempty"`
	Name      string           `json:"name"`
	APIKey    string           `json:"api_key,omitempty"`
	Vertex    *VertexConfig    `json:"vertex,omitempty"`
	Anthropic *AnthropicConfig `json:"anthropic,omitempty"`
	Pricing   *PricingConfig   `json:"pricing,omitempty"`
}

ModelConfig selects the LLM provider and model.

Provider: one of "gemini", "vertex", "anthropic". When empty, the resolver auto-detects from the environment (see models.Resolve). Name: a model ID, e.g. "gemini-3.1-pro-preview-customtools" or "claude-opus-4-7". APIKey: optional inline key for Provider="gemini"; usually unset and read from GOOGLE_API_KEY at runtime. Vertex: required when Provider="vertex"; project + location. Anthropic: optional credentials for Provider="anthropic"; usually unset and read from ANTHROPIC_API_KEY at runtime.

type OTELConfig ¶

type OTELConfig struct {
	Exporter string `json:"exporter,omitempty"` // "none" | "console" | "otlp"
	Endpoint string `json:"endpoint,omitempty"`
}

OTELConfig configures the OpenTelemetry exporter.

type PathScopeConfig ¶

type PathScopeConfig struct {
	Allow []string `json:"allow,omitempty"`
}

PathScopeConfig holds extra paths that file tools may read/write outside the default project + user-home scope. Patterns may be exact paths or directory globs (terminating "/...") and are typically appended via the "Always allow this path/tree" prompt path.

type PermissionsConfig ¶

type PermissionsConfig struct {
	Mode  string   `json:"mode,omitempty"`  // "ask" | "allow" | "yolo"
	Allow []string `json:"allow,omitempty"` // pattern allowlist
	Deny  []string `json:"deny,omitempty"`  // pattern denylist
}

PermissionsConfig configures the permission gate.

type PricingConfig ¶

type PricingConfig struct {
	InputPerMTok  float64 `json:"input_per_mtok,omitempty"`
	OutputPerMTok float64 `json:"output_per_mtok,omitempty"`
}

PricingConfig overrides the built-in price table for cost estimation.

type ToolOutputConfig ¶

type ToolOutputConfig struct {
	MaxBytes int                              `json:"max_bytes,omitempty"`
	MaxLines int                              `json:"max_lines,omitempty"`
	PerTool  map[string]ToolOutputPerToolCaps `json:"per_tool,omitempty"`
}

ToolOutputConfig caps tool result size before it enters model context.

type ToolOutputPerToolCaps ¶

type ToolOutputPerToolCaps struct {
	MaxBytes int `json:"max_bytes,omitempty"`
	MaxLines int `json:"max_lines,omitempty"`
}

ToolOutputPerToolCaps overrides global tool-output limits for one tool.

type ToolsConfig ¶

type ToolsConfig struct {
	Disable []string `json:"disable,omitempty"`
}

ToolsConfig configures the bundled CLI's built-in tool suite.

Disable lists tools to turn off. Names must match the canonical built-in names (see tools.BuiltinToolNames). Unknown names cause a startup error from tools.BuiltinTools.Disable, so typos fail loudly rather than silently leaving a tool on.

The CLI's --disable-tools flag composes with this list by union; --no-builtin-tools disables the entire suite and makes Disable moot.

type URLScopeConfig ¶ added in v1.8.0

type URLScopeConfig struct {
	Allow          []string                     `json:"allow,omitempty"`
	Deny           []string                     `json:"deny,omitempty"`
	MaxBodyBytes   int                          `json:"max_body_bytes,omitempty"`
	TimeoutSeconds int                          `json:"timeout_seconds,omitempty"`
	Headers        map[string]map[string]string `json:"headers,omitempty"`
}

URLScopeConfig governs which URLs the fetch_url built-in is allowed to reach. Same Allow/Deny grammar + precedence as PathScopeConfig: Deny wins on overlap; an empty Allow list with the tool registered is treated as default-deny (the tool refuses every fetch and returns a clear error pointing at this config field).

Patterns are host-only globs (e.g. "github.com", "*.googleapis.com", "*.svc.cluster.local"). HTTPS is assumed unless the pattern is prefixed with "http://", in which case plain HTTP is allowed for that pattern only (intentionally awkward — operators have to type the prefix to opt out of TLS).

MaxBodyBytes caps the response body the tool returns to the model; zero means use the built-in default (64 KiB). TimeoutSeconds caps the HTTP timeout; zero means 30s.

Headers maps host patterns to header bundles. Header values pass through os.ExpandEnv at request time, so values like "Bearer ${GITHUB_TOKEN}" pick up rotated env vars without a restart. The model never sets headers directly — keeps credential exfiltration off the tool argument surface.

type VertexConfig ¶

type VertexConfig struct {
	Project  string `json:"project"`
	Location string `json:"location"`
}

VertexConfig holds GCP-specific settings for the vertex provider.