Host Agent
The local B3IQ service for node identity, inventory, runtime probing, local APIs, receipts, heartbeats, and command polling.
The host agent is the local service that makes a machine usable as a B3IQ node. It owns local identity, machine inventory, setup APIs, runtime probes, model profile state, local auth, local API keys, receipts, heartbeats, and command polling.
Responsibilities
Generates and uses the node identity for enrollment challenges, signed heartbeats, command results, and payout report access.
Reads OS, CPU, RAM, GPU, disk, runtime, model, queue, and benchmark posture from the machine instead of trusting browser estimates.
Serves local setup endpoints, /v1/models, /v1/chat/completions,
model-profile readiness, receipt listing, and receipt submission.
Posts signed heartbeats and polls the control plane for narrow command workflows over outbound HTTPS.
Local Listener
The default local listener is:
texthttp://127.0.0.1:8831
Loopback is the default because setup, local auth, and local API keys are operator-controlled local credentials. LAN-exposed appliance installs require explicit configuration and network controls.
Data The Host Agent Protects
| Data class | Handling |
|---|---|
| Setup token | Bootstrap or recovery credential. Do not expose through public docs, logs, or remote support bundles. |
| Local API key | `b3iq_local_` secrets are shown once, stored hashed, revocable, scoped, and safe examples keep them out of argv. |
| Support grant | `b3iq_support_` secrets are expiring, revocable, hash-stored, and diagnostics-only. |
| Node private key | Never persisted in public payloads. Recovery flows must label secrets as one-time operator artifacts. |
| Prompts and outputs | Local request content stays local unless the operator sends it to a runtime or explicitly uses a routed workflow. |
Common Commands
bashb3iq-host wizard url
bashcurl --fail http://127.0.0.1:8831/health
bashb3iq-host chat --api-key-file .secrets/b3iq-local-key
Prefer --api-key-stdin, --api-key-file, or environment variables for local
CLI testing. Do not place b3iq_local_ secrets directly into command argv.
CLI Command Map
The host-agent binary is the day-to-day surface for setup, diagnostics, and local OpenAI-compatible testing:
textb3iq-host versionb3iq-host statusb3iq-host doctorb3iq-host runtimesb3iq-host enroll --url https://control-plane.b3iq.orgb3iq-host serve --listen 127.0.0.1:8831b3iq-host wizard urlb3iq-host openb3iq-host chat --api-key-stdin --prompt "hello"b3iq-host support-bundleb3iq-host logs -f
b3iq-host enroll on a machine B3IQ has not seen before currently requires a
B3IQ onboarding code (--code or B3IQ_LICENSE_CODE, or run
b3iq-host license redeem first) — B3IQ admits new hardware to the fleet
rather than opening it to self-service. Re-enrolling a known machine is
unaffected.
The binary also covers service install/start/stop, self-update, and headless setup. See CLI commands for the full host-agent command table and the monorepo build/test commands.
Local CLI vs Account CLI
b3iq-host is the daemon's own CLI — it only ever talks to the agent running
on the machine you're standing in front of. B3IQ also ships a separate
account-level CLI that manages your whole fleet remotely:
sign in once via a browser device flow, then list machines, install or remove
models, restart runtimes, tail logs, or open an SSH session against any
machine on your account from wherever you're working.
b3iq-host link-path (run automatically by every installer) puts a
b3iq command on your PATH that simply forwards to the local
b3iq-host daemon — it is not the fleet CLI. If the account-level CLI is
also on your machine, confirm which b3iq your shell resolves first before
relying on it; the two are unrelated binaries that happen to share a name.
Managed Node Behavior
The host agent does not need inbound networking for managed mode. It can:
- Request and sign enrollment challenges.
- Publish signed inventory and readiness heartbeats.
- Poll for commands over outbound HTTPS.
- Run narrow jobs such as benchmark smoke, tunnel health checks, model install, support bundle generation, and receipt submission.
- Submit signed command results and receipts.