Baseten Switch is a local macOS app and gateway that routes supported AI coding harnesses between their native providers and models served on Baseten. A global switch controls routing overrides, and per-client mappings select the model that serves each request. Claude Desktop can use a separate local gateway whose selected Baseten models remain available while overrides are Off.

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 --probe

The 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, Claude Desktop, 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 uninstall

baseten-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 sync

on 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 off

Open Clients → Claude Desktop in Switch. Use Manage models to choose the Baseten models offered to Claude, then choose Connect Claude Desktop…. Switch prepares the local gateway, validates Claude's configuration, and asks before restarting Claude. Save your work, then choose Restart and connect. Switch backs up the affected configuration files, creates a named gateway configuration, and opens Claude. Saved settings and an observed gateway connection are reported separately. If Claude has not connected, finish its startup prompts and choose Check again.

Automatic setup is currently verified for Claude Desktop 2.42304.0, 3.6556.1, and 3.6556.2. Other versions use the manual guide. Switch preserves unrelated local configurations and refuses automatic changes when Claude has managed preferences or unrecognized configuration files.

Set up manually remains available in the app. Its numbered guide includes copy buttons for the local URL, placeholder key, and authentication scheme, plus a configuration file that can be imported through Claude's configuration picker. The supported in-app configuration window is under Developer → Configure Third-Party Inference…, after enabling Help → Troubleshooting → Enable Developer Mode. Use provider Gateway, credential kind Static API key, the displayed loopback URL, the non-secret placeholder baseten-switch-local, and bearer authentication. Enable model discovery with an empty explicit model list; turn Chat on and Auto mode off. Choose Apply Changes, then Save & Restart.

Each selected model has a stable, opaque discovery ID, with its model name shown separately. Removing a model prevents new requests using either its discovery ID or saved routing alias; it does not retarget old IDs to a different model. After upgrading the beta, restart Claude and reselect a model if an existing conversation still refers to an older picker ID. Quit and reopen Claude after adding, removing, or reordering models. Switch shows a Restart Claude Desktop notice while model-list changes are pending. Make several edits, then use its restart action after saving your work; if Claude is closed, the action opens it. The notice clears when Claude fetches the current ordered model list. This action does not repeat gateway setup. Refresh models reloads the available Baseten catalog in Switch; it does not refresh Claude's cached picker. Switch keeps the Baseten provider credential in its existing credential store.

This beta uses Baseten-hosted open models with local conversation history. Standard Claude account history and subscription routing are separate. Use Desktop's standard Anthropic sign-in choice to return to its standard experience. Like Claude Code, the Desktop picker offers Baseten catalog models for users to try without requiring per-model chat or tool certification. Chat, tools, images, and long conversations may work differently by model. Adding a model is blocked when its known context limit is below 200K tokens, matching the Claude Code picker's safeguard; unknown context limits remain unverified. Cowork compatibility is not established by the gateway setup.

The Routing overrides toggle controls the other clients' routing policy. Desktop's gateway remains active when overrides are Off and never falls back to Anthropic. Stopping Switch's gateway leaves Desktop requests failing until the service is restored or Desktop is changed back to its standard configuration. The Desktop page reports local listener, authentication, and recent endpoint traffic separately. A successful model-discovery request confirms that Claude contacted the current gateway; it does not prove the current UI mode or model compatibility.

The CLI manages the same saved selection:

baseten-switch claude-desktop setup
baseten-switch claude-desktop status --json
baseten-switch claude-desktop models add <baseten-model-slug> --dry-run --json
baseten-switch claude-desktop models add <baseten-model-slug>
baseten-switch claude-desktop models remove <alias>
baseten-switch claude-desktop models move <alias> --before <other-alias>

Setup creates an empty selection on a dedicated 127.0.0.1:45274 listener (127.0.0.1:45374 in Preview). Start the gateway with baseten-switch up if it is stopped. CLI model edits made while it is stopped remain saved until applied.

Codex 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 baseten

The 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 off

Do 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 --probe

status 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, confirms the gateway has loaded the stored credential, and prints the current identity. status identifies the selected profile as OAuth or API key. Use baseten-switch auth reload to apply a credential change without repeating sign-in. Auth commands return nonzero if runtime application cannot be confirmed; the stored credential remains in place. Confirmation validates local loading, not access to a hosted model.

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 remove

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

Packaged releases check for a newer version once a day. The Mac app shows an update notice in its main window and a blue marker with an Update Available action in its menu bar. How to Update opens release notes and copyable installation instructions. Updates are installed manually; checking never restarts the gateway or changes routing.

The CLI can check explicitly, including when the gateway is stopped:

baseten-switch update check
baseten-switch update check --refresh
baseten-switch update check --json
baseten-switch update automatic off
baseten-switch update automatic on

Checks use the public Homebrew formula version and confirm its matching published GitHub release, including numeric beta releases. They require no GitHub or Baseten credentials. Successful results are cached for 24 hours; failed checks preserve the last confirmed release and back off before retrying. --refresh forces a manual check, even when automatic checks are off.

Interactive status, up, and doctor commands can show a short update hint on stderr. Piped output, JSON, help, and version output stay unchanged. Automatic checks do not run for development builds or the separate Preview app/runtime. Versions shipped before release discovery was added need one normal upgrade before they can discover subsequent releases.

For Homebrew installations:

brew update && brew upgrade baseten-switch
baseten-switch up
baseten-switch doctor

up leaves healthy current components alone and moves stale components to the new binary and app. Homebrew remains the canonical public install and upgrade channel.

Finish active coding requests before running up to adopt newly installed components. The update window detects a Homebrew or Nix CLI installation before showing package-manager commands; other installations use the release's installation guidance.

Inspect the exact removal first:

baseten-switch uninstall --dry-run

Then remove managed harness settings, processes, launch agents, runtime residue, and the Mac app:

baseten-switch uninstall
brew uninstall baseten-switch

The 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-switch

Uninstall 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.sh

See 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-switch

Upgrade and restart the locally running components:

nix profile upgrade --refresh baseten-switch
baseten-switch up

Homebrew is the supported path for the complete macOS product.

Baseten Switch is available under the MIT License.