axis

module

v0.14.7 Latest Latest Go to latest Published: Jul 25, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/toasterbook88/axis

Links

Open Source Insights

README ¶

AXIS

A local-first cluster substrate that discovers hardware across your machines via SSH, builds deterministic snapshots, and makes reservation-aware placement decisions — with optional gossip mesh discovery, AI agent surfaces, and guarded execution.

Truth Boundary: No generated output may present itself as cluster truth unless it is backed by a real snapshot or live probe.

Architecture

AXIS is built as a 5-layer stack. Each layer is subordinate to the one below it — advisory surfaces never override observed state.

┌─────────────────────────────────────────────────────────────────┐
│  Layer 5: ADVISORY                                              │
│  Chat · Agent · MCP Server                                      │
│  Experimental helpers — never authoritative                     │
├─────────────────────────────────────────────────────────────────┤
│  Layer 4: EXECUTION                                             │
│  Guarded Exec · Safety Gates · Heartbeat Reservations           │
│  Structured NDJSON streaming · Resource accounting              │
├─────────────────────────────────────────────────────────────────┤
│  Layer 3: PLACEMENT                                             │
│  Filter → Rank → Select · FitScore 0-100                        │
│  GPU/VRAM matching · Locality · Empirical observations          │
├─────────────────────────────────────────────────────────────────┤
│  Layer 2: SNAPSHOT                                              │
│  ClusterSnapshot assembly · Daemon cache · 7 refresh triggers   │
│  Content-aware config watches · Staleness detection             │
├─────────────────────────────────────────────────────────────────┤
│  Layer 1: FACT PLANE                                            │
│  SSH hardware probes · UDP beacons · Mesh gossip scaffolding    │
│  (mesh is library-only; not wired into the CLI operator path)   │
│  Local + remote collectors · HMAC-authenticated beacons         │
└─────────────────────────────────────────────────────────────────┘

Quick Start

# Install (Recommended)
curl -fsSL https://raw.githubusercontent.com/toasterbook88/axis/main/install.sh | bash

# Or install via Go (Requires Go 1.26+)
go install github.com/toasterbook88/axis/cmd/axis@latest

# Configure your cluster (Interactive Wizard)
axis init

# Inspect the local machine
axis facts

# Inspect the full cluster
axis status

# Ask where to run a task
axis task place "run ollama inference on a 7b model"

# Explain a placement decision
axis placement explain "run ollama inference on a 7b model"

# Health diagnostics
axis doctor

Command Surface

Stable Operator Path

Command	Purpose
`axis version`	Print build version, commit, and Go version
`axis init`	Interactive cluster configuration wizard
`axis facts`	Local hardware/tool snapshot (`--format json\|yaml`)
`axis status`	Live cluster snapshot (`--cached`, `--cached-only`)
`axis summary`	Cluster summary view
`axis task place`	Advisory placement with reasoning (`--cached`)
`axis placement explain`	Detailed per-node placement breakdown
`axis profile match`	Workload class inference (no snapshot needed)
`axis task context`	Compact context block (`--format json`, `--cached`)
`axis task run`	Guarded task execution with safety gates
`axis reservations`	Reservation inspection
`axis doctor`	Comprehensive health diagnostics
`axis daemon start`	Background snapshot refresh daemon
`axis daemon status`	Daemon health and cache metadata
`axis daemon refresh`	Trigger immediate cache refresh
`axis daemon invalidate`	Invalidate cached snapshot
`axis daemon restart`	Restart the local cache daemon
`axis serve`	Local HTTP API + daemon cache
`axis llm`	LLM routing and model management
`axis ai`	Inference backends, roles, and dry-run routing
`axis cortex`	Distributed vector memory / event bus
`axis update`	Self-update via GitHub Releases
`axis context show\|clear`	Inspect or clear placement memory
`axis scripts list`	Built-in script catalog
`axis skills`	Learned execution skills
`axis completion`	Shell completions (bash/zsh/fish/powershell)

Experimental / Secondary Surfaces

These commands are shipped but advisory or experimental. They do not override observed cluster state.

Command	Purpose
`axis mcp serve`	Read-only MCP server over stdio
`axis chat`	Ollama-backed advisory chat
`axis agent`	Tool-calling agent loop

Placement Algorithm

The placement engine uses a deterministic Filter → Rank → Select pipeline:

Filter (all must pass)

Node status: complete
Allocatable RAM ≥ requirement (after system reserve)
GPU VRAM/vendor/backend match
Required tools present
Empirical PeakRAMMB filter
No thermal throttling
Battery ≥ 20%
No active tombstones
Storage class check (HDD penalty)

Rank (priority order)

Highest allocatable RAM
Best empirical observation (fresh only)
Resident model locality
Preferred backend rank
GPU score (+25 pts)
Highest effective headroom
Unified-memory / TurboQuant suitability
Lowest RAM pressure
Lowest reservation ratio
Node name ascending (stable tiebreak)

FitScore (0–100)

GPU match: +25 pts
Local node: +10 pts
Unified memory bonus for matching workloads
Reservation ratio factor

HTTP API

v1 Routes (Unix socket: `~/.axis/axis.sock`)

Route	Auth	Purpose
`GET /health`	No	Daemon health
`GET /snapshot`	Yes	Full ClusterSnapshot
`GET /snapshot/meta`	Yes	Cache metadata
`POST /run`	Yes	Guarded execution (NDJSON stream)
`POST /refresh`	Yes	Trigger cache refresh
`POST /invalidate`	Yes	Invalidate cache
`GET /tools`	Yes	MCP tool definitions
`GET /knowledge`	Yes	Cluster knowledge + skills

v2 Routes (internal scaffolding)

A small set of /v2/* read routes (/v2/cluster, /v2/nodes, /v2/nodes/:name, /v2/metrics, /v2/doctor) are active. Several endpoints return 501 as explicit placeholders for unimplemented surfaces. These are not the primary operator API.

Configuration

# ~/.axis/nodes.yaml
nodes:
  - name: macbook-pro
    hostname: 192.168.1.100
    ssh_port: 22
    ssh_user: admin
    role: workstation
    timeout: 10s

  - name: linux-server
    hostname: 192.168.1.200
    ssh_user: deploy
    role: server

Build & Test

make build          # CGO_ENABLED=0 go build -trimpath with LDFLAGS
make install        # Build + copy to $GOPATH/bin
make test           # go test ./... -count=1 -timeout 180s
make test-race      # go test ./... -count=1 -timeout 180s -race
make lint           # gofmt + go vet
make coverage       # Coverage gates via hack/coverage-check.sh

Release Process

Releases are automated via GitHub Actions:

# 1. Update version in internal/buildinfo/version.go
# 2. Commit and tag
git tag v0.X.Y
git push origin v0.X.Y

# 3. release.yml runs automatically:
#    Test Gate → Version Validation → Security Scan → GoReleaser → Verify Install

Binaries are built for darwin/linux × amd64/arm64 with:

Reproducible builds (-trimpath, CGO_ENABLED=0)
Embedded version, commit hash, build date
SHA-256 checksums
Conventional Commits changelog

Project Layout

axis/
├── cmd/axis/          Cobra CLI entry point
├── internal/          Private packages (34 packages)
│   ├── facts/         SSH hardware/tool collection
│   ├── snapshot/      ClusterSnapshot assembly
│   ├── placement/     Deterministic Filter→Rank→Select
│   ├── execution/     Guarded task execution
│   ├── daemon/        Background cache + 7 refresh triggers
│   ├── api/           HTTP API (v1 + v2 read routes)
│   ├── mesh/          Gossip peer discovery scaffolding (library-only)
│   ├── reservation/   Resource accounting ledger (library-only)
│   ├── safety/        Structured command safety groundwork (scaffolding)
│   ├── discovery/     SSH + UDP node discovery
│   ├── mcp/           MCP server (stdio)
│   ├── agent/         Tool-calling agent loop
│   └── ...            20+ additional packages
├── docs/              Design docs + CI-validated state
├── hack/              Developer scripts
└── .github/           CI + release workflows

Security

Air-gapped option: On-device inference via Ollama, no cloud dependency
HMAC-SHA256: Beacon auth is shipped; mesh gossip scaffolding authenticates payloads but does not yet enforce replay protection
Zero-trust execution: Existing safety gates are shipped; parsed command analysis scaffolding is not wired into the operator path
Constant-time auth: Bearer token comparison via crypto/subtle
No data exfiltration: All state persisted locally in ~/.axis/
govulncheck: Automated vulnerability scanning in release pipeline
SBOM generation: Supply chain transparency via GoReleaser

See SECURITY.md for our vulnerability disclosure policy.

Contributing

See CONTRIBUTING.md for development guidelines.

For AI agents working in this repo, see AGENTS.md.

License

MIT — Smith Software Solutions LLC

axismcp.app · axismcp.tech · smithsolutionssc.com · @AXISBRIDGEMACOS

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
axis command Package main extension: dashboard.go contains rendering helpers for proposed dashboard-style CLI views.	Package main extension: dashboard.go contains rendering helpers for proposed dashboard-style CLI views.
examples
mcp-event-client command
hack
internal
agent Package agent is EXPERIMENTAL — tool-calling agent loop with safety-gated shell.	Package agent is EXPERIMENTAL — tool-calling agent loop with safety-gated shell.
api Package api is EXPERIMENTAL — optional local HTTP API and execution surface.	Package api is EXPERIMENTAL — optional local HTTP API and execution surface.
auth Package auth is INTERNAL-ONLY — forwarded-origin auth helpers.	Package auth is INTERNAL-ONLY — forwarded-origin auth helpers.
buildinfo Package buildinfo is INTERNAL-ONLY — version, commit, date, and Go version injection.	Package buildinfo is INTERNAL-ONLY — version, commit, date, and Go version injection.
chat Package chat is EXPERIMENTAL — structured Ollama client.	Package chat is EXPERIMENTAL — structured Ollama client.
config Package config is STABLE — AXIS node configuration loader with strict YAML parsing.	Package config is STABLE — AXIS node configuration loader with strict YAML parsing.
cortex Package cortex is EXPERIMENTAL — distributed vector memory and event bus client.	Package cortex is EXPERIMENTAL — distributed vector memory and event bus client.
daemon Package daemon is STABLE — background snapshot refresh and in-memory cache.	Package daemon is STABLE — background snapshot refresh and in-memory cache.
discovery Package discovery is STABLE — configured-node fan-out and optional UDP beacon discovery.	Package discovery is STABLE — configured-node fan-out and optional UDP beacon discovery.
events Package events provides an in-process event bus for AXIS lifecycle events.	Package events provides an in-process event bus for AXIS lifecycle events.
execution Package execution is EXPERIMENTAL — guarded execution path with safety gating.	Package execution is EXPERIMENTAL — guarded execution path with safety gating.
facts Package facts is STABLE — local and remote cluster fact collection.	Package facts is STABLE — local and remote cluster fact collection.
failures Package failures is STABLE — failure-scope hashing and expiry.	Package failures is STABLE — failure-scope hashing and expiry.
git Package git is STABLE — local git repository workspace querying and status helpers.	Package git is STABLE — local git repository workspace querying and status helpers.
knowledge Package knowledge is STABLE — execution context builder for cluster operations.	Package knowledge is STABLE — execution context builder for cluster operations.
llmrouter Package llmrouter is EXPERIMENTAL — hybrid local/cloud LLM routing.	Package llmrouter is EXPERIMENTAL — hybrid local/cloud LLM routing.
lockutil
mcp Package axismcp is EXPERIMENTAL — read-only MCP diagnostic server.	Package axismcp is EXPERIMENTAL — read-only MCP diagnostic server.
mcpclient Package mcpclient provides a unified client for connecting to multiple MCP servers.	Package mcpclient provides a unified client for connecting to multiple MCP servers.
mesh Package mesh is SCAFFOLDED — gossip-based peer discovery scaffolding.	Package mesh is SCAFFOLDED — gossip-based peer discovery scaffolding.
modelplan Package modelplan builds deterministic, snapshot-backed distributed model placement plans.	Package modelplan builds deterministic, snapshot-backed distributed model placement plans.
models Package models is INTERNAL-ONLY — core shared types with no operator-facing contract.	Package models is INTERNAL-ONLY — core shared types with no operator-facing contract.
multipath
netutil Package netutil contains small helpers for outbound network operations.	Package netutil contains small helpers for outbound network operations.
persist Package persist is INTERNAL-ONLY — corrupt-file quarantine and warning recovery.	Package persist is INTERNAL-ONLY — corrupt-file quarantine and warning recovery.
placement Package placement is STABLE — deterministic filter, rank, and select for task placement.	Package placement is STABLE — deterministic filter, rank, and select for task placement.
repairs Package repairs is SCAFFOLDED — typed repair-event structures.	Package repairs is SCAFFOLDED — typed repair-event structures.
reservation Integration: The daemon holds the Ledger.	Integration: The daemon holds the Ledger.
runtimectx Package runtimectx is STABLE — unified live runtime loader for read surfaces.	Package runtimectx is STABLE — unified live runtime loader for read surfaces.
safety Package safety is EXPERIMENTAL — execution safety blocker with structured analysis.	Package safety is EXPERIMENTAL — execution safety blocker with structured analysis.
scripts Package scripts is STABLE — built-in helper script registry with keyword matching.	Package scripts is STABLE — built-in helper script registry with keyword matching.
secrets Package secrets is EXPERIMENTAL — safe API key resolution for AXIS.	Package secrets is EXPERIMENTAL — safe API key resolution for AXIS.
skills Package skills is EXPERIMENTAL — learned skills and failures with corrupt-file recovery.	Package skills is EXPERIMENTAL — learned skills and failures with corrupt-file recovery.
snapshot Package snapshot is STABLE — cluster snapshot assembly from collected NodeFacts.	Package snapshot is STABLE — cluster snapshot assembly from collected NodeFacts.
snapshotview Package snapshotview is INTERNAL-ONLY — deep clone and reservation overlay on snapshots.	Package snapshotview is INTERNAL-ONLY — deep clone and reservation overlay on snapshots.
state Package state is STABLE — placement memory, exact-scope observations, and reservation tracking.	Package state is STABLE — placement memory, exact-scope observations, and reservation tracking.
transport Package transport is STABLE — SSH command execution layer with host-key verification.	Package transport is STABLE — SSH command execution layer with host-key verification.
turboexec Package turboexec is INTERNAL-ONLY — TurboQuant flag injection for execution.	Package turboexec is INTERNAL-ONLY — TurboQuant flag injection for execution.
ui Package ui is INTERNAL-ONLY — terminal colors, tables, spinners, and help templates.	Package ui is INTERNAL-ONLY — terminal colors, tables, spinners, and help templates.
versioncmp Package versioncmp is INTERNAL-ONLY — module version comparison helpers.	Package versioncmp is INTERNAL-ONLY — module version comparison helpers.
workload Package workload is STABLE — workload class inference and deterministic matching.	Package workload is STABLE — workload class inference and deterministic matching.