Baseten Switch is a local macOS app and gateway that routes supported AI coding harnesses between their native providers and models served on Baseten. One global switch controls Baseten routing, and per-client mappings select the model that serves each request.
Beta: Baseten Switch is under active development. Interfaces, configuration, and behavior may change between releases. The current macOS build is ad hoc signed and not yet notarized by Apple, so first launch may require approval under System Settings → Privacy & Security.
The first public release supports macOS 13 or newer on Apple Silicon and Intel.
brew install basetenlabs/baseten/baseten-switch
baseten-switch setup
baseten-switch up --install
baseten-switch claude on
baseten-switch doctor --probeThe fully qualified Homebrew command adds Baseten's public tap and installs
both Baseten Switch and its Baseten CLI dependency. It requires no GitHub
login, separate brew tap, second install command, or local compiler. The beta
release includes a universal macOS artifact for Apple Silicon and Intel.
setup verifies the Baseten CLI and its current credential, opens
baseten auth login when needed, and creates the initial configuration.
It never overwrites an existing configuration. up --install installs the
user launch agents, starts the local gateway, installs Baseten Switch.app in
~/Applications, and opens the app. claude on connects new Claude Code
sessions to the gateway. The final command checks the complete request path
with a small live request.
By default, Baseten Switch uses the current
Baseten CLI profile for
authentication. Both browser OAuth and API-key profiles created by
baseten auth login work with the gateway. Baseten controls each API key's
permissions and resource access; Switch treats the key as an opaque
credential.
To keep Switch authentication independent of CLI account changes, open Overview → Authentication and save an API key. Switch uses that key until you replace or remove it. Removing it restores CLI authentication.
If macOS blocks the app's first launch, open System Settings → Privacy & Security, scroll to Security, and click Open Anyway. This control appears after a blocked launch attempt. A managed Mac may prohibit the override.
The menu bar app is the primary interface for daily use. It provides:
- the global Baseten routing switch;
- Claude Code and Codex model configuration;
- current health, active fallback, and authentication status;
- recent traffic, performance, and spend views;
- actions to start the system and run it at login.
After an upgrade, baseten-switch up adopts the new CLI and app version.
Run baseten-switch menubar when you only need to install, refresh, or reopen
the app from the current Homebrew package.
The app and CLI update the same configuration. You can use either interface without maintaining separate state.
Install the direct Baseten provider for Pi without starting Baseten Switch:
brew install basetenlabs/baseten/baseten-switch
export BASETEN_API_KEY="<your-api-key>"
baseten-switch pi install
pi --provider baseten --model <model-slug>pi install reads the visible model catalog through the Baseten CLI and adds
only the direct baseten provider to Pi. It joins exact model IDs with the
public models.dev catalog for reasoning and text/image
input capabilities. Models without an exact capability match use conservative
defaults and are reported during installation. The API key remains in the
environment; Pi's configuration contains only a $BASETEN_API_KEY reference.
The command does not create gateway configuration, install launch agents,
start the router or front door, or change another harness profile.
The Homebrew formula contains the optional Mac app archive, but this flow does
not install the app in ~/Applications or open it. Manage the direct provider
without running local services:
baseten-switch pi status
baseten-switch pi uninstallbaseten-switch claude on saves the previous Claude Code environment values,
points new sessions at Baseten Switch, enables deferred tool loading, and
enables Claude Code's attribution block for compatibility with Anthropic's
Auto mode checks. Restart Claude Code after enabling or disabling the integration.
New installations also append the configured Baseten rows to Claude Code's
/model picker. Claude continues to own and update its native model choices.
The picker rows use stable aliases from model_aliases, so selection and
routing refer to the same model identity.
Useful controls:
baseten-switch on
baseten-switch off
baseten-switch claude status
baseten-switch claude route
baseten-switch claude route sonnet zai-org/GLM-5.2
baseten-switch claude route sonnet native
baseten-switch claude subagents zai-org/GLM-5.2
baseten-switch claude picker status
baseten-switch claude picker enable
baseten-switch claude picker add <baseten-model-slug> --dry-run --json
baseten-switch claude picker add <baseten-model-slug> --alias <alias>
baseten-switch claude picker remove <alias>
baseten-switch claude picker syncon and off change one global routing switch. Saved model mappings remain
editable while routing is off. A Claude family can map to native, a
configured alias, or a Baseten model slug. Run
baseten-switch claude route <family> default to remove a family override.
On an existing installation without picker configuration,
claude picker enable enables an empty picker. Add each Baseten model you
want to expose with claude picker add; enabling the picker does not add
routing aliases as picker rows.
Picker add, remove, and reorder operations do not delete routing aliases or
change a running Claude Code session. Reopen /model after a change, and
restart Claude Code if the picker has not refreshed.
To restore the Claude Code setting that existed before setup:
baseten-switch claude offCodex support is opt-in. Install Codex CLI, start Baseten Switch, and create its managed profile:
baseten-switch codex on
baseten-switch codex route zai-org/GLM-5.2
baseten-switch codex status
codex --profile basetenThe first codex on may request permission to enable the parked Codex
listener. Baseten Switch writes ~/.codex/baseten.config.toml; it does not
modify ~/.codex/config.toml. Start Codex without --profile baseten to use
native OpenAI routing.
Remove the managed profile and restore any file it replaced:
baseten-switch codex offDo not override the managed profile's compatibility model with -m. Select
the upstream Baseten model with baseten-switch codex route instead.
baseten-switch status
baseten-switch status --verbose
baseten-switch doctor
baseten-switch doctor --probestatus summarizes the router, front door, Mac app, authentication, and
client routing state. doctor inspects the same path without changing it and
prints the first failure with a concrete fix. doctor --fix can apply
supported repairs after confirmation.
Baseten Switch stores configuration, local state, logs, and telemetry under
~/.config/baseten-switch/. The primary logs are:
~/.config/baseten-switch/logs/router.log
~/.config/baseten-switch/logs/door.log
Run baseten-switch auth login if the CLI credential expires, is rotated,
or needs to change. The command delegates authentication to the Baseten CLI,
reloads the gateway, and prints the current identity. status identifies the
selected profile as OAuth or API key. The gateway also watches the selected
CLI profile for login, logout, rotation, and profile changes.
A key saved in Switch takes precedence over CLI authentication. Manage it in Overview → Authentication, or read a key from a local file through stdin:
baseten-switch auth api-key set < /path/to/key-file
baseten-switch auth api-key removeOn macOS, Switch stores the key in Keychain, separately from Baseten CLI
credentials, with a distinct entry for each configuration path. Existing
owner-only .api-key files migrate to Keychain; Switch verifies the stored key
before removing the file. Other operating systems retain the owner-only file
beside the configuration. Keys are never included in gateway YAML or status
responses.
A saved key works without a CLI login. If Keychain is locked, access is denied, or a saved credential cannot be read, Switch reports an error instead of substituting CLI credentials. Restore access or replace/remove the saved key to recover. Saving checks the key's format; provider permissions are checked when it is used.
BASETEN_API_KEY is a separate environment fallback, not the selected CLI
profile. Switch uses it only when BASETEN_SWITCH_API_KEY_FALLBACK=1 and no
saved key or selected profile credential is available. A saved key takes
precedence over a selected OAuth or API-key profile, followed by the explicitly
enabled environment fallback.
Run baseten-switch doctor. If it reports disabled attribution, run
baseten-switch doctor --fix, approve the repair, and restart Claude Code.
brew upgrade baseten-switch
baseten-switch up
baseten-switch doctorup leaves healthy current components alone and moves stale components to the
new binary and app. Homebrew remains the canonical public install and upgrade
channel.
Inspect the exact removal first:
baseten-switch uninstall --dry-runThen remove managed harness settings, processes, launch agents, runtime residue, and the Mac app:
baseten-switch uninstall
brew uninstall baseten-switchThe default uninstall retains configuration, telemetry, logs, and backups. To remove those files as well, use this instead of the standard uninstall:
baseten-switch uninstall --purge --yes
brew uninstall baseten-switchUninstall never removes Baseten CLI credentials or keychain entries. If the app's Start at Login item prevents safe bundle removal, the command prints the manual action required in macOS System Settings.
Baseten Switch binds its services to the local loopback interface. It receives harness requests and credentials because it is in the selected request path. Request content leaves the machine only for the upstream chosen by the active routing policy. Baseten credentials go only to Baseten, and native credentials go only to their matching native provider.
Baseten-routed inference requests identify Switch and its version in the
standard User-Agent header and X-Baseten-Switch-Version. Switch does not
add a user or installation identifier. Switch does not add these markers to
native-provider requests.
Switch may route narrowly identified compatibility requests to a harness's
native provider even when ordinary requests are mapped to Baseten. For example,
recognized Claude Code Auto permission checks are sent to Anthropic and labeled
Auto check in the Requests view. These checks require credentials accepted
by Anthropic, and a native failure is returned directly instead of being
retried through Baseten. Other requests continue to follow the configured
routing policy.
Local telemetry contains request metadata, not prompts, responses,
credentials, headers, or request bodies. Disable future records by setting
telemetry_enabled: false in gateway.yaml, then reload the configuration.
Delete existing records from
~/.config/baseten-switch/telemetry/.
Request and response body capture is a separate, disabled-by-default local
feature. If an operator explicitly enables global.trace_capture, Switch can
store exact bodies in a separate private trace store. Those bodies can contain
prompts, responses, reasoning content, tool data, source code, credentials,
personal data, and regulated data. Switch does not upload captured traces.
Public model-catalog refreshes from models.dev send no credential or user-derived data. The unauthenticated administration API binds to loopback and must never be exposed on a network interface.
The generated configuration is
~/.config/baseten-switch/gateway.yaml. Prefer the Mac app or typed CLI
commands over direct edits; routing changes hot-reload without a restart.
See config/schema.md for every field and
config/gateway.example.yaml for the generated
shape. The Baseten CLI owns selected-profile credentials. If you explicitly
enable the environment fallback, store BASETEN_API_KEY and
BASETEN_SWITCH_API_KEY_FALLBACK=1 in
~/.config/baseten-switch/env, which must use mode 0600, rather than in
gateway.yaml.
The Go module in gateway/ builds the CLI, router, administration API, and
front door. The Swift package in mac/BasetenSwitch/ builds the native menu
bar app without external Swift packages.
scripts/build.sh
scripts/check.shSee CONTRIBUTING.md for contribution and dependency rules. See TESTING.md for test layers and isolation requirements.
The Nix flake is an alternate source build for Linux and Apple Silicon macOS. It does not include the signed Mac app or install the Baseten CLI dependency:
nix profile install github:basetenlabs/baseten-switch#baseten-switchUpgrade and restart the locally running components:
nix profile upgrade --refresh baseten-switch
baseten-switch upHomebrew is the supported path for the complete macOS product.
Baseten Switch is available under the MIT License.