# Sference Switch > A macOS app and local gateway that routes Claude Code between Anthropic and sference model by model, so Claude models keep working alongside open models. Codex is supported through an opt-in profile. Source: https://sference.com/docs/sference-code/switch **Sference Switch** is a macOS menu bar app with a local gateway. It routes the coding agents you already use, Claude Code and Codex, between their native providers and open models served by sference. One switch turns sference routing on or off, and per-client mappings choose which model serves each request. [`sference launch claude`](https://sference.com/docs/sference-code/claude-code) runs one Claude Code session entirely on one sference model. Switch is for keeping both: Claude models still go to Anthropic with your normal login, sference models appear next to them in `/model`, and you can send whole model families to an open model, such as the `sonnet` family that sub-agents often request. Once connected, it applies to every Claude Code session you start. > **Beta** > > Sference Switch is under active development, and its interfaces and configuration may change between releases. It requires macOS 13 or newer (Apple Silicon or Intel). The build is not yet notarized by Apple, so on first launch you may need to allow it under **System Settings → Privacy & Security → Open Anyway**. ## Install ```bash curl -fsSL https://get.sference.com | sh ``` The installer downloads the latest release, verifies its checksum, installs the `sference-switch` CLI to `~/.local/bin` and the app to `~/Applications`. Homebrew and administrator rights are not needed. ## Get started Open the app, then: 1. **Sign in.** Go to **Account → Sign In**. The app shows a verification code and opens the approval page in your browser. 2. **Turn on the Switch.** This turns on sference routing. No administrator password is needed. 3. **Connect Claude Code.** Run this once in a terminal. The app does not do this step for you: ```bash sference-switch claude on ``` Then restart any Claude Code sessions that are already running. New sessions pick it up automatically. 4. **Pick a model.** In Claude Code, run `/model`. Sference models are listed next to the Claude models. For a 1M-context model, choose the entry whose id ends in `[1m]`; Claude Code assumes any other unrecognized model holds only 200K tokens. Claude models keep working as before. Anything you don't route to sference goes to Anthropic with your normal login. ## What the app shows - **Switch**: global routing on/off. Your model mappings are kept while it is off. - **Account**: the signed-in sference account and session state. - **Live request path**: for each client, the gateway's health, the model that is actually serving requests, and the fallback. - **Traffic** and **Requests**: recent requests, latency, and spend. - **Clients**: per-client model mapping for Claude Code and Codex. ## Claude Code `sference-switch claude on` edits the `env` block of `~/.claude/settings.json`. It sets `ANTHROPIC_BASE_URL` to the local gateway and `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`, and fills Claude Code's `/model` list from the gateway. It backs up any values it replaces, and `sference-switch claude off` restores them. Check the current state with `sference-switch claude status`. No credential is added to Claude Code. Your claude.ai login stays the active one, so your organization's claude.ai connectors keep working. You can map whole Claude model families to a sference model, for example so that sub-agents requesting `sonnet` run on GLM: ```bash sference-switch claude route sonnet zai-org/GLM-5.3 sference-switch claude route sonnet native # send this family back to Anthropic sference-switch claude route sonnet default # remove the override sference-switch claude subagents zai-org/GLM-5.3 ``` **Coming soon.** Mapping a family to `sference/auto` is not available on the public API yet ([auto model routing](https://sference.com/docs/sference-code/auto-model-routing)). Intended command: ```bash sference-switch claude route sonnet sference/auto ``` ## Codex Codex support is opt-in. Switch writes a separate profile (`~/.codex/sference.config.toml`) and does not modify `~/.codex/config.toml`: ```bash sference-switch codex on sference-switch codex route zai-org/GLM-5.3 codex --profile sference ``` The first `codex on` may ask to enable the gateway's Codex listener. Choose the sference model with `sference-switch codex route`, not Codex's `-m` flag, which would override the profile's model. Start Codex without `--profile sference` to use OpenAI as usual. `sference-switch codex off` removes the profile. To configure Codex by hand instead, see [Codex](https://sference.com/docs/sference-code/codex). ## Turning it off Flip the Switch off in the app, or run `sference-switch off`. Every request then passes through to its native provider, but Claude Code still connects through the local gateway. To disconnect Claude Code from the gateway completely, also run: ```bash sference-switch claude off ``` While Claude Code is connected, the gateway has to be running, including for requests that go to Anthropic. If it is stopped, Claude Code cannot reach any model. Start it with `sference-switch up`, or disconnect with `sference-switch claude off`. `sference-switch uninstall --dry-run` shows everything a full uninstall would remove. `sference-switch uninstall` restores Claude Code's settings and removes the Codex profile, the app, and the background services. It keeps configuration, logs, and telemetry unless you pass `--purge --yes`. > **Upgrading from 0.1.x** > > Versions before 0.2.0 routed Claude Code by adding an entry to `/etc/hosts` and installing a root system service. 0.2.0 removed both. If `sference-switch doctor` reports a leftover `/etc/hosts` block, remove it with: > > ```bash > sudo sference-switch hosts-clean > ``` ## How it works Claude Code sends its requests to the gateway on `127.0.0.1`. For each request, the gateway checks the model against your mappings. Requests for sference models go to sference with your sference credential. Everything else goes to Anthropic unchanged, with your own login. The gateway runs as two user-level background services. It needs no `/etc/hosts` entry, certificate authority, or root service. - **Everything stays on loopback.** The gateway and its admin API bind only to `127.0.0.1`. - **Credentials go only to their own provider.** Your sference credential is sent only to sference, and your Anthropic or OpenAI credentials only to Anthropic or OpenAI. - **Telemetry is local, metadata only.** Records contain no prompts, responses, headers, or credentials. To stop recording, set `telemetry_enabled: false` in `~/.sference/switch/gateway.yaml`. Existing records are in `~/.sference/switch/telemetry/`. ## Troubleshooting ```bash sference-switch status sference-switch doctor --probe ``` `doctor` checks the whole request path and prints the first failure with a concrete fix. Logs are in `~/.sference/switch/logs/`: `router.log` for routing and `door.log` for the endpoint Claude Code connects to. If your session expires, sign in again from the app or with `sference-switch auth login`. Source, the full command reference, and releases: **[github.com/s-ference/sference-switch](https://github.com/s-ference/sference-switch)** (MIT). - [SferenceCode](https://sference.com/docs/sference-code): All harnesses, model choices, and when to use Switch or sference launch. - [sference launch](https://sference.com/docs/cli#launch-a-coding-agent): Run Claude Code, Codex, opencode, or Pi on sference for one session. - [Claude Code](https://sference.com/docs/sference-code/claude-code): Model recommendations, known limits, and manual configuration.