Configuration Reference

Configuration Reference

Relevant source files

The following files were used as context for generating this wiki page:

• internal/auth/auth.go
• internal/config/config.go
• internal/config/config_test.go
• internal/secrets/secrets.go
• nodes.example.yaml

The AXIS configuration system is centered around a single source of truth: the nodes.yaml file located at ~/.axis/nodes.yaml. This file defines the cluster topology, discovery mechanisms, AI inference providers, and external integrations like MCP servers and webhooks.

Core Configuration Schema

The Config struct serves as the root object for the YAML configuration. AXIS employs strict decoding via gopkg.in/yaml.v3; any unknown keys in the YAML file will cause the Load function to return an error, preventing silent failures due to typos internal/config/config.go:175-185.

Node Configuration (NodeConfig)

The nodes list is the only mandatory section in the configuration. It defines the seed nodes for the cluster.

Field	Type	Required	Description
name	string	Yes	Unique identifier for the node within the config.
hostname	string	Yes	Resolvable DNS name or IP address for SSH access.
ssh_user	string	Yes	The username used for remote fact collection and execution.
ssh_port	int	No	SSH port (defaults to 22) internal/config/config.go:33-38.
role	string	No	Optional label (e.g., primary, worker).
timeout_sec	int	No	Per-node collection timeout (defaults to 10s) internal/config/config.go:41-46.
system_reserve_mb	int64	No	RAM to subtract from reported capacity for OS overhead.
stable_id	string	No	Optional UUID for persistent identity across IP changes.

Sources: internal/config/config.go:21-47, nodes.example.yaml:7-20

Discovery Configuration (DiscoveryConfig)

Discovery controls how AXIS identifies other nodes on the network using UDP beacons.

graph TD
    subgraph "Code Entity Space: internal/config"
        A["DiscoveryConfig struct"] --> B["Enabled: bool"]
        A --> C["UDPPort: int"]
        A --> D["BeaconInterval: int"]
        A --> E["Secret: string"]
    end
    
    subgraph "Natural Language: nodes.yaml"
        F["'discovery:' block"] --- B
        G["'udp_port:'"] --- C
        H["'beacon_interval_sec:'"] --- D
        I["'secret:'"] --- E
    end

Loading

Sources: internal/config/config.go:49-54, nodes.example.yaml:23-27

AI Provider Configuration

AXIS supports a hybrid inference model, allowing routing between local (e.g., Ollama) and cloud (e.g., OpenAI, Anthropic) providers.

AIProviderConfig

This section defines how to connect to specific LLM backends.

• Type: Either local or cloud internal/config/config.go:89.
• Kind: Specific provider implementation (e.g., openrouter, groq, anthropic) internal/config/config.go:92.
• API Key Resolution: AXIS uses a priority-based resolution for secrets. It first checks api_key_env (the name of an environment variable). If not found, it checks api_key_file (a path to a file containing the key) internal/secrets/secrets.go:27-55.

InferenceConfig

Global preferences for the llmrouter.Engine:

• DefaultMode: local, cloud, or auto.
• Prefer: latency, cost, or quality internal/config/config.go:125-141.

Sources: internal/config/config.go:72-115, internal/secrets/secrets.go:1-55

Integration: MCP and Webhooks

MCPServers

AXIS can act as a client to external Model Context Protocol (MCP) servers.

• Transport: Supports stdio (local process) or http (remote SSE).
• Command: For stdio, a list of strings representing the executable and arguments.
• URL/Headers: For http transport internal/config/config.go:144-156.

Webhooks

The webhooks field is a simple list of URLs. AXIS dispatches cluster events (e.g., task.placement.requested) to these endpoints as POST requests internal/config/config.go:166.

Sources: internal/config/config.go:143-167

Data Flow and Validation

When config.Load(path) is called, the system performs a multi-stage validation:

1. File Read: Loads raw bytes from the filesystem internal/config/config.go:177-180.
2. Strict YAML Unmarshal: Maps bytes to the Config struct, rejecting unknown fields internal/config/config_test.go:61-80.
3. Semantic Validation: The Validate() method ensures required fields like name, hostname, and ssh_user are present for every node internal/config/config_test.go:199-231.

Configuration Logic Flow

graph LR
    subgraph "Filesystem"
        YAML["~/.axis/nodes.yaml"]
        ENV["Environment Variables"]
    end

    subgraph "internal/config"
        LOAD["Load() function"]
        VAL["Validate() method"]
        CFG["Config struct"]
    end

    subgraph "internal/secrets"
        RES["Resolve() function"]
    end

    YAML --> LOAD
    LOAD --> VAL
    VAL --> CFG
    CFG -- "api_key_env" --> RES
    ENV -- "LookupEnv" --> RES
    RES --> "Inference Engine"

Loading

Sources: internal/config/config.go:176-185, internal/config/config_test.go:61-122, internal/secrets/secrets.go:27-35

Security and Auth

AXIS generates a local API token for the daemon at ~/.axis/token.

• Permissions: The token is saved with 0600 permissions (owner read/write only) internal/auth/auth.go:125.
• Atomic Write: Uses a temporary file and os.Rename to ensure the token is never partially written internal/auth/auth.go:86-120.
• Locking: Uses syscall.Flock to prevent race conditions during initial token generation internal/auth/auth.go:43-46.

Sources: internal/auth/auth.go:17-126

---