Install and update

Switchboard uses the npm package @ruban24/switchboard, the executable switchboard, and the GitHub repository ruban-24/switchboard.

The Homebrew command uses ruban-24/homebrew-tap, which also distributes agex. Both installation methods use the compiled npm artifact for the selected version.

npm and npx

npm install -g @ruban24/switchboard
switchboard init
switchboard claude
# Or: switchboard codex

For a trial without a global installation:

npx --package=@ruban24/switchboard switchboard init
npx --package=@ruban24/switchboard switchboard claude

The package identifier includes the npm scope; the command does not. Pin the published version when reproducing a result, for example @ruban24/switchboard@0.1.0 for the first release.

Node.js 22.18+ and an installed, logged-in Claude Code or Codex are required. init detects agents, asks which to enable, offers Jev connection presets, and accepts an API key through hidden input. It saves connection.json with owner-only permissions beside policy.json. The CLI reads that file on launch.

For zsh, setup suggests $ZDOTDIR/.zshrc or ~/.zshrc. For bash, it suggests both .bashrc and the first existing login profile (.bash_profile, .bash_login, or .profile), creating .bash_profile if none exists. This covers login and non-login interactive terminals. You can choose another absolute path, such as ~/.zprofile, or skip the change. The marked block contains only SWITCHBOARD_HOME; it never contains the API key. Existing text and symlinked dotfiles are preserved.

The shell block is optional: default settings work immediately without restarting the shell. Re-running init can update the connection and managed block while preserving policy overrides. init --yes creates default policy without prompts; it does not save environment keys or edit shell profiles.

Installed commands do not load project .env files. The source command npm run switchboard -- ... loads the checkout’s .env.local if present. Environment values override saved connection settings. See classifier connections for TypeSafe, OpenRouter, Vercel, and compatible custom endpoints.

Setup and doctor make no AI calls. doctor checks enabled agents and credential presence, not key validity. Neither command installs or logs in to coding agents. A real routed task consumes classifier credits and native provider quota.

Supported platforms

Platform	Switchboard v0.2.0 status
macOS	Native interactive CLI adapters verified.
Linux	Native interactive CLI adapters verified in a Debian 12 ARM64 VM.
Native Windows	Unsupported in v0; publishing through npm does not add compatibility.
Windows with WSL2	A possible Linux environment, but not separately verified for this release.

See native CLI compatibility for tested agent versions. The Homebrew formula uses the same release archive on macOS and Linux.

Configuration locations

Variable	Purpose
SWITCHBOARD_HOME	Explicit directory for personal policy, connection settings, and saved routes.
XDG_CONFIG_HOME	If absolute and SWITCHBOARD_HOME is unset, use $XDG_CONFIG_HOME/switchboard; otherwise ~/.config/switchboard.
SWITCHBOARD_STATUSLINE	Set to off to disable Claude’s temporary Switchboard status line.

Provider, key, URL, and classifier model variables are listed in the connection guide. Routing choices belong in personal policy. Internal SWITCHBOARD_TOKEN and SWITCHBOARD_HOOK_URL values are generated per launch; do not set them yourself.

Homebrew

Install from ruban-24/homebrew-tap:

brew install ruban-24/tap/switchboard
switchboard init
switchboard claude

The formula belongs at Formula/switchboard.rb in that separate tap. It uses the exact compiled npm artifact and installs Node as a dependency. Choose npm or Homebrew for the global installation to avoid two package managers competing for the same command. npm distribution does not establish Windows compatibility.

Upgrade or uninstall

Use the same package manager that installed Switchboard. For an npm installation:

npm install -g @ruban24/switchboard@latest
switchboard doctor

For Homebrew:

brew update
brew upgrade ruban-24/tap/switchboard
switchboard doctor

Close running Switchboard sessions before upgrading, then relaunch. Personal policy and credentials are stored outside the package and survive an upgrade. Saved conversations keep their existing model and effort. For an npx trial, use npx --package=@ruban24/switchboard@latest switchboard doctor to select the latest published version, or replace latest with a version you want to reproduce.

To uninstall, exit running sessions and use the matching command:

# npm installation:
npm uninstall -g @ruban24/switchboard

# Homebrew installation:
brew uninstall ruban-24/tap/switchboard

An npx trial has no global Switchboard installation to remove. Uninstallation preserves personal state and native Claude/Codex installations and logins. The shared Homebrew tap can stay installed for agex or other packages.

If you enabled shell integration, edit the profile files listed by init and remove only the block from # >>> Switchboard >>> through # <<< Switchboard <<<. Bash setup can add it to both a login profile and .bashrc. Open a new shell afterward, or run unset SWITCHBOARD_HOME to clear that variable in the current shell.

To remove saved data too, record the policy directory reported by doctor before uninstalling. After all routed sessions have stopped, you can delete connection.json to remove the saved classifier key, or remove that whole configuration directory to delete policy, routes, and usage records as well. Deleting routes prevents automatic resume of their conversations. This does not revoke the provider key or remove native transcripts or backup copies; use the provider’s account controls to revoke a key you no longer need.