Getting Started

Previous Next

Status: Current

This guide is the shortest path for a new user who wants to install Home AI Cluster, run it locally, and try its ordinary capabilities.

Home AI Cluster is an orchestration layer. It does not install, download, start, stop, or supervise AI runtimes or models. The default first-use path below uses an operator-managed local Ollama runtime with the llama3.2 model.

For exact command contracts and advanced options, use the command reference. For the canonical operational sequence and static multi-node operation, use the operator workflow.

Windows 11 x86_64

The supported native Windows installation path uses PowerShell with WinGet available. In PowerShell, run:

winget install --id astral-sh.uv -e --source winget
uv tool install home-ai-cluster
uv tool update-shell

WinGet installs upstream Astral uv; uv installs and isolates the ordinary HAC PyPI tool, so you do not need to install Python manually. Close PowerShell and open a new PowerShell session, then verify that HAC is available:

hac --version

This supported path is limited to native Windows 11 x86_64, PowerShell, and WinGet. HAC does not install or manage runtimes, models, plugins, or Windows system configuration. Continue with step 3 to prepare an operator-managed runtime.

1. Install uv (Linux and macOS)

Home AI Cluster uses uv for Python and package installation.

Install uv using the official procedure for your operating system:

On Linux and macOS, the official standalone installer can be run with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal if necessary, then verify the installation:

uv --version

2. Install a supported Python (Linux and macOS)

Home AI Cluster currently supports Python 3.13 and 3.14.

The simplest uv-managed path is:

uv python install 3.13

Verify that uv can see it:

uv python list

Using uv for Python is convenient but not an architectural requirement. An already installed compatible Python can also be used.

3. Install Ollama and the default model

The default Home AI Cluster runtime composition uses Ollama with llama3.2.

Install Ollama using its supported procedure for your operating system:

Ensure Ollama is running, then make the default model available locally:

ollama pull llama3.2

You can confirm that Ollama sees the model with:

ollama list

Home AI Cluster does not manage Ollama or model downloads. If Ollama is stopped later, start it using Ollama's normal operating-system procedure before using Home AI Cluster.

4. Install Home AI Cluster (Linux and macOS)

Install the current published package as an isolated uv tool:

uv tool install home-ai-cluster

uv tool install is the recommended first-use path because it keeps the HAC CLI in an isolated Python environment without requiring you to manage that virtual environment directly.

If you prefer pip, install HAC inside an explicitly managed virtual environment rather than into the system Python. For example:

python3.13 -m venv ~/.venvs/home-ai-cluster
source ~/.venvs/home-ai-cluster/bin/activate
python -m pip install home-ai-cluster

This guide uses the uv tool path for the remaining steps.

Verify the installed command:

hac --help

hac is the short ordinary command. home-ai-cluster is the equivalent long root command.

To update an already installed published HAC tool, use:

uv tool upgrade home-ai-cluster

This is the normal published-package upgrade path; it does not validate or install unreleased checkout work.

Optional: retain stable choices

The default first-use path needs no retained configuration. To keep a stable local runtime choice for later ordinary starts, use:

hac config local --runtime ollama --ollama-model qwen3:8b
hac config show
hac local

Later compatible runtime CLI values are temporary one-invocation overrides and do not rewrite retained configuration.

To use the optional local Image Generation companion with the same ordinary process, start and manage sd-server yourself, then retain only its loopback endpoint:

hac config image-generation --base-url http://127.0.0.1:<SD_SERVER_PORT>
hac config show
hac local

HAC does not configure an image model or manage sd-server. The companion is ignored when hac local --runtime-config <PATH> is explicitly selected; add an Image Generation binding to that complete file when it is needed there.

5. Start Home AI Cluster

Start the ordinary local process:

hac local

Keep this terminal open. The process runs in the foreground.

With the default host and port, Home AI Cluster is now available only on the local machine at:

http://127.0.0.1:25042/

This same process serves both the native local API and the fixed loopback browser interface.

6. Try the browser

Open this address in a browser on the same machine:

http://127.0.0.1:25042/

The current browser navigation is:

  • Chat;
  • Code;
  • Image;
  • Summarize;
  • Classify;
  • Configuration.

Chat includes an optional, page-local automatic External Information authorization and a separate explicit External Information operation. The explicit operation accepts an optional plugin override plus distinct QUERY and QUESTION fields; ordinary Chat Send does not submit those fields.

The browser is intentionally local and small. It is not a dashboard, LAN control surface, runtime manager, or persistent server-side conversation store.

For a first test, open Chat, enter a short message, and submit it.

Optional: trusted-LAN capability browser

Loopback remains the default. To expose the separate, capability-only browser to trusted peers, start HAC with one explicit concrete non-loopback LAN IP:

hac local --lan-browser-host <LAN_IP>

The loopback browser remains available. The trusted-LAN browser shows Chat, Code, Image, Summarize, and Classify, but does not expose Configuration, Workspace, or External Information authority. It is plain HTTP with no TLS or client authentication, so use it only where reachable peers and the network path are trusted. It is a separate listener from any receiver authority.

7. Try the command line

Leave hac local running and open a second terminal.

Chat

Send one request:

hac chat "Explain local-first AI in one sentence."

Or start an interactive terminal conversation:

hac chat

Use Ctrl-D or Ctrl-C to end the interactive session. Its successful conversation context exists only in that foreground client process and is not persisted.

Summarize

Summarize explicit text:

hac summarize --text "Home AI Cluster routes requests by capability rather than by machine or runtime brand."

Or summarize a UTF-8 text file:

hac summarize --file README.md

Classify

Classify text against an explicit ordered label set:

hac classify \
  --text "The invoice is due tomorrow." \
  --label invoice \
  --label personal

Code

Ask for bounded textual code assistance:

hac code "Write a Python function that returns the larger of two integers."

Or start an interactive Code conversation:

hac code

Use Ctrl-D or Ctrl-C to end the interactive session. As with interactive Chat, successful conversation context exists only in that foreground client process and is not persisted.

hac code returns text only. It does not execute generated code or grant shell, Git, repository, testing, or general filesystem authority.

Optional: Image Generation

Image Generation requires an explicitly configured and available Image Generation binding or companion. HAC does not manage sd-server or its model.

hac image-generation \
  --output generated.png \
  "A small cabin in a snowy forest"

generated.png must not already exist and its parent directory must already exist. Without --jpeg, HAC writes validated PNG bytes regardless of the file suffix. See the Command Reference for the exact output and JPEG-export semantics.

8. Stop Home AI Cluster

Return to the terminal running:

hac local

and stop it with normal process interruption, usually Ctrl-C.

Ollama remains operator-owned. Leave it running or stop it separately according to your own local setup.

9. Optional: use external information

Ordinary Home AI Cluster requests do not acquire Web information by default. External Information uses one separately installed compatible plugin. Installation alone does not select or perform acquisition, and retaining a plugin choice alone does not authorize Chat to disclose a question.

Choose either published plugin. The SearXNG plugin keeps acquisition against an operator-managed local SearXNG service. The Tavily plugin uses the external Tavily service, requires TAVILY_API_KEY in the caller environment, and discloses the explicit acquisition query to Tavily.

For an initial isolated HAC installation, choose one of these instead of the plain command in step 4:

uv tool install \
  --with home-ai-cluster-plugin-searxng \
  home-ai-cluster

uv tool install \
  --with home-ai-cluster-plugin-tavily \
  home-ai-cluster

If you already followed step 4, rebuild that isolated tool environment explicitly with your chosen plugin included:

uv tool install --force \
  --with home-ai-cluster-plugin-searxng \
  home-ai-cluster

uv tool install --force \
  --with home-ai-cluster-plugin-tavily \
  home-ai-cluster

uv tool gives HAC its own isolated environment. Each --with package is an additional requirement in that environment. uv tool install --force ... recreates it, so include every HAC plugin or other additional requirement that should remain installed; an omitted earlier --with dependency can be absent from the recreated environment. Repeat --with when installing multiple compatible packages. Installed packages and the one retained hac config external-information --plugin NAME selection are separate.

Explicit External Information

With SearXNG and hac local already running, retain that choice once, then use it for an explicit external-information request:

hac config external-information --plugin searxng

hac external-information \
  "local AI inference developments" \
  "What are the main recent developments?"

This explicitly acquires evidence for one source-grounded request: the first value is the acquisition query and the second is the question sent with the acquired evidence.

An explicit one-off override remains possible and does not change the retained selection:

hac external-information \
  --plugin <OTHER_NAME> \
  QUERY \
  QUESTION

For Tavily, set the caller credential and use the selected plugin:

export TAVILY_API_KEY="<YOUR_TAVILY_API_KEY>"

hac external-information \
  --plugin tavily \
  "Python 3.14 free-threading changes" \
  "What changed for free-threaded Python in 3.14?"

Manage or unset the environment credential according to your normal shell and security practice. Retaining tavily selects only that plugin for later explicit external-information operations; it does not retain or manage TAVILY_API_KEY.

One-shot Chat with retained automatic External Information authorization

A retained External Information plugin choice is also required for this flow. It is separate from, and does not grant, Chat disclosure authority. To retain the one-shot Chat authorization, run:

hac config chat --external-information-fallback

Then use ordinary one-shot Chat, for example:

hac chat "What is the weather in Agnone today?"

For an eligible question, HAC makes its existing bounded ordinary / external decision. Only the external branch performs acquisition, using the exact user question as its acquisition query. The authorization remains retained until you explicitly remove it:

hac config chat --reset

Interactive Chat with session-local External Information authorization

To authorize the same bounded decision path only for one foreground interactive Chat session, use the no-message form:

hac chat --external-information

This is TTY-only interactive Chat and uses the retained External Information plugin selection. Each eligible new user turn may take the existing bounded ordinary / external decision path. The authorization lasts only for this foreground session: it does not persist or enable the retained one-shot fallback authorization. Ctrl-D or Ctrl-C ends the session.

See the SearXNG plugin README, Tavily plugin README, and the hac external-information command reference for the exact HAC boundary.

10. Where to go next

If this local first run works, the useful next documents are:

A second machine is optional. Local-only operation remains the shortest and least complex ordinary Home AI Cluster path.

Home Command Reference