Home AI Cluster

Local-first orchestration for personal AI runtimes.

Project maturity: early prototype.

User documentation: frian.github.io/home-ai-cluster

Home AI Cluster is an orchestration layer, not an LLM or inference engine. It presents multiple personal machines and replaceable AI runtimes as one capability-centered local system:

Many machines. One AI.

Architecture at a glance

A request names the capability it needs. Home AI Cluster routes it among the eligible declared nodes without making the caller choose a machine or runtime.

                         Home AI Cluster
                    "Many machines. One AI."


                           User / Tool
                               │
                               ▼
                     ┌───────────────────┐
                     │   HAC endpoint    │
                     │     /v1/chat      │
                     │                   │
                     │ capability: code  │
                     └─────────┬─────────┘
                               │
                               ▼
                     ┌───────────────────┐
                     │   Orchestrator    │
                     │                   │
                     │ capability-based  │
                     │      routing      │
                     └─────────┬─────────┘
                               │
             ┌─────────────────┼─────────────────┐
             │                 │                 │
             ▼                 ▼                 ▼
    ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
    │   Local node   │  │ Remote node A  │  │ Remote node B  │
    │                │  │                │  │                │
    │ capabilities   │  │ capabilities   │  │ capabilities   │
    │ • chat         │  │ • summarize    │  │ • chat         │
    │ • code         │  │ • classify     │  │ • code         │
    │                │  │                │  │                │
    │    adapter     │  │    HAC app     │  │    HAC app     │
    │       │        │  │       │        │  │       │        │
    │       ▼        │  │       ▼        │  │       ▼        │
    │    runtime     │  │    adapter     │  │    adapter     │
    │                │  │       │        │  │       │        │
    │                │  │       ▼        │  │       ▼        │
    │                │  │    runtime     │  │    runtime     │
    └────────────────┘  └────────────────┘  └────────────────┘

The capability labels are illustrative examples from the currently supported explicit capability vocabulary; they are declaration-owned routing eligibility, not runtime discovery or dynamic status.

The user addresses the cluster rather than selecting a machine or runtime brand for an ordinary request. Ordinary operation remains intentionally small, local-first, and explicit.

What works today

Topology declarations and runtime lifecycle remain operator-owned.

Deliberate boundaries

Home AI Cluster remains local-first, privacy-first, engine-independent, capability-centered, and architecture-before-implementation. Topology is explicit and static; operators own runtimes, models, remote processes, and declarations.

The project does not provide automatic discovery, scheduling or ranking, dynamic topology mutation, process supervision, a dashboard architecture, Kubernetes deployment, a model catalogue, broad OpenAI API emulation, bundled Web acquisition, a generic plugin system, or a general production security model. See the vision, foundations, principles, and non-goals for the project rationale.

Install and first use

For a complete first-use walkthrough, including uv, Python, Ollama, the default model, browser use, and first commands, see the Getting Started guide.

Installed package

The supported installed-package path uses the current published package release:

uv tool install home-ai-cluster

A repository checkout may contain unreleased development work. See the PyPI project for published package information.

The default path requires Python 3.13 or 3.14, uv, and an operator-managed local Ollama runtime with the default llama3.2 model available. Home AI Cluster does not install, download, start, stop, or manage the runtime or model.

Start the ordinary local process in the foreground:

hac local

From another terminal on the same machine, send one request:

hac chat "Hello"

The same fixed loopback process serves the browser at http://127.0.0.1:25042/.

Repository checkout

For development from a checkout, prepare the locked environment:

uv sync --locked
uv run home-ai-cluster-local

Then, from another terminal, send one request:

uv run home-ai-cluster-chat "Hello"

See Contributing for development and validation guidance.

Optional bounded integrations

The separate hac compatibility process offers deliberately incomplete, loopback-only OpenAI-compatible Chat access. hac aider is a bounded caller edge and does not imply support for every Aider version or mode. hac code returns textual code assistance, while hac code-file performs one bounded whole-file replacement; generated code is never automatically executed and these commands grant no general repository, shell, Git, testing, agent, or execution authority.

hac external-information explicitly uses one separately installed compatible acquisition plugin for one source-grounded Chat request. An operator may also authorize eligible one-shot hac chat to use that same bounded caller-owned plugin boundary. No provider is bundled, and the ordinary HAC server does not acquire external information by itself. Two published examples prove the same acquisition boundary with materially different provider ownership: the operator-managed local-service SearXNG plugin and the credentialed external-service Tavily plugin.

Use the command reference for exact syntax and boundaries, and the documentation index for retained integration evidence and proofs.

Operators can retain local runtime choices and static remote declarations with hac config; explicit invocation values remain temporary.

Documentation

For a first installation and local run, use the Getting Started guide.

For operating Home AI Cluster, use the canonical operator workflow, command reference, and configuration examples.

For architecture and project history, use the documentation and historical evidence index, RFC index, and completed roadmap.

For project direction and participation, see the vision, foundations, principles, non-goals, and contribution guide.

Founding milestone, contributing, and license

One endpoint. Two machines. One routed request.

This founding milestone established the core abstraction: multiple personal machines can participate in one capability-centered local system without becoming an infrastructure platform. Retained evidence is available through the documentation index.

Contributions follow the contribution guide. Home AI Cluster is licensed under AGPL-3.0-or-later; see the notice for associated notices.