AXIS Overview

AXIS Overview

Relevant source files

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

• AGENTS.md
• CHANGELOG.md
• CONTRIBUTING.md
• Makefile
• README.md
• cmd/axis/testdata/summary_corrupt_state.golden
• cmd/axis/testdata/summary_empty_state.golden
• cmd/axis/testdata/summary_live_snapshot.golden
• docs/current-state.md
• docs/phase1_spec.md
• docs/white_paper_v1.md
• go.mod
• go.sum
• hack/pr-review-cycle.sh
• hack/refresh-current-state.sh
• hack/test-lint-failclosed.sh
• internal/buildinfo/version.go
• internal/daemon/daemon_testmain_test.go

AXIS is a local-first cluster substrate designed to discover, manage, and execute workloads across a distributed set of machines. It transforms a collection of nodes accessible via SSH into a unified resource pool with deterministic placement and safety-gated execution.

The system is built as a single binary with a "Truth Boundary" principle: no generated output or AI-mediated response may present itself as cluster truth unless it is backed by a real snapshot or live hardware probe docs/current-state.md:7-7.

The 5-Layer Architecture

AXIS is organized into a strict 5-layer stack. Each layer is subordinate to the one below it, ensuring that high-level advisory features (like AI agents) cannot override the observed physical reality of the cluster README.md:20-21.

Layer 1: Fact Plane

The foundation of the system. It uses internal/facts to collect hardware telemetry (RAM, GPU, CPU, Disk) and internal/discovery to locate nodes via nodes.yaml or UDP beacons AGENTS.md:101-102.

• Key Entities: NodeFacts, LocalCollector, RemoteCollector.
• For details, see Fact Collection and Discovery.

Layer 2: Snapshot Plane

Assembles raw facts into a ClusterSnapshot. The internal/daemon maintains a cached view of the cluster, triggered by seven distinct refresh events such as config changes or execution events docs/current-state.md:36-37.

• Key Entities: ClusterSnapshot, daemon.Cache, snapshot.Build().
• For details, see Snapshot Assembly and Daemon Cache.

Layer 3: Placement Plane

The deterministic engine that decides where a task should run. It uses a Filter → Rank → Select pipeline to match task requirements against node capabilities README.md:121-121.

• Key Entities: PlacementDecision, FitScore, llmrouter.Engine.
• For details, see Placement Engine.

Layer 4: Execution Plane

Handles the lifecycle of a task. It orchestrates safety gating, resource reservations in a double-entry ledger, and secure execution via SSH or local bash AGENTS.md:129-132.

• Key Entities: RunGuarded, reservation.Ledger, Evaluator.
• For details, see Execution Engine.

Layer 5: Advisory Layer

The user-facing AI and API surfaces. These tools provide cluster-aware assistance and interfaces but remain strictly advisory README.md:25-27.

• Key Entities: Agent, MCPServer, axis chat.
• For details, see Advisory Layer: AI Surfaces.

---

System Architecture Diagram

This diagram illustrates how the conceptual layers map to specific internal Go packages and the flow of data from physical hardware to the user.

Cluster Data Flow

graph TD
    subgraph "Layer 5: Advisory"
        A1["internal/chat"]
        A2["internal/agent"]
        A3["internal/mcp"]
    end

    subgraph "Layer 4: Execution"
        E1["internal/execution"]
        E2["internal/safety"]
        E3["internal/reservation"]
    end

    subgraph "Layer 3: Placement"
        P1["internal/placement"]
        P2["internal/workload"]
    end

    subgraph "Layer 2: Snapshot"
        S1["internal/snapshot"]
        S2["internal/daemon"]
    end

    subgraph "Layer 1: Fact Plane"
        F1["internal/facts"]
        F2["internal/transport (SSH)"]
        F3["internal/discovery"]
    end

    F1 --> S1
    F2 --> F1
    F3 --> S1
    S1 --> S2
    S2 --> P1
    P1 --> E1
    E2 --> E1
    E3 --> E1
    E1 --> A2
    S2 --> A1
    S2 --> A3

Loading

Sources: README.md:23-46, AGENTS.md:94-103

---

Design Principles

1. Single-Binary Philosophy: AXIS is distributed as a single static binary to minimize deployment friction README.md:9-12.
2. Deterministic Placement: Node selection is never "random." It follows a 10-level sort priority including RAM headroom, GPU scores, and empirical failure memory README.md:134-144.
3. Safety First: All remote executions are "guarded." The system uses a structured safety engine to parse commands and apply risk categories (e.g., destructive, privilege escalation) docs/current-state.md:69-69.
4. Empirical Feedback: The system records PeakRAMMB and WallTimeMS from actual runs to refine future placement decisions docs/current-state.md:59-59.

---

Core Code Entities

The following diagram bridges the gap between high-level system components and the primary Go structs defined in internal/models/types.go.

Entity Mapping

classDiagram
    class NodeFacts {
        +String Name
        +String Hostname
        +Resources Hardware
        +[]String Tools
        +NodeStatus Status
    }
    class ClusterSnapshot {
        +[]NodeFacts Nodes
        +Time Timestamp
        +ClusterMetrics Aggregates
    }
    class PlacementDecision {
        +NodeFacts SelectedNode
        +Float64 FitScore
        +String Reasoning
    }
    class TaskRequirements {
        +Int64 RAMMB
        +String GPUVendor
        +[]String RequiredTools
    }

    NodeFacts --* ClusterSnapshot : "assembled into"
    ClusterSnapshot --> PlacementDecision : "input for"
    TaskRequirements --> PlacementDecision : "constraints for"

Loading

Sources: internal/models/types.go:151-158, AGENTS.md:149-158

---

Subsystem Relationships

Subsystem	Responsibility	Primary Interface
Daemon	Background refresh and state persistence in ~/.axis/state.json.	axis daemon start docs/current-state.md:30-30
Collector	Probing nvidia-smi, ollama, and OS telemetry.	facts.NewCollector() docs/current-state.md:54-54
Safety	Blocking or allowing commands based on RuleSet.	safety.Evaluator docs/current-state.md:69-69
Cortex	Distributed event bus and vector memory.	axis cortex README.md:101-101

For a deeper dive into these components, refer to the following child pages:

• Getting Started — Installation and first commands.
• Design Principles and Architecture — Deep dive into the 5-layer stack.

---