> ## 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.

# Run a Private Fleet

Reach every machine you own through your own gateway keys, manage them from the dashboard or CLI, and choose per machine whether idle capacity earns.

A private fleet is the set of machines you own, run as your own network, and on
B3IQ it is the **default**, not a toggle. Serving is always **own-nodes-strict**:
your gateway keys route only to machines your account owns, and B3IQ never
routes an outside caller onto your hardware. There is nothing to switch on to
make your fleet private.

What you *do* choose, per machine, is its **mode**:

| Aspect | Bare metal (default) | Earn |
| --- | --- | --- |
| Your inference | Serves 100% of your own traffic, free | Not reachable by your keys while in Earn |
| SSH & terminal | Available | Disabled until flipped back |
| External workloads | None | Offered to external GPU marketplaces |
| Health telemetry & alerts | Full | Liveness heartbeat continues; GPU and CPU metric sampling stops |

Request the change from the machine's page and the team schedules it with you,
in either direction. A machine in **Earn** mode is out of your serving pool
entirely. Earning is an explicit per-machine choice, never something that
happens to an idle machine on its own.

## "Private" means different things

| Term | What it controls | Where |
| --- | --- | --- |
| Private fleet | Own-nodes-strict routing: the default for every account; your keys only ever reach your machines | This guide |
| Private inference | Encryption of the prompt and output in transit (private_transport) | /protocol/privacy, /developers/private-jobs |
| Local serving + tunnel controls | Pausing a single machine locally, and rotating or revoking its route credential | /operators/node-dashboard |

## Assemble the fleet

**Own every machine in the fleet**

A fleet is the set of machines claimed to one account (or one organization;
    org-owned machines respect member roles). Claim each machine to the same
    owner: purchased machines arrive pre-onboarded and are linked by redeeming a
    claim code in the dashboard; hardware you enroll yourself uses an onboarding
    code from the B3IQ team. See
    [Run your first node](/guides/run-your-first-node).
  **Create a gateway key**

Any `b3iq_gateway_` key you create in the dashboard routes free across every
    machine on your account by default. Optionally narrow a key to specific
    machines with a node scope. The key is shown once and revocable. Save it to
    a file you control.

    **Never put the key in argv**

Process arguments are visible to other processes and land in shell history.
      Read `b3iq_gateway_` secrets from a `chmod 600` file or an environment
      variable, and pass them to curl through a temporary config file, never as
      a literal `-H` flag on the command line.
  **Call your fleet**

Send requests to the gateway with your key. Each one self-routes to a
    machine you own, free of charge; the `X-B3IQ-Router-Node-ID` response header
    tells you which machine served it. The code is in the next section.

## Call your fleet

Store the key in a locked-down file and point two environment variables at it.

```bash
umask 077
printf '%s\n' 'b3iq_gateway_...' > "$HOME/.b3iq/fleet-key"
chmod 600 "$HOME/.b3iq/fleet-key"

export B3IQ_GATEWAY_BASE_URL="https://b3iq.org/v1/api"
export B3IQ_FLEET_KEY_FILE="$HOME/.b3iq/fleet-key"
```

**List your fleet's models first**

The `model` field takes an id returned by `GET /v1/api/models`. The examples
  below use a representative id (`qwen3-8b`); list the live models your machines
  serve first, since the available ids change with what you have installed.

```bash curl
: "${B3IQ_GATEWAY_BASE_URL:?set B3IQ_GATEWAY_BASE_URL}"
: "${B3IQ_FLEET_KEY_FILE:?set B3IQ_FLEET_KEY_FILE}"

cfg="$(mktemp)"
chmod 600 "$cfg"
trap 'rm -f "$cfg"' EXIT
{
  printf 'url = "%s/chat/completions"\n' "${B3IQ_GATEWAY_BASE_URL%/}"
  printf 'request = "POST"\n'
  printf 'header = "Authorization: Bearer %s"\n' "$(sed -n '1p' "$B3IQ_FLEET_KEY_FILE")"
  printf 'header = "Content-Type: application/json"\n'
} > "$cfg"

# --dump-header surfaces X-B3IQ-Router-Node-ID so you can see which of your machines served.
curl --fail --silent --show-error --dump-header - --config "$cfg" --data-binary @- <<'JSON'
{
  "model": "qwen3-8b",
  "messages": [{ "role": "user", "content": "Say hello from my private fleet." }],
  "max_tokens": 64
}
JSON
```

```javascript fetch.js
import { readFileSync } from "node:fs";

const baseURL = process.env.B3IQ_GATEWAY_BASE_URL;
const token = readFileSync(process.env.B3IQ_FLEET_KEY_FILE, "utf8").trim();

const response = await fetch(`${baseURL}/chat/completions`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${token}`,
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "qwen3-8b",
    messages: [{ role: "user", content: "Say hello from my private fleet." }],
    max_tokens: 64
  })
});

// Which of your machines served the request.
console.log("served by", response.headers.get("x-b3iq-router-node-id"));
console.log(await response.json());
```

Inference on hardware you own is free. A fleet request records no charge.
Confirm it landed on one of your own machines by reading
`X-B3IQ-Router-Node-ID`, rather than by looking for a receipt.

## Reach your machines

Day-to-day fleet operations don't need a browser:

- **Fleet SSH keys**: add a public key once under **Settings → SSH keys** and
  it is installed on every machine you own, kept in sync automatically; remove
  it to revoke access everywhere. Per-machine keys, a browser terminal, and a
  native SSH lane (plain `ssh`/`scp`/`rsync`) live on each machine's detail
  page. SSH is unavailable while a machine is in Earn mode.
- **The b3iq CLI** (`npm i -g @b3dotfun/b3iq-cli`): `b3iq login`,
  `b3iq machines list`, `b3iq ssh <machine>`, `b3iq models install <model>
  --machine <m>`, `b3iq logs --follow`. See [b3iq CLI](/developers/cli).

## Blend models across your fleet

A gateway key can also run a [Mixture of Experts](/developers/mixture-of-experts):
attach `b3iq.mixture` to the same request and the fan-out runs across the
machines you own, still free. Each expert model needs to be installed on at
least one of your machines, and the request must not pin a machine (a mixture
spreads across the fleet by policy, so a pin returns a 400).

## Ownership is re-verified

B3IQ re-checks machine ownership on the server for every request, so a key can
  only ever reach machines owned by the same account. Even a leaked key cannot
  be pointed at someone else's hardware, and it cannot spend anything.
  Inference on your own machines is free. Still treat it like any gateway secret
  and revoke it if it is exposed. See [Security](/operators/security).

## Common blockers

**My key returns a no-healthy-candidates error**

Your fleet has nothing to serve the request right now. A key only reaches
    machines you own that are online, in Bare metal mode, and serving the
    requested model. Check that at least one machine is online with a fresh
    heartbeat and has that model installed. `b3iq status` shows this at a
    glance.
  **A machine stopped answering my keys after it moved to Earn**

Expected. An Earn-mode machine is offered to external GPU marketplaces and
    leaves your serving pool (SSH is disabled too). Ask us to move it back to
    Bare metal to reclaim it.
  **A machine is claimed but my key can't reach it**

Claiming alone does not bring a machine up. It still needs the full local
    path: online with a fresh heartbeat, a healthy route, and an installed model
    that answers. See [Route readiness](/operators/route-readiness).
  **My key works but I can't find a charge**

There isn't one. Inference on machines you own is free, whichever of your
    keys you use. Usage still shows up metered per key on the dashboard so you
    can see what ran, but no money moves.

## Related

**[Local, managed, network](/concepts/local-managed-network)**

The conceptual home of fleet operation and the B3IQ operating modes.
  **[Call the gateway](/guides/call-the-gateway)**

The hosted path your keys use: same base URL for every machine you own.
  **[b3iq CLI](/developers/cli)**

Manage the fleet from a terminal: machines, models, runtimes, logs, ssh.