Skip to content

Design Principles and Architecture

Jump to bottom
William Smith edited this page Jul 13, 2026 · 1 revision

Design Principles and Architecture

Relevant source files

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

AXIS is a local-first cluster substrate designed to provide a deterministic, verifiable foundation for distributed task execution and AI agent coordination. It operates as a strict 5-layer stack where each layer is subordinate to the one below it.

The 5-Layer Stack

The architecture is organized into five distinct planes. A core invariant of the system is that advisory surfaces (Layer 5) can never override the observed state of the lower planes.

Layer Name Responsibility Key Packages
5 Advisory Experimental helpers, Chat, and Agent loops. internal/chat, internal/agent, internal/mcp
**** Execution Guarded task runs, safety gates, and resource accounting. internal/execution, internal/safety, internal/reservation
3 Placement Deterministic node selection via Filter → Rank → Select. internal/placement, internal/workload
2 Snapshot Cluster-wide state assembly and daemon-backed caching. internal/snapshot, internal/daemon
1 Fact Plane Raw hardware discovery and telemetry collection. internal/facts, internal/transport

Sources: README.md:20-46, AGENTS.md:90-103

Architecture Logic Flow

The following diagram illustrates the flow from raw hardware discovery to high-level advisory surfaces, mapping system concepts to code entities.

Diagram: System Flow and Code Mapping

graph TD
    subgraph Layer1 ["Layer 1: Fact Plane"]
        A["SSHExecutor"] -->|"probes"| B["LocalCollector"]
        A -->|"probes"| C["RemoteCollector"]
        B --> D["NodeFacts"]
        C --> D
    end

    subgraph Layer2 ["Layer 2: Snapshot"]
        D --> E["snapshot.Build()"]
        E --> F["ClusterSnapshot"]
        F --> G["daemon.Cache"]
    end

    subgraph Layer3 ["Layer 4: Placement"]
        F --> H["placement.Engine"]
        H -->|"Filter/Rank"| I["PlacementDecision"]
    end

    subgraph Layer4 ["Layer 4: Execution"]
        I --> J["execution.RunGuarded()"]
        J --> K["reservation.Ledger"]
        K -->|"Overlay"| F
    end

    subgraph Layer5 ["Layer 5: Advisory"]
        F -.-> L["agent.Agent"]
        F -.-> M["mcp.Server"]
    end

    style Layer1 stroke-dasharray: 5 5
    style Layer5 stroke-dasharray: 5 5
Loading

Sources: AGENTS.md:90-136, internal/buildinfo/version.go:1-5, README.md:119-145

Core Design Principles

The Truth Rule

No generated output may present itself as cluster truth unless it is backed by a real snapshot or live probe docs/current-state.md:7-7. This ensures that AI agents or experimental CLI commands cannot "hallucinate" the state of the cluster.

Deterministic Placement Guarantee

Placement is not a "best effort" guess. It follows a rigid Filter → Rank → Select pipeline:

  1. Filter: Hard constraints (RAM floor, GPU vendor match, tool availability, thermal health) README.md:123-132.
  2. Rank: A 10-level deterministic sort, ending in a node-name tiebreak to ensure consistency README.md:134-144.
  3. Select: Calculation of a FitScore (0-100) based on locality and resource suitability README.md:146-151.

Single-Binary Philosophy

AXIS is distributed as a single, statically-linked binary with zero external runtime dependencies other than SSH README.md:9-11. This simplifies deployment across heterogeneous environments (macOS, Linux, x86, ARM).

Sources: docs/current-state.md:7-7, README.md:119-151, AGENTS.md:11-20

Layer 1 & 2: Facts and Snapshots

The foundation of AXIS is the NodeFacts struct AGENTS.md:151-153.

  • Discovery: Nodes are discovered via nodes.yaml or UDP beacons README.md:41-44.
  • Telemetry: Probes collect real-time data including Linux PSI/Darwin VM pressure, battery levels, and thermal throttling docs/current-state.md:55-57.
  • Snapshot Assembly: The snapshot.Build() function deduplicates nodes and classifies network topology (e.g., direct-lan vs tailscale) CHANGELOG.md:4-4.

Sources: internal/buildinfo/version.go:1-5, docs/current-state.md:53-58, AGENTS.md:105-117

Layer 3 & 4: Placement and Execution

The transition from "knowing" to "doing" happens through the internal/execution package.

The Reservation Ledger

To prevent over-subscription, AXIS uses a double-entry reservation.Ledger docs/current-state.md:69-69. When a task is placed, RAM/VRAM is "committed" in the ledger. Subsequent placement decisions use a snapshotview which subtracts these active reservations from the raw hardware facts docs/current-state.md:45-46.

Guarded Execution Pipeline

Execution follows a strict lifecycle:

  1. Safety Evaluation: The internal/safety engine parses the command to assign a risk score docs/current-state.md:69-69.
  2. Resource Lock: A reservation is created in ~/.axis/state.json docs/current-state.md:41-41.
  3. Context Injection: AXIS_CONTEXT_FILE is injected into the remote environment docs/current-state.md:44-44.
  4. Cleanup: Remote cleanup traps ensure temporary files are removed even on failure docs/current-state.md:67-67.

Sources: docs/current-state.md:41-69, AGENTS.md:129-132, README.md:29-31

Layer 5: Advisory Surfaces

The Advisory layer contains the AI-powered interfaces:

  • axis agent: A tool-calling loop with 32+ tools for cluster management CHANGELOG.md:20-30.
  • axis chat: An interactive REPL that auto-routes inference to the best node via SSH tunnels CHANGELOG.md:41-42.
  • MCP Server: Implements the Model Context Protocol to expose cluster state to external LLMs docs/current-state.md:39-39.

Diagram: Advisory Context Injection This diagram shows how Layer 5 consumes Layer 2 data without modifying it.

graph LR
    subgraph Core ["Authoritative Core"]
        DS[("state.json")] --> DC["daemon.Cache"]
        NF["NodeFacts"] --> DC
    end

    subgraph Advisory ["Advisory Surfaces"]
        DC -->|"Read Only"| AG["agent.Agent"]
        DC -->|"Read Only"| MC["mcp.Server"]
        DC -->|"Read Only"| CH["chat.Engine"]
    end

    AG -->|"Request Task"| RE["execution.RunGuarded"]
    RE -->|"Update"| DS
Loading

Sources: docs/current-state.md:39-41, AGENTS.md:121-136, CHANGELOG.md:20-30

Persistence and State Management

AXIS maintains persistent state in the user's home directory to survive reboots and binary updates.

File Purpose Implementation
~/.axis/nodes.yaml Static cluster configuration internal/config
~/.axis/state.json Active reservations and heartbeats internal/state
~/.axis/skills.json Learned execution successes/failures internal/skills

The system includes a Tombstone Immune System that records task failures. If a node causes repeated crashes, it is automatically excluded from placement for 24h to 7d docs/current-state.md:63-63.

Sources: docs/current-state.md:41-42, docs/current-state.md:63-63, AGENTS.md:108-110

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally