Getting Started

Getting Started

Relevant source files

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

• README.md
• cmd/axis/init.go
• cmd/axis/init_test.go
• docs/phase1_spec.md
• docs/white_paper_v1.md
• internal/config/config.go
• internal/config/config_test.go
• internal/modelplan/planner.go
• internal/modelplan/planner_basic_test.go
• nodes.example.yaml

AXIS is a local-first coordination substrate designed to discover hardware across machines via SSH, build deterministic snapshots, and make reservation-aware placement decisions for AI workloads README.md:9-11. It operates as a single binary with no mandatory background processes or proprietary wire protocols docs/white_paper_v1.md:27-32.

Installation

The primary method for installing AXIS is via the automated installation script, which fetches the latest release from GitHub. Alternatively, it can be built from source using the Go toolchain.

Recommended: Install Script

curl -fsSL https://raw.githubusercontent.com/toasterbook88/axis/main/install.sh | bash

README.md:51-52

From Source

AXIS requires Go 1.26+ README.md:5 and can be installed directly into your $GOPATH/bin:

go install github.com/toasterbook88/axis/cmd/axis@latest

README.md:54-55

Initial Configuration

AXIS relies on a seed configuration file located at ~/.axis/nodes.yaml internal/config/config.go:170-173. This file defines the initial set of nodes that AXIS will probe to build a cluster snapshot.

Interactive Wizard (axis init)

The easiest way to configure AXIS is by running the interactive setup wizard. This command:

1. Local Node: Detects your local hostname and sets up the primary node cmd/axis/init.go:58-73.
2. SSH User: Configures a global SSH user for remote connections cmd/axis/init.go:74-87.
3. Discovery: Scans for Tailscale peers cmd/axis/init.go:100-115 and UDP Gossip beacons cmd/axis/init.go:189-209 to automatically populate your node list.
4. Verification: Optionally tests SSH connectivity to each node before adding it cmd/axis/init.go:166-170.

Manual Configuration

You can manually create or edit ~/.axis/nodes.yaml. AXIS uses strict YAML parsing; unknown keys will cause the configuration to fail to load internal/config/config.go:1-2.

Example nodes.yaml:

nodes:
  - name: macbook-pro
    hostname: 192.168.1.100
    ssh_user: admin
    role: workstation
    timeout_sec: 10

  - name: linux-gpu-server
    hostname: 10.0.0.50
    ssh_user: root
    role: worker
    ssh_port: 22
    system_reserve_mb: 4096 # Reserved RAM AXIS won't allocate

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

Configuration Data Flow

The following diagram illustrates how the internal/config package transforms the YAML seed into internal models.

Config to Model Mapping

graph TD
    subgraph ["YAML Space (nodes.yaml)"]
        Y_Nodes["nodes:"]
        Y_Name["name: node-a"]
        Y_Host["hostname: 10.0.0.1"]
        Y_User["ssh_user: user"]
    end

    subgraph ["Code Entity Space (internal/config)"]
        C_Config["type Config struct"]
        C_NodeConfig["type NodeConfig struct"]
        C_Load["func Load(path string)"]
    end

    Y_Nodes --> C_Config
    Y_Name --> C_NodeConfig
    Y_Host --> C_NodeConfig
    Y_User --> C_NodeConfig
    C_Load -- "Parses" --> C_Config

Loading

Sources: internal/config/config.go:158-167, internal/config/config.go:21-30, internal/config/config.go:176-182

SSH Prerequisites

AXIS uses standard SSH for its transport layer docs/white_paper_v1.md:31. To ensure successful discovery and fact collection:

• Key-based Auth: Remote nodes must be accessible via SSH keys. Password authentication is not supported docs/phase1_spec.md:203-204.
• Identity: The local user running axis must have their public key in the ~/.ssh/authorized_keys file of the ssh_user on every remote node.
• Connectivity: The hostname provided in nodes.yaml must be resolvable and reachable on the specified ssh_port (defaulting to 22) internal/config/config.go:32-38.

First Commands

Once configured, use these commands to verify your cluster state:

Command	Description
axis facts	Probes the local machine only and prints hardware/tool telemetry README.md:61.
axis status	Fans out SSH probes to all nodes in nodes.yaml to build a ClusterSnapshot README.md:64.
axis doctor	Runs health diagnostics, checking for unreachable nodes or RAM pressure README.md:73.
axis task place "run llama3"	Advisory command that explains where a specific task should run based on current facts README.md:67.

Data Collection Lifecycle

The collection process flows from the internal/discovery package through the internal/facts collectors.

Fact Collection Flow

graph LR
    subgraph ["Orchestration"]
        D_Disc["discovery.Discover()"]
    end

    subgraph ["Collectors (internal/facts)"]
        LC["LocalCollector"]
        RC["RemoteCollector"]
    end

    subgraph ["Transport"]
        SSH["internal/transport.SSHExecutor"]
    end

    D_Disc --> LC
    D_Disc --> RC
    RC --> SSH
    LC -- "NodeFacts" --> SB["snapshot.Build()"]
    RC -- "NodeFacts" --> SB
    SB -- "Result" --> CS["models.ClusterSnapshot"]

Loading

Sources: docs/white_paper_v1.md:37-49, internal/facts/facts.go:1-20, internal/discovery/discovery.go:1-10 (Note: file paths inferred from white paper architecture and build spec).

Examples Directory

The repository includes a nodes.example.yaml file to serve as a template for cluster configuration nodes.example.yaml:1-28.

Key usage patterns demonstrated in examples:

1. Static Cluster: Defining a fixed set of known IP addresses nodes.example.yaml:7-17.
2. UDP Discovery: Enabling the experimental mesh gossip to find nodes without manual entry nodes.example.yaml:23-27.
3. Role Assignment: Distinguishing between primary and worker nodes for organizational purposes nodes.example.yaml:12-17.

Sources:

• README.md: 9-11, 51-55, 61-73
• internal/config/config.go: 1-2, 21-38, 158-182
• cmd/axis/init.go: 58-87, 100-115, 166-170, 189-209
• docs/white_paper_v1.md: 27-32, 37-49
• docs/phase1_spec.md: 203-204
• nodes.example.yaml: 1-28

---