Axis v0.19.4：本地优先、感知预留的集群底座

Local-first, reservation-aware cluster substrate
Deterministic placement · Guarded execution · Observed-state truth

Quick start · What · Architecture · Commands · Docs

Quick start

Each block below is safe to paste. Commands match axis --help on v0.19.4 (axis serve, axis cluster status, axis init, axis daemon).

1. Install

Pinned release — install.sh writes /usr/local/bin/axis and uses sudo when that directory is not writable:

curl -fsSL https://raw.githubusercontent.com/toasterbook88/axis/main/install.sh \
  | AXIS_VERSION=v0.19.4 AXIS_REQUIRE_PINNED=1 bash
axis version

Same installer, user-local (no sudo). Put ~/.local/bin on PATH if it is not already:

curl -fsSL https://raw.githubusercontent.com/toasterbook88/axis/main/install.sh \
  | AXIS_VERSION=v0.19.4 AXIS_REQUIRE_PINNED=1 AXIS_INSTALL_DIR="${HOME}/.local/bin" bash
"${HOME}/.local/bin/axis" version

From source (Go 1.26+, see go.mod):

git clone https://github.com/toasterbook88/axis.git
cd axis
make build
make install-user
"${HOME}/.local/bin/axis" version

Or install the tagged module into $(go env GOPATH)/bin:

go install github.com/toasterbook88/axis/cmd/axis@v0.19.4
axis version

2. Init and status

axis init is interactive. It writes ~/.axis/nodes.yaml (override the path with --config).

axis init
axis node facts
axis doctor
axis cluster status

axis cluster status reads the daemon publication when it is inside the 5-minute stale window and prints the source and age. Force a sweep with:

axis cluster status --live

3. Placement (advisory)

axis task place "run ollama inference on a 7b model"
axis placement explain "run ollama inference on a 7b model"

place and explain do not run the workload. Execution is a separate command: axis task run.

4. Serve, health, agent card

axis serve stays in the foreground. It is the same listener as axis daemon start. The default address is the Unix socket ~/.axis/axis.sock (--addr opts into TCP).

axis serve

In another terminal. /health and the agent card are public; the host in the URL is only a curl placeholder for --unix-socket:

curl -fsS --unix-socket "${HOME}/.axis/axis.sock" \
  http://localhost/health
curl -fsS --unix-socket "${HOME}/.axis/axis.sock" \
  http://localhost/.well-known/agent-card.json

TCP, if you pass --addr:

axis serve --addr 127.0.0.1:8082

curl -fsS http://127.0.0.1:8082/.well-known/agent-card.json

Check the daemon without curl, and install a user service (launchd or systemd) when you do not want a foreground process:

axis daemon status
axis daemon service install
axis daemon service status

The public card advertises streaming: false (sync send/get only; no subscribe/SSE). That is not an A2A TCK claim. Other API routes (/snapshot, /run, /a2a/v1/...) require Authorization: Bearer with the token in ~/.axis/token.

Fleet rollouts and mesh membership are operator-driven. AXIS does not auto-provision or auto-join a fleet.

What it is

AXIS discovers hardware on machines you already own (SSH, optional UDP beacons), builds deterministic cluster snapshots, and makes reservation-aware placement decisions. Optional surfaces add guarded task execution, resident model lifecycle, a local HTTP API, MCP, and an A2A agent-card / task plane.

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

Features

Core

• SSH fact collection and cluster snapshot assembly (live or daemon-cached)
• Deterministic placement. Ranking objective is allocatable_ram; FitScore is diagnostic suitability only
• Reservation ledger and reservation-aware status / place / context reads
• Guarded execution (axis task run, HTTP /run) with structured NDJSON streaming
• Optional daemon cache with explicit refresh / invalidate, plus launchd / systemd user service install

Models and agents (v0.19.x)

• Resident model lifecycle: axis model plan | start | await | query | stop | list
• Interactive TUI: bare axis on a TTY, or axis tui
• Tool-calling axis agent (console on a TTY; cache-first cluster context)
• Read-oriented MCP server (axis mcp serve) and MCP client (axis mcp client)

A2A (landed in 0.19.4)

• Per-node agent card at /.well-known/agent-card.json — #464
• Authenticated observe task send/get (POST /a2a/v1/message:send, GET /a2a/v1/tasks/{id}) — #465
• Approval queue for exec-shaped work (approve / reject; no auto-approve) — #466
• Delegate CLI: axis task delegate | status | approve | reject — #468

Architecture

Five layers. Each is subordinate to the one below. Advisory surfaces never override observed state.

┌─────────────────────────────────────────────────────────────┐
│  Layer 5  Advisory — agent · MCP · A2A cards/tasks · chat   │
├─────────────────────────────────────────────────────────────┤
│  Layer 4  Execution & lifecycle — guarded exec · models     │
├─────────────────────────────────────────────────────────────┤
│  Layer 3  Placement — Filter → Rank → Select                │
├─────────────────────────────────────────────────────────────┤
│  Layer 2  Snapshot — ClusterSnapshot · daemon cache         │
├─────────────────────────────────────────────────────────────┤
│  Layer 1  Fact plane — SSH probes · UDP beacons · mesh      │
└─────────────────────────────────────────────────────────────┘

Default HTTP / A2A listen address: Unix socket ~/.axis/axis.sock. TCP is opt-in via axis serve --addr.

Commands

Stable operator path

Experimental / advisory

axis chat and axis llm were removed. Use axis agent and axis ai route.

Full command notes: docs/current-state.md.

Documentation

Status

Build and test

make build       # CGO_ENABLED=0 go build -trimpath -o axis ./cmd/axis/
make install-user    # ~/.local/bin/axis
make test        # hermetic go test ./... plus docs tool tests
make test-race
make lint        # gofmt, go vet, staticcheck
make coverage    # hack/coverage-check.sh

Requires Go 1.26+ (go.mod is authoritative). make install-system installs to /usr/local/bin and needs sudo.

Contributing

See CONTRIBUTING.md. Protected main: required CI checks, squash-only merges. For AI agents: AGENTS.md.

License

MIT — Copyright © 2026 Smith Software Solutions

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