You install two things, usually on two machines.
On the GPU
Install Fabric
houdry servehoudry gpu register
Ollama running, with at least one model pulled.
On the desk
Install Agent
Point it at https://HOST:8080/v1
Do not install Fabric on every laptop.
One machine can be both (a workstation that also has a keyboard). Same commands. Agent then uses https://127.0.0.1:8080/v1.
GPU / ops workstation. This is the houdry CLI.
Desk app. Point it at https://HOST:8080/v1.
curl -fsSL https://raw.githubusercontent.com/houdry-genomex/houdry-agent/main/scripts/install.sh | bash1. GPU workstation: Houdry Fabric
This repo is houdry-genomex/houdry. The installer puts the houdry binary in ~/.houdry/bin.
Linux / macOS:
curl -fsSL https://github.com/houdry-genomex/houdry/releases/latest/download/install.sh | sh
export PATH="$HOME/.houdry/bin:$PATH"
houdry version
houdry gpu detect
Windows PowerShell:
irm https://github.com/houdry-genomex/houdry/releases/latest/download/install.ps1 | iex
& "$HOME\.houdry\bin\houdry.exe" version
& "$HOME\.houdry\bin\houdry.exe" gpu detect
Put ~/.houdry/bin (Windows: $HOME\.houdry\bin) on PATH so later terminals can run houdry without the full path.
Binaries also ship on the Fabric releases page (houdry-linux-amd64, houdry-windows-amd64.exe, and so on). Prefer the install script unless you need a specific architecture.
houdry serve listens on 0.0.0.0:8080 unless you pass --listen. That listener is HTTPS. There is no HTTP on the control-plane port.
2. Models: Ollama on the GPU host
Fabric’s working runtime is Ollama. Without it, chat has nowhere to run.
- Install Ollama from ollama.com.
- Pull at least one chat model, for example:
ollama pull llama3.2
For drawings / scanned PDFs, also pull a vision model your catalog expects (for example qwen2.5vl). Leave Ollama running.
A workstation with no discrete GPU can still run houdry serve as the control plane. Another box then registers as compute. With no READY GPU node, /v1 can still talk to Ollama on the serve host.
3. Start the fabric
Two terminals is the usual setup. Leave both running.
# Terminal 1: control plane (any machine on the Wi-Fi; GPU not required)
houdry serve --listen 0.0.0.0:8080
On first serve, Fabric writes a local CA at ~/.houdry/server/pki/root_ca.crt. Browsers, curl, and Agent must trust that file. Dashboard: https://127.0.0.1:8080/.
# Terminal 2: this GPU workstation
houdry gpu detect
houdry gpu register
gpu register is the same process as houdry node join. It finds houdry serve on the same Wi-Fi, stays READY, and takes work from Houdry Agent. Extra workstations only need detect + register. They do not start a second serve.
Do not use houdry gpu join. That is a one-shot inventory snapshot and does not run jobs.
On the serve machine run houdry node enroll create. It prints a one-time HDRY_… token (10 minutes, one use). Use that on the GPU host when register enrolls. Do not pass it as --token. --token on serve is the optional API key for chat, not enrollment.
If discovery fails (guest Wi-Fi):
houdry gpu register --server https://127.0.0.1:8080
Set HOUDRY_SERVER (and optional HOUDRY_TOKEN) so later CLI commands do not need --server every time. Config lives in ~/.houdry (HOUDRY_HOME overrides the directory).
4. Desk: Houdry Agent
This repo is houdry-genomex/houdry-agent. It is the desktop app, not the houdry CLI.
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/houdry-genomex/houdry-agent/main/scripts/install.sh | bash
Windows: download Houdry-Agent-*-win-x64.exe from Agent releases.
On first run:
- Choose Houdry server URL (not a public OpenAI / Azure endpoint).
- Same machine as Fabric:
https://127.0.0.1:8080/v1. - Another machine on the LAN:
https://HOST:8080/v1. The/v1suffix is required. - Model:
auto(the fabric router picks the GPU and the model). - Optional API key:
houdry(use this if you passed--tokentoserve).
If one control plane is visible on Wi-Fi, Agent can fill the URL. It looks for /.well-known/houdry.json on ports 18080, 8090, and 8080. Confirm with Connect. If you started serve with --listen on another port, paste that port.
Trust the Fabric CA on the desk if TLS fails: copy ~/.houdry/server/pki/root_ca.crt from the serve host.
Agent data:
- Linux / macOS:
~/.houdry-agent - Windows:
%LOCALAPPDATA%\houdry-agent
Check that it worked
On the GPU / ops machine:
houdry version
houdry gpu detect
houdry discover
houdry node list --server https://127.0.0.1:8080
discover should list the control plane. Open Agent and send “Say hello.” If chat fails, see Troubleshooting.