# `@inference/fast`

Connect Claude Code, Codex, Grok, OpenCode, and Pi to fast models on Inference.net.
The CLI signs in through the Inference dashboard, lets you choose a team and
project when more than one is available, and creates one machine-scoped project
API key.

## Install

```bash
npm install -g @inference/fast
```

## Use

```bash
fast login
fast models
fast claude on
fast claude on --model glm-5.2
fast claude on --main glm-5.2 --sonnet kimi-k3-fast
fast codex on --model glm-5.2
fast grok on --model glm-5.2
fast opencode on --build kimi-k3-fast --plan deepseek-v4-flash-0731
fast opencode status
fast pi off
fast claude on --new-key
fast key rotate
fast status
fast logout
```

`fast models` lists every model in the catalog with its context window, price
per million tokens, and capabilities; pass a substring to filter
(`fast models kimi`), `--endpoint messages` to see only models an agent can
talk to, or `--json` for scripts.

Calling a coding agent without `on` is equivalent to `on`, so `fast claude`
is enough. Claude Code has a default model per slot (`main`, `opus`, `sonnet`,
and `fable` use the default model; `haiku` and `subagents` use
`deepseek-v4-flash-0731`).
`--model` sets every slot at once; `--main`, `--opus`, `--sonnet`, `--haiku`,
`--fable`, and `--subagents` override one slot and win over `--model`. OpenCode
accepts `--build` and `--plan` the same way for its two primary agents. Every
`on` registers every model from the catalog in the agent's own model picker and
snapshots the agent's original config before changing it.
`off` restores that snapshot byte-for-byte. Every `on` re-validates the saved
machine key against the gateway. `--new-key` (or `fast key rotate`) archives
that key, creates a new one, and rewrites every connected agent with it.
`logout` restores every connected agent and disables the API key created for
this machine. The inference gateway
can retain an already-used key in its authentication cache for up to three
minutes before it starts returning unauthorized responses.

## Files

- Owner-private CLI state and transport credentials: `~/.inference-fast`
- Claude Code: `~/.claude/settings.json`
- Codex: `~/.codex/config.toml`
- OpenCode: `~/.config/opencode/opencode.json`
- Pi: `~/.pi/agent/{settings,models,auth}.json`

All CLI and harness files that can contain a credential are written with owner-
only permissions. Harness backups live under `~/.inference-fast/backups`.

## Local development

With relay, the inference gateway, and `fast-web` running locally:

```bash
INFERENCE_FAST_RELAY_URL=http://localhost:8888 \
INFERENCE_FAST_DASHBOARD_URL=http://localhost:3001 \
INFERENCE_FAST_API_URL=http://localhost:8788 \
bun run dev -- login
```

The dashboard and inference URLs are derived automatically from a localhost
relay unless explicitly overridden.

## Testing integrations

Three suites cover the harness integrations:

- `bun run test:integration` — hermetic; spawns the CLI against a local mock
  gateway and asserts the exact config every harness writes (all Claude slots,
  pickers, per-agent models, byte-exact `off` restore), plus drift between the
  shipped harnesses and the fast website's integration list. Runs in PR CI via
  `ci:build-and-verify`.
- `bun run test:e2e` (`tests/auth-flow/`) — the full auth flow against the
  LOCAL stack: a fresh account signs up, the CLI does the real device-code
  login (the test approves the code server-side, no browser), the relay mints
  a machine key through tRPC, and `fast <harness> on` writes config; `logout`
  restores and the disabled key is proven rejected by the gateway. Runs in the
  e2e harness (`[inference] fast-cli auth-flow e2e` job). Needs the local stack
  (`task run-test-harness-headless`) on current code — the CLI's catalog
  schema requires `supported_endpoints` on every model.
- `.github/workflows/inference--fast-cli-e2e.yml` — live end-to-end against
  **prod** (`api.inference.net`): installs the real harness binaries, connects
  them, and runs a two-turn probe per model — the second turn must reply and
  show a prompt-cache read covering most of the request (the "only the new
  message is uncached" invariant). Runs nightly against the latest
  `@inference/fast@beta` on npm. Prod because this is the release gate for the
  stack users actually hit, and many models are not hosted in dev. Its resolve
  step also carries the live-catalog contract (the CLI's default models must
  be present) so a serving-side catalog change fails the nightly run, not an
  unrelated PR.

To test any integration against any model(s) on demand:

```bash
gh workflow run inference--fast-cli-e2e.yml \
  -f harnesses=claude,codex \
  -f models=glm-5.2-fast,kimi-k3-fast \
  -f cli_source=npm-beta \
  -f enable_images=true
```

`harnesses=all` and `models=default` (the defaults) run every harness against
its default models. A model that is not in the prod catalog fails the setup
job before any install starts. The gateway converts every wire API
(`/v1/messages`, `/v1/responses`, `/v1/chat/completions`) for every hosted
model, so any catalog model can pair with any harness.

To run the same probe locally against prod with your own harness installs
(seed a config.json with a machine key first, e.g. by running `fast login`
against prod once and copying `~/.inference-fast/config.json`):

```bash
INFERENCE_FAST_CONFIG_DIR=<state-dir-with-config.json> \
INFERENCE_FAST_RELAY_URL=https://relay.inference.net \
INFERENCE_FAST_API_URL=https://api.inference.net \
HARNESS=claude MODEL=claude-haiku-4-5 \
bun run test:live
# add ENABLE_IMAGES=true MODEL_VISION=true to include the image probe
```