Houdry

Houdry Fabric and Houdry Agent

Architecture

Fabric on GPU workstations. Agent on the desk. HTTPS /v1 on the LAN.

Houdry splits compute from the people using it.

On the desk

Houdry Agent

Chat, Knowledge, SOPs, files, and local tools.

Talks to Fabric at https://HOST:8080/v1

On the GPU

Houdry Fabric

houdry serve is HTTPS on port 8080.

houdry gpu register runs Ollama and returns the answer.

People never talk to the GPU process. They talk to Agent. Agent talks to Fabric. Fabric picks a model on a READY GPU.

Two Fabric processes, plus the desktop app

What you runProductWhat it does
houdry serveFabricHTTPS API, dashboard, LAN announce, router. Default 0.0.0.0:8080.
houdry gpu registerFabricStay READY, claim jobs, run Ollama. Same as houdry node join.
Houdry AgentAgentChat, sessions, knowledge, local tools. Calls POST /v1/chat/completions.

houdry gpu join is a one-shot inventory snapshot and does not run jobs.

One machine can run serve and register together. Extra GPU boxes only run register. End users never talk to the GPU process.

What a request does

  1. Step 1

    Prompt

    Operator types in Houdry Agent.

  2. Step 2

    LAN call

    POST /v1/chat/completions with model auto.

  3. Step 3

    Route

    Fabric scores the task against READY GPUs.

  4. Step 4

    Infer

    That workstation runs Ollama and streams tokens.

  5. Step 5

    Reply

    The answer shows up in Agent. Files stay on-prem.

Analyze is a heuristic (keywords, length, images, tools), not a second LLM call. Scoring prefers a loaded, right-sized model on a READY node. Vision attachments go to a vision-capable model when one is available.

With no READY GPU node, the same /v1 talks to Ollama on the serve host (live streaming, vision). When a GPU registers, that URL starts dispatching cluster jobs. You do not change the Agent URL.

Agent settings

SettingTypical value
ProviderHoudry server URL
Base URLhttps://HOST:8080/v1
Modelauto (fabric router)
API keyhoudry if serve was started with --token

Same machine as Fabric: https://127.0.0.1:8080/v1. Browser dashboard is https://HOST:8080/ (no /v1). Agent needs /v1.

Data directory:

  • Linux / macOS: ~/.houdry-agent (HERMES_HOME overrides)
  • Windows: %LOCALAPPDATA%\houdry-agent

Fabric state lives under ~/.houdry (HOUDRY_HOME overrides). First serve writes $HOUDRY_HOME/server/pki/root_ca.crt. Generated files can be served from /files/.

Node and job states

Nodes: JOINED (inventory only, not schedulable), READY, BUSY, DRAINING, OFFLINE (stale heartbeat).

Jobs: queued, pending (assigned, waiting for claim), running, succeeded, failed.

Network

  • Fabric announces on the LAN (_houdry._tcp and UDP 41808).
  • Agent and extra GPU nodes browse for that announce. Agent also probes /.well-known/houdry.json on ports 18080, 8090, and 8080.
  • Guest Wi-Fi that isolates clients blocks discovery. Paste a URL instead.
  • GPU node APIs use mTLS after houdry node enroll create. Chat /v1 does not require a client cert.
  • There is no cloud LLM hop. Pull the WAN cable; chat against local models still works if Ollama and Fabric are up.
  • Do not bind houdry serve to the public internet.

Next

CLI
Every houdry command.
Configuration
URLs, tokens, data dirs.
Platforms
What runs where.