> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3iq.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

**Local identity**

Generates and uses the node identity for enrollment challenges, signed
    heartbeats, command results, and payout report access.
  **Runtime inventory**

Reads OS, CPU, RAM, GPU, disk, runtime, model, queue, and benchmark posture
    from the machine instead of trusting browser estimates.
  **Local APIs**

Serves local setup endpoints, `/v1/models`, `/v1/chat/completions`,
    model-profile readiness, receipt listing, and receipt submission.
  **Managed sync**

Posts signed heartbeats and polls the control plane for narrow command
    workflows over outbound HTTPS.

## Local listener

The default local listener is:

```text
http://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

**Wizard URL**

```bash
    b3iq-host wizard url
    ```
  **Local health**

```bash
    curl --fail http://127.0.0.1:8831/health
    ```
  **Plugins**

```bash
    sudo b3iq-host plugin list
    sudo b3iq-host plugin install inference
    ```

**Avoid process argv secrets**

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:

```text
b3iq-host version
b3iq-host status
b3iq-host doctor
sudo b3iq-host plugin list
b3iq-host enroll --url https://control-plane.b3iq.org
b3iq-host license redeem --code <onboarding-code>
b3iq-host serve --listen 127.0.0.1:8831
b3iq-host wizard url
b3iq-host open
b3iq-host support-bundle
b3iq-host logs -f
```

**New machines are onboarded by B3IQ**

`b3iq-host enroll` on a machine B3IQ has not seen before fails with
  `onboarding_code_required` unless a valid B3IQ onboarding code is in the
  environment as `B3IQ_LICENSE_CODE`. `enroll` reads that code from the
  environment only; the `--code` flag belongs to `b3iq-host license redeem`,
  which redeems a code against an already-enrolled node and claims it to the
  code's customer. B3IQ admits new hardware to the fleet rather than opening it
  to self-service, and sets the code while provisioning the machine. The gate
  applies only to node ids the control plane has never seen, so re-enrolling or
  rotating keys on a known machine never needs a code.

A machine boots without inference. Engines, models and the local chat API arrive
with the inference plugin, which the owner installs from the dashboard or root
installs with `sudo b3iq-host plugin install inference`. The plugin's own commands
(`runtimes`, `chat`, `provision-engines`) live in its binary,
`/usr/local/lib/b3iq/plugins/b3iq-inference`, which is not on `PATH`.

The binary also covers service install/start/stop, self-update, and headless
setup. See [CLI commands](/operations/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](/developers/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.

**Both CLIs answer to the name `b3iq`**

`b3iq-host link-path` (run automatically during provisioning) 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.

## Next

**[Setup wizard](/operators/setup-wizard)**

Walk through the operator setup flow served by the host agent.
  **[Local API](/developers/local-api)**

Use the host agent as a local OpenAI-compatible endpoint.
  **[Security](/operators/security)**

Review local auth, support grants, secret handling, and public boundaries.