@boundless.md/setup

The Boundless setup wizard for your terminal.

npx -y @boundless.md/setup@latest

It does what boundless.md asks a coding agent to do, as a full-screen terminal app:

1. Inspects the machine: OS, shell, remote session, installed harnesses, an existing key.
2. Signs you in through your browser with the OAuth device grant, or shows a code when there is no browser.
3. Exchanges that approval for one inference key on your account. The secret is never printed.
4. Stores the key in the macOS Keychain, the Linux Secret Service, or a private 0600 file, and exports BOUNDLESS_API_KEY from your shell profile without ever writing the key into the profile.
5. Lets you pick a default and a background model from the live catalog, with prices.
6. Offers every harness on Coding Agents & Harnesses. It backs up and merges the configuration of those that keep it in a file, and prints the steps for those configured in an app's settings.
7. Sends one small request per model and wire format, with the exact cost, and reports what changed.

To put everything back the way it was before the first run:

curl -fsSL https://boundless.md/install | sh -s -- --revert

Setup records every file it backs up in ~/.boundless/setup-journal.json. Revert restores those backups (keeping the current version next to each file as .boundless-revert-…), deletes files setup created, removes the Claude Code router and the shell-profile export. The key itself stays on your account until you revoke it.

Project-only scope keeps the key in .boundless/api-key (git-ignored) and writes project-level configuration where the harness supports it.

Development

npm install
npm run build
BOUNDLESS_CONSOLE=http://localhost:3000 node dist/cli.js

BOUNDLESS_CONSOLE points the wizard at another console; it reads the OAuth client, issuer and gateway from GET /api/setup there. Plain HTTP is accepted for loopback only.

npm test

npm run e2e drives the built CLI in a pseudo-terminal through every wizard screen against a mock console (src/e2e/). npm run e2e:live feeds the production catalog through the same mock, and with SETUP_E2E_API_KEY=<key> adds a full run against the production console with that key.

Publishing

npm version patch
npm publish

The package is public under the @boundless.network npm organisation. npm publish runs prepublishOnly, which builds dist/.

Claude Desktop

User scope installs a local bridge in ~/.boundless/claude-desktop/ and points Desktop at http://127.0.0.1:18787. Desktop's credential helper starts the bridge when needed, including after a reboot. Keep Node installed at the path shown by setup. Project scope skips Desktop because its configuration applies to the whole user account.

Setup adds its own "Boundless" entry to Desktop's configuration library and applies it, leaving any other entry untouched. While it is applied, Desktop runs its separate third-party profile (Claude-3p/): claude.ai chats, projects, connectors and MCP servers from the normal profile do not show there. Nothing is deleted; revert (or picking another configuration in Desktop) brings them back.

Desktop filters model IDs by vendor. The bridge gives non-Claude models opaque routing aliases while the picker keeps their real Boundless names. Requests are translated back to the original model IDs before reaching Boundless; streaming responses and tool events pass through unchanged. This compatibility depends on Desktop's current model validation and may need updates when Desktop changes.

The bridge listens only on loopback and requires a separate local token. The Boundless key stays in its private config.json; it is never put in command-line arguments. Setup backs up the active Desktop configuration before changing it. Quit and reopen Desktop after setup, then start a new conversation with the model you want. Older conversations may retain their previous model selection.

To undo setup, quit Desktop and restore the .boundless-backup-* copy of its active configLibrary/<id>.json file. Remove the applied entry if setup created it, using Developer → Configure Third-Party Inference. The files under ~/.boundless/claude-desktop/ can then be removed once its bridge process exits.

Claude Code: Anthropic account + Boundless

Choose Claude Code → Anthropic account + Boundless in the wizard. It is a preview on Linux and Windows (see below). Requires Claude Code 2.1.282 or newer, Node 22 or newer, user scope, and an existing claude auth login using your Anthropic account. Restart Claude Code after setup.

In one conversation, use /model to select a native model such as Fable, then boundless/dsv4, then Fable again. Native choices use your Anthropic account; rows labelled Boundless use Boundless credits. Switching providers sends the conversation history to the selected provider. Existing account access and usage prompts still apply. The native default and background model aliases stay intact.

The router is part of this npm package (src/router/). Installation copies its runtime and private configuration to ~/.boundless/claude-code-router/ and installs a per-user login service named network.boundless.claude-code: a launchd agent in ~/Library/LaunchAgents/ on macOS, a systemd user unit in ~/.config/systemd/user/ on Linux, and a Task Scheduler logon task on Windows. It listens on a private loopback port, starts at login and restarts after a crash. Keep Node installed at the path used during setup; rerun setup after changing that path. Rerun setup to refresh the catalog or rotate your Boundless key.

Claude Code owns Anthropic login and token refresh. The router forwards that credential only to Anthropic; Boundless requests receive only the Boundless key. The router stores no Anthropic credential and logs no conversations. Its private configuration contains the Boundless key and a separate local access token.

npx -y @boundless.md/setup@latest --router status
npx -y @boundless.md/setup@latest --router restart
npx -y @boundless.md/setup@latest --router uninstall

Uninstall restores settings owned by setup while preserving later unrelated edits. Restart Claude Code after removal. Uninstall before selecting Boundless only. Backups of previous settings remain beside the settings file.

On Linux and Windows mixed mode is a preview: CI tests the service lifecycle there, but a live Anthropic-account conversation has only been qualified on macOS. Linux needs a systemd user session (systemctl --user); WSL without systemd and containers should use Boundless only. Conflicting shell/project credentials and managed device policies block mixed installation. With a custom endpoint Claude Code does not fetch server-managed organization policy, and Remote Control is unavailable; organizations requiring those features should not enable this mode. Anthropic does not officially support non-Claude gateway models. See verification and compatibility.