The right coding-agent account, and the right MCP servers, for the folder you're in.
EnvRouter is for people who use more than one account with their coding agents. Run claude in
~/dev/work and it uses your work config with your work MCP servers; run it in ~/dev/personal
and it uses your personal ones. There are no aliases to remember, no wrapper commands and
nothing to reload.
It's a desktop app for macOS and Linux, including WSL 2, and an envrouter command for machines
without a desktop.
You define profiles. Each profile has trigger folders, a config folder per agent, and a selection of MCP servers from a library you keep in the app:
| Agent | Command | Variable EnvRouter sets | How it hands over MCP servers |
|---|---|---|---|
| Claude Code | claude |
CLAUDE_CONFIG_DIR |
--mcp-config=<file> |
| Copilot CLI | copilot |
COPILOT_HOME |
--additional-mcp-config=@<file> |
| Codex CLI | codex |
CODEX_HOME |
--config=mcp_servers.<name>={…}, one inline table per server, no file; no SSE servers |
- 👤 Per-folder accounts. Each profile points an agent at its own config folder, so logins, settings and history stay separate. The deepest matching folder picks the profile.
- 🔌 Per-folder MCP servers. Keep one server library and choose which profiles load each server. Turn off individual tools per profile once a check has listed them.
- 📥 Import, paste and catalog. Bring in the servers your agents already define (EnvRouter only reads their files, Codex's TOML included), paste a server's JSON or TOML straight from its README, search a catalog of nearly 90 vendors' own servers (hosted or local, and what each needs to sign in), or add one by hand. Duplicate a server or a profile to start from one you have.
- 🔑 Secrets in your system's store. API keys and tokens you enter go to the macOS Keychain,
the Linux keyring, or, inside WSL, the Windows Credential Manager. Never
config.jsonor a rendered file. A server the agent runs as a command gets its own when it starts, in its own environment rather than the agent's, and, kept in an environment variable or a header, never on a command line. - 🧩 Editor extensions too. Claude Code for VS Code (and in Cursor, Windsurf, VSCodium) runs
its own copy of
claude; Editors… routes it through EnvRouter as well, including VS Code connected to WSL or over SSH. - 💻 A CLI for headless machines.
envroutersets up and checks routing on a server or in a WSL distro, without the window. - 🔍 Folder check. Drop a folder on the window (or press ⌘O; Ctrl+O on Linux) and EnvRouter starts your shell the way a new terminal window would, then reports what running the agent there would really do, including an alias, a shell function, or a prompt hook (mise, direnv) getting in the way.
- 🪶 No background process. A small shim does the routing when you run a command. Config changes apply on the next run in every open terminal, with the app closed or open.
- 🛟 Never in the way. If the config is missing or broken, the agent still runs, without a profile. EnvRouter never signs you in to anything.
- macOS 11 Big Sur or later, on Apple Silicon, with Safari 16.4 or later: the window is drawn by the system's WebKit, which Safari updates bring, and its styles need 16.4's. Intel Macs should work the same way but haven't been tried, and the bundle is arm64-only for now.
- Linux on x86_64 or aarch64: Ubuntu 22.04 or newer, or a distro of the same age, and WSL 2.
The app needs WebKitGTK 4.1, which the
.debinstalls. Secrets need a keyring (GNOME Keyring or KWallet); in WSL they go to Windows instead, through a helper that comes with EnvRouter. - zsh, bash or fish.
- Claude Code, Copilot CLI or Codex CLI, installed the usual way.
EnvRouter is pre-release. The macOS app is signed ad hoc rather than with a paid Apple Developer ID, so it isn't notarized: install it with Homebrew, which clears the download's quarantine flag, or build it yourself. Native Windows support is planned.
With Homebrew:
brew install --cask pixel-perfect-software/tap/envrouter
open /Applications/EnvRouter.appFrom the latest release,
take the .deb (Debian, Ubuntu and their relatives) or the AppImage (any distro) for your
architecture: amd64/x86_64 or arm64/aarch64. The .deb is about 7 MB and uses your
system's WebKitGTK; the AppImage is about 85 MB because it carries WebKitGTK with it, so it
runs where webkit2gtk-4.1 isn't packaged. Both work in WSL 2.
sudo apt install ./EnvRouter_<version>_amd64.deb # then open EnvRouter from your apps
# or
chmod +x EnvRouter_<version>_amd64.AppImage && ./EnvRouter_<version>_amd64.AppImageenvrouter does the same setup without the window, for servers, WSL distros and scripts:
brew install pixel-perfect-software/tap/envrouter-cli
envrouter install # the shim and helpers, into ~/.envrouter/bin
envrouter shell on zsh # or bash, fishOn a Mac with the app installed, skip envrouter install: the app keeps ~/.envrouter/bin
current itself. Without Homebrew, unpack envrouter-cli-<version>-<target>.tar.gz from the release (for example
envrouter-cli-0.11.0-x86_64-unknown-linux-gnu.tar.gz)
and run ./envrouter install from that folder.
Every release comes with SHA256SUMS; sha256sum -c SHA256SUMS --ignore-missing checks the
files you downloaded. From 0.7.1 on, every file also has a signed build provenance attestation,
which ties it to the release workflow run and the tagged commit that built it. With the
GitHub CLI:
gh attestation verify envrouter-cli-<version>-<target>.tar.gz --repo pixel-perfect-software/env-router \
--signer-workflow pixel-perfect-software/env-router/.github/workflows/release.yml--signer-workflow accepts only files built by the release workflow.
The cask and formula come from pixel-perfect-software/homebrew-tap. Every build in a release comes from its tagged source, built by this repository's release workflow on GitHub Actions. Installing by full name trusts only that cask or formula, not the whole tap.
You need, once:
- On macOS, Xcode's command line tools:
xcode-select --install. On Linux, a C toolchain and the WebKitGTK development packages: on Debian or Ubuntu,sudo apt install build-essential libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev - Rust, from rustup.rs. The repository pins its toolchain in
rust-toolchain.toml, and rustup installs that version on first build. (Homebrew'srustdoesn't read the pin; if you use it, match the version by hand.) - Node.js 24 or later, from nodejs.org or
brew install node - pnpm:
npm install -g pnpm. The project pins its own pnpm version, and pnpm fetches it. - cargo-about, which writes the third-party notices every build carries:
cargo install --locked --features cli cargo-about
(With asdf, asdf install sets up the Node and pnpm versions pinned in
.tool-versions instead of steps 3 and 4.)
Then clone and build:
git clone https://github.com/pixel-perfect-software/env-router.git
cd env-router
pnpm install
pnpm bundle # tauri build, with LICENSE and the third-party notices inside
# macOS: copy the app into Applications
ditto target/release/bundle/macos/EnvRouter.app /Applications/EnvRouter.app
open /Applications/EnvRouter.app
# Linux: install the package it built
sudo apt install ./target/release/bundle/deb/EnvRouter_*.debFor the CLI alone, cargo build --release -p envrouter-cli -p envrouter-shim -p envrouter-keychain
and then target/release/envrouter install. The first build takes a few minutes.
- Create a profile (⌘N; Ctrl+N on Linux). Give it a name, add its trigger folders with
Add Folder…, and set a config folder for each agent you want to route, such as
~/.claude-work. EnvRouter creates missing config folders inside your home folder when you save, and again when an agent starts in a folder whose config folder has been deleted. An agent a new terminal can't find on itsPATHis still offered, marked Not installed (with its vendor's install line), so you can set it up first. - Turn on your shell. Click the shell status in the toolbar (the
zshandbashdots) and switch on the shells you use. This adds a marked block to the end of each startup file that puts EnvRouter's shims first onPATH. - Open a new terminal window,
cdinto a trigger folder and runclaude,copilotorcodex. A new config folder starts logged out, so sign in once there as usual. - Check it. Drop a folder on the window, or press ⌘O (Ctrl+O), to see which profile a new
terminal window would use there and what it would set. From a terminal,
envrouter checkdoes the same, andENVROUTER_EXPLAIN=1 claudeprints the route as JSON instead of running Claude.
To route an editor extension, open Editors… (the </> button in the toolbar) and switch on
the editor. It points the extension's process-wrapper setting (claudeCode.claudeProcessWrapper
for Claude Code) at EnvRouter; new sessions in that editor then use the folder's profile.
EnvRouter never replaces a wrapper you set yourself. The button appears once EnvRouter finds an
editor with an agent extension it can route.
To start a profile from one you have, right-click its card and choose Duplicate Profile… (or Duplicate in its editor). The copy keeps the agents, servers and turned-off tools, but no folders, since a folder belongs to one profile.
Switch to MCP Servers (⌘2; Ctrl+2). The list on the left is your server library; the editor
beside it changes one server at a time. A server reaches an agent only in the folders of the
profiles that use it. Once the library grows past a handful, a Filter servers field appears
above the list: it matches the name, the command or URL, and the arguments (so an npx package
or a Docker image), and Escape clears it. Right-click a server, or use the … that appears on
its row, for Duplicate…, Check Server and Delete….
-
Add from Catalog (the package icon): search the vendors' own servers. Filter by where they run (Hosted by the vendor, or Runs locally on your machine) and by what they need (No sign-in, Sign-in, Secret). Picking one opens the editor filled in, with any secret fields empty and the expected format as a hint. An
npxserver comes pinned to the package's current release. -
Import from Your Agents (the import icon): lists the servers your agents already define, in Claude Code's
.claude.json(your home folder and each profile's config folder) and any.mcp.jsonin a trigger folder, and in Copilot'smcp-config.jsonand the.mcp.jsonand.github/mcp.jsonin a trigger folder, each written with anmcpServerswrapper or as a bare table of named servers. Codex CLI keeps its servers in TOML, so the[mcp_servers.<name>]tables ofconfig.toml(your~/.codexand each profile'sCODEX_HOME) and of a trigger folder's.codex/config.tomlare listed too. Tick the ones to bring in. Values that look like credentials go to your system's secret store, and Docker or Podman servers get--initso the container stops with the agent. EnvRouter never changes those files, and a server already in the library is shown as such.From Codex, a server's
command,args,env,urlandhttp_headerscome as they are, and the variables Codex passes by name (env_vars,env_http_headers,bearer_token_env_var) come as${NAME}references, which go back to Codex as the same fields. A server that signs in its own way (oauth,oauth_resource,scopes,http_headers_helper, anauthother thanoauth), runs somewhere else (cwd, a remoteenvironment_idorenv_varssource), holds an inlinebearer_token, or sets bothcommandandurlis left out, since it couldn't be imported right, and so is one you turned off there (enabled = false). Codex's own tool filters (enabled_tools,disabled_tools), timeouts and the like aren't carried: set the tools in the profile instead, or they all show until you do. A name Codex allows and agents don't (docs.search) is offered under one they accept (docs-search), so the original inconfig.tomlruns beside it under Codex until you remove it. -
Paste JSON (the clipboard icon): paste a server's config as its README or an agent's file writes it: an
mcpServersblock, VS Code'sservers, a bare table of servers, or one server on its own. Codex's TOML works too:[mcp_servers.<name>]blocks, bare[<name>]ones, or one server'scommandorurlfields. Comments and trailing commas are fine. One server opens in the editor; several open the import review. ⌘Return (Ctrl+Return) continues. -
Add Server (the plus): fill in the editor by hand. Connects with picks a command the agent starts (with arguments and environment variables), or a URL (HTTP or SSE) with headers. Codex CLI has no SSE transport, so an SSE server reaches Claude Code and Copilot CLI, not Codex.
Switch a profile on in the server's Used by row, or tick the server in the profile's own MCP servers checklist. Both change the same thing. Each profile card lists its servers; click a name to open it.
Every value field has a lock at its right edge. Click it to keep that value in the macOS
Keychain, the Linux keyring or, in WSL, the Windows Credential Manager, instead of
config.json. A new value under a name like API_KEY or Authorization starts locked. A stored
value shows as In Keychain (In the keyring, In the Credential Manager) and is never
shown again; Replace
sets a new one. EnvRouter also warns when a value that looks like a credential would be saved as
plain text, such as an --api-key= argument or a password in a connection string.
With no store to keep values in (no Secret Service running on Linux, say), the lock is off and the editor says why; values are saved in config.json and flagged as such.
Give a server its secret through an environment variable or a header. An argument can hold one too, under every agent, but the value then sits on the server's command line once it starts (and while you check it), where other programs you run can read it.
A server the agent runs as a command and that needs a secret starts through EnvRouter's
helper. Where the agent would run the server, it runs ~/.envrouter/bin/envrouter-keychain exec <file>; the helper reads that server's values from the store, then replaces itself with the
server's own command, so the values are in that server's environment (or arguments) and nowhere
else. It reads them every time the server starts, so a value you Replace applies the next
time the server starts, with no need to restart the agent. If the store can't be read or a value
isn't in it, that server doesn't start: the agent shows it as failed, and EnvRouter's reason is
one line in the server's error output, wherever the agent shows that. The other servers load.
The helper also fills in a ${NAME} or ${NAME:-default} in that server's other values, as the
agent would, from the environment the agent starts it with (EnvRouter tells Copilot CLI and Codex
CLI, which pass a server only some of theirs, which variables to hand on). One that isn't set
and has no default stops that server the same way.
A remote server (a URL) has no process of its own to start, since the agent sends its headers. The shim reads the values and gives them to the agent in its environment, which the agent puts into the headers. One it can't read is left out, with a warning when the agent starts. Privacy and security says what that means for who can see them.
Claude Code and Copilot CLI load a file EnvRouter wrote. Codex has no such flag, so each server
reaches it as one --config=mcp_servers.<name>={…} argument, a TOML table holding the whole
server, and nothing is written to disk for it. That has some consequences:
- Lock what's secret. Codex expands no
${VAR}in a server's values. EnvRouter tells it to read a variable where a whole value is one: an environment variable set to${SAME_NAME}, a header that is${VAR}, orAuthorization: Bearer ${VAR}. Anything else reaches the server as typed. And the table is on Codex's command line, so a value you leave unlocked (a plain environment variable, a plain header, an argument) can be read by other programs you run. A locked value in an environment variable or a header isn't on it: a command server gets it from the helper as it starts, and a remote server's header only names the variable the shim sets. - In a folder with servers, Codex runs without its shared background server. Given any
configuration override,
codex,codex resumeandcodex forkrun the session themselves instead of handing it to the background server.codex queue,archive,unarchive,deleteandremote-controlare left alone by EnvRouter, also with your own options ahead of them (codex -C ~/proj queue …), because they refuse an override or would write session state through a second server; they get no servers and need none. - A server named like one of yours in Codex's own
config.tomlmerges with it. Codex joins the two key by key, so the same transport works (EnvRouter's fields win, yours still apply). A different transport, say a command in one and a URL in the other, stops everycodexcommand in that folder with an error ending inurl is not supported for stdio. EnvRouter warns when you save, and Check Folder shows it with the file to open (envrouter checkprints it and exits 1); it reads theconfig.tomlof the profile's Codex folder (~/.codexwhen it doesn't set one) and the checked folder's.codex/config.tomlfiles that Codex trusts. Rename one of them, or runENVROUTER_MCP=0 codexmeanwhile. codex_appsandcodex_tuiare Codex's own servers' names, so a server in your library can't take either name while Codex is set up.- Sign-ins are Codex's:
codex mcp login <name>. They're kept in the system's keyring by server name and URL, so every profile shares them.
Check Server starts the server (or calls its URL), lists its tools and stops it again. Once a server has been checked, each profile that uses it can turn individual tools off: open the profile, expand the server's All 9 tools line under MCP servers, and untick tools, or use All On and All Off. A tool turned off in a profile stays available in the others.
An npx server with no version, or with @latest, runs whatever npm has newest when an agent
starts it, so a new release (or a bad one) reaches every session the day it's published, with
the server's secrets in its environment. The editor says so under Arguments: Pin Version
asks your own npm (npm view, so your registry and ~/.npmrc apply) for the current release and
writes it into the argument (chrome-devtools-mcp@0.9.0). A pinned server shows its version, and
Check for Update offers Update to … when a newer release is out. Nothing changes until you
save.
Remote servers that need a login sign in through the agent (/mcp in Claude Code), not through
EnvRouter. Duplicate in the editor's footer starts a new server from this one, with its
secret fields empty; Delete… removes it from the library and from every profile.
On macOS, EnvRouter lives in the menu bar: closing the window only hides it; quit from the menu bar icon. On Linux, closing the window quits; routing keeps working without it. The window opens where you left it, at the size you left it, on the view (Profiles or MCP Servers) you left it on. The menu bar's menu carries Check Last Folder (the folder you last checked in the window; greyed out until there is one) and the version.
Settings… (⌘, on macOS, Ctrl+, on Linux) opens the Shells panel: EnvRouter has no Preferences window, since shells are the one setting. The Shells panel also links to the documentation and to Report an Issue; on macOS the Help menu has both.
The keyboard reaches everything the pointer does. The arrow keys, Home and End move between the
profile cards, the servers in the list and the entries in the catalog (Tab leaves the list rather
than stepping through each one); the context-menu key (or Shift+F10) opens a card's or a row's
menu under it. ⌘N (Ctrl+N) starts a new profile on Profiles and a new server on MCP Servers, and
⌘S (Ctrl+S) saves whichever editor is open. When a check can't start (the profile editor is open,
or config.json can't be read), EnvRouter says why instead of doing nothing.
To see EnvRouter's own files, the menu bar icon's menu and the Shells panel show config.json in
Finder (Files off macOS) and open ~/.envrouter, and a profile card's right-click menu opens the
folder its MCP files are written to.
envrouter runs the same operations as the window:
| Command | Does |
|---|---|
envrouter or envrouter status |
The shim, each shell and editor, and the config. --agents also says which agents a new terminal doesn't find (an Agents line, or missingAgents in --json), by running your login shell; without it nothing runs one, and missingAgents is null |
envrouter install |
Installs the shim, the secrets helper and the CLI into ~/.envrouter/bin, and a shim per agent. When that changes the installed files, it renders the MCP files again to match, and asks the system's store once to let the new helper in |
envrouter shell on|off <zsh|bash|fish> |
Adds or removes the block in that shell's startup files |
envrouter editor on|off <editor> [--agent <command>] |
Routes an editor extension (code, cursor, remote-code for the VS Code Server, …) |
envrouter check [folder] [--tool <command>] [--shell <shell>] |
Starts a shell the way a new terminal would and reports what running the agent there does; exits 1 unless it's routed, and when Codex won't start there because one of its own files defines a server of the profile's with the other transport |
envrouter explain [folder] [--tool <command>] |
Which profile the saved config picks, without starting a shell |
envrouter apply |
Validates ~/.envrouter/config.json after you edit it by hand, and renders its MCP files and shims |
envrouter secret set <ID> |
Stores the value of a server's secret in the system's store: piped in, or typed without echo; never on the command line |
envrouter secret list |
Each secret the config refers to, the servers that use it, and whether it's stored (unknown when the store can't be read) |
envrouter uninstall [--yes] [--dry-run] |
Turns routing off everywhere, deletes the stored MCP secrets, ~/.envrouter and the window's own data, and names the commands that remove the app and the CLI (see Uninstall below) |
envrouter rpc |
Answers the window's commands as JSON lines, one per line each way, so another program (later, a window managing a WSL distro) can drive this machine |
--tool defaults to claude; pass --tool copilot for Copilot CLI or --tool codex for Codex CLI. --shell defaults to your
login shell. Add --json to any command for machine-readable output.
The window and the CLI can both change the config while the window is open. When the window
saves, it keeps whatever else changed in config.json meanwhile, and asks first only when the
same profile or server changed in both places.
On a server or in a WSL distro, write ~/.envrouter/config.json yourself and run
envrouter apply. A profile names its trigger folders, a config folder per agent and the
library servers it loads; a value kept in the secret store is written { "secret": "<ID>" },
with an ID of uppercase hex:
{
"version": 7,
"profiles": [
{
"id": "work",
"name": "Work",
"triggerPaths": ["~/dev/work"],
"tools": {
"claude": { "envVar": "CLAUDE_CONFIG_DIR", "path": "~/.claude-work" },
"copilot": { "envVar": "COPILOT_HOME", "path": "~/.copilot-work" }
},
"mcpServers": { "github": { "disabledTools": [] } }
}
],
"mcpServers": {
"github": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": { "secret": "A1" } }
}
}
}envrouter apply # validates it, fills in what each agent needs, renders the MCP files
envrouter secret set A1 # paste the token, then Return (or: … secret set A1 < token.txt)
envrouter explain ~/dev/work # Work: CLAUDE_CONFIG_DIR=~/.claude-work, with MCP servers githubEach profile needs its own id: it names the folder the profile's MCP files are rendered into,
so apply refuses two profiles with the same one. Once a profile uses a server, its id may hold
only letters, digits, - and _. A copied profile block needs a new id as well as a new name.
A hand-written config doesn't need the agents section: apply adds each agent's MCP and
editor details to it, and install and editor use them without saving. The CLI fills in
agents the config doesn't name yet, and adds the newest rules for runs that take no injected
servers to the ones it does; it leaves the rest of an agent as it is, and where the app is
installed it leaves the app's own shim and helper in place.
A WSL 2 distro is a Linux machine: install EnvRouter inside it, not on the Windows side.
- Install inside the distro: the CLI (
brew install pixel-perfect-software/tap/envrouter-cli, or the release archive), thenenvrouter installandenvrouter shell on bash(or your shell), and set up profiles without the window. The.debworks too; its window opens on your Windows desktop through WSLg. - Secrets go to the Windows Credential Manager. A distro usually has no keyring of its own,
so EnvRouter's Windows helper (
~/.envrouter/bin/envrouter-keychain.exe, installed with the rest) keeps them on the Windows side, per distro. It needs WSL's Windows interop, which is on by default. Store one withenvrouter secret set <ID>, or in the window. The distro's name comes fromWSL_DISTRO_NAME, which WSL sets in its terminals; the first time one of them uses the store, EnvRouter notes the name in~/.envrouter/wsl-distro, so a process started without the variable finds the same secrets. Until then such a process can't tell which distro it is and says so; runenvrouter secret listonce in a WSL terminal. - VS Code on Windows, connected to the distro, runs the Claude Code extension inside WSL.
Route it with
envrouter editor on remote-code(or Editors… › VS Code Server), which sets the wrapper in the distro's server settings. - Keep repositories in the Linux filesystem (
~/…), not under/mnt/c: Windows drives are slow to resolve from WSL, and their folder names aren't case-sensitive.
EnvRouter uses shims, like mise or Volta.
~/.envrouter/shims/<tool>is a symlink to~/.envrouter/bin/envrouter-shim, a small Rust binary.- A marked block at the end of your shell startup file puts
~/.envrouter/shimsfirst onPATH. - Each time you run a tool, the shim reads
~/.envrouter/config.json, finds the profile for the current folder, sets that tool's variable, adds that profile's MCP servers to the command line, andexecs the real tool found later onPATH. - When you save, the app writes each profile's MCP server files in each agent's own format, so
servers keep working with the app closed. A server the agent runs as a command and that needs a
secret is written to run through a small helper,
envrouter-keychain exec, which reads the secret from the system's store as the agent starts the server and runs the server's command with it. For a remote server, the shim asks the helper to read the secret and passes it to the agent in its environment, where the agent puts it into the server's headers. - An editor extension that runs its own copy of the agent runs it through the shim instead
(
envrouter-shim <its binary> <args>, or<interpreter> <script> <args>for a build that ships a script), so the same routing applies there.
The most specific folder wins outright. The deepest trigger folder containing the current folder picks the profile. If that profile doesn't set the tool you're running, the tool runs with its default config; it does not fall back to a profile further up. Folders are compared after resolving symlinks and letter case, and a trigger covers its whole subtree.
| Where | What |
|---|---|
~/.envrouter/config.json |
Your profiles and server library |
~/.envrouter/bin/ |
The shim and the secrets helper, which also starts the command servers that need a secret (on Linux also its Windows build, for WSL), and the CLI if you installed it from a release archive; updated by the app when it starts |
~/.envrouter/shims/ |
One symlink per routed command |
~/.envrouter/mcp/ |
Rendered MCP server files per profile and agent (readable only by you). For a command server that needs a secret, stdio/<server>.json holds what the helper starts it from: the server's command, with each secret as a reference to the store, never the value. A server you remove stays there for ten minutes, since a running agent may start it again |
~/.envrouter/mcp-tools.json |
Tool lists from server checks |
~/.envrouter/last-folder.json |
The folder you last checked, for the menu bar's Check Last Folder |
~/.envrouter/wsl-distro |
In WSL only: the distro's name, noted the first time a terminal uses the secret store. The Credential Manager item is keyed by it, and a process the distro starts without WSL_DISTRO_NAME (a systemd user unit, cron, an agent that passes a bare environment) reads it here |
~/.envrouter/checked-once |
Made the first time a folder check finds an agent routed, so first-run's last step is not shown again. Also made when you update from a release up to 0.7.2 that was already set up (a profile, a shell turned on) |
~/Library/Application Support/ca.pixel-perfect.envrouter/.window-state.json (macOS), ~/.config/ca.pixel-perfect.envrouter/.window-state.json (Linux) |
The window's size and position, written when the app quits. The view it was left on is kept in the window's own web storage. Releases up to 0.7.2 kept these under another bundle identifier; the first launch copies the window's size and position over and deletes that identifier's folders (the window's storage and caches, which can't move: the system keys them by identifier). The view you left on is reset once. If an older copy of the app is still running, the folders are cleared at a later launch, after it quits |
| "EnvRouter MCP secrets" in the system's store | Secret values you've entered, once there are any: in the login Keychain on macOS, the keyring on Linux, the Windows Credential Manager from WSL |
| Shell startup files | A block between # >>> envrouter >>> and # <<< envrouter <<< in ~/.zshrc (or $ZDOTDIR/.zshrc); for bash, ~/.bashrc on a Linux desktop, or the login file (and ~/.bashrc) on macOS and in WSL; or fish's config.fish |
| An editor's settings | claudeCode.claudeProcessWrapper, once you turn the editor on in Editors… |
Your agents' own config folders are yours; EnvRouter only creates missing ones.
EnvRouter has no account, no telemetry and no background process. It makes network requests
only when you check an MCP server (a remote one, or an npx one npm has to download) or look up
a package's version, which runs your own npm. Secret values never appear in config.json or in
a rendered file, and the window never reads them back once they're saved. Where they go depends
on the server:
- A server the agent runs as a command gets its secrets from EnvRouter's helper, which reads
them from the system's store as the server starts and puts them in that server's own
environment. They are not in the agent's environment, so not in anything else the agent runs.
The helper also removes any
ENVROUTER_SECRET_*variable it inherited before it starts the server, so a server never gets the secrets of the agent's remote servers. - A remote server's header secrets are still in the agent's environment, as
ENVROUTER_SECRET_<ID>, for as long as the agent runs: the agent expands them into the headers it sends, so it has to have them. Claude Code passes its environment on to the commands it runs for you, its hooks, and its command servers that need no secret, so those can read them. - A secret in an argument is on that server's command line while it runs, where other programs you run can read it; one in an environment variable or a header isn't.
- Under Codex, every unlocked value is on Codex's command line. Codex takes a server as an
argument, so a plain environment variable, header or argument of a server is in
codex's argument list for as long as it runs, visible to other programs you run. Credential-looking values start out locked, and the editor warns about plain ones. A remote server's locked headers are in Codex's environment, as for Claude Code. - Any program that runs as you can run the helper and ask it for the secrets, the same as it could before: the system's store is what stops it (on macOS, the Keychain asks the first time and each time the helper changes; choose Always Allow). The protection is against accidental exposure, such as the agent's environment, its logs and the commands it runs, not against another program you run.
- An allowlist that matches a server's exact command sees
envrouter-keychain exec <file>instead of that command, for a server that needs a secret. An administrator who keeps such a list has to allow the helper (the server's real command is then not checked), or the server's value has to stay plain, unlocked, inconfig.json. A server with no secret keeps its own command.
| Problem | Try |
|---|---|
| The agent ignores the profile | Check the folder in the app (⌘O, Ctrl+O) or with envrouter check. It names what's in the way: the shell block is off, an alias or function, another copy earlier on PATH, or a prompt hook (mise, direnv) moving one ahead. Remember to open a new terminal window after turning a shell on. |
| You want to see what the shim would do | ENVROUTER_EXPLAIN=1 claude (or copilot, codex) prints the profile, variable, MCP servers and real binary as JSON, without running the tool. |
| You want one run without EnvRouter's MCP servers | ENVROUTER_MCP=0 claude, or pass --strict-mcp-config to claude. |
Claude Code exits at startup with You cannot dynamically configure MCP servers when an enterprise MCP config is present |
Your organization manages MCP servers on this machine (managed-mcp.json in /Library/Application Support/ClaudeCode/ or /etc/claude-code/). EnvRouter leaves its servers off wherever that file exists and says so when claude starts; the folder still gets its profile's config. |
An MCP server doesn't show in claude mcp list or copilot mcp list |
Expected: those commands don't list servers passed on the command line. Use /mcp inside the agent. codex mcp list does show them, unmarked, along with the ones in Codex's own config. |
Every codex command in a folder fails with url is not supported for stdio (or the reverse) |
A profile's server and one in Codex's config.toml (or a trusted project's .codex/config.toml) share a name but not a transport, and Codex merges the two. EnvRouter warns when you save, and Check Folder shows it as "codex won't start here" with the file to open; envrouter check prints it and exits 1. Rename one, or run ENVROUTER_MCP=0 codex to skip EnvRouter's servers for that run. |
| Codex has no shared background server in a folder | Expected where the profile has MCP servers: Codex runs without it when given any configuration override. Folders with no servers, and codex queue, archive, unarchive, delete and remote-control everywhere, are unaffected. |
| Saving a secret fails on Linux with "there's no Secret Service" | Install and start GNOME Keyring or KWallet, then save again. Until then a remote server that needs a secret is left out, and a command server that needs one doesn't start (the agent shows it as failed); the rest still load. |
A server fails with envrouter: … is gone, so EnvRouter no longer starts the MCP server … |
The profile no longer has that server, and the agent session began before you removed it. Restart the agent. EnvRouter keeps a removed server's file for ten minutes, so a session can still reconnect to it for a while. |
A server fails with envrouter: couldn't read the secrets the MCP server … needs |
The store refused, or didn't answer within 20 seconds. On macOS a Keychain prompt for envrouter-keychain may be waiting behind another window; choose Always Allow, then restart the agent or reconnect the server. The store's own reason is in the parentheses. |
A server fails with usage: envrouter-keychain read [ID...] |
The helper in ~/.envrouter/bin is older than the files that name it, which happens when an older app starts after a newer CLI and puts its own helper back. Update the app and the CLI together, then save once in the app or run envrouter apply. |
| A command server that needs a secret is blocked by your organization's MCP allowlist | The agent runs ~/.envrouter/bin/envrouter-keychain exec <file>, not the server's command (see Privacy and security). Ask for the helper to be allowed, or unlock the value so the server keeps its own command. |
| Saving a secret fails in WSL with "couldn't reach the Windows Credential Manager" | Run envrouter install so ~/.envrouter/bin/envrouter-keychain.exe is there, and check that WSL interop is on ([interop] enabled isn't false in /etc/wsl.conf). |
The window says it can't read config.json |
It isn't valid JSON, usually a hand edit that stopped halfway. Open config.json (or Reveal) lets you fix it, and the window reads it again. Back Up and Start Over… copies the file to ~/.envrouter/config.json.bak (config.json.bak-2, … if one is already there; earlier backups are never replaced) and starts with no profiles or servers. It offers nothing for a file from a newer EnvRouter or one it can't read at all. Your MCP secrets, shims and agents' config folders stay as they were, and the secrets the backup names stay in the store for as long as the backup is there, so putting it back (mv config.json.bak config.json) brings its servers' secrets with it. Agents keep running without a profile meanwhile. |
| macOS says EnvRouter can't be opened | The app is signed ad hoc, not notarized. Homebrew's cask clears the quarantine flag that triggers this; for a copy you downloaded or built elsewhere, run xattr -dr com.apple.quarantine /Applications/EnvRouter.app. |
With Homebrew, brew upgrade --cask envrouter for the macOS app (it quits EnvRouter first; open
it again afterwards), and brew upgrade envrouter-cli for the CLI, followed by envrouter install where the CLI is what installed the shim. On Linux, install the new .deb or AppImage
over the old one. From source, pull the latest code,
quit EnvRouter, and run the build and install commands again. When a new version of the app
starts, it updates the shim and helpers in ~/.envrouter/bin itself, and renders the MCP files
again so they match. envrouter install does the same when it installs something new.
Update the app and the CLI together. The helper in ~/.envrouter/bin is whichever one was
installed last, and the MCP files of servers that need a secret depend on it: if an older app
starts after a newer CLI, it puts its older helper back without rendering anything, and those
servers fail with a usage line until you save once in the app or run envrouter apply. Files
rendered before this change keep working with the new shim and helper, with the secrets read as
before, until the next time they're rendered.
One action leaves the machine as if EnvRouter had never been installed, except for the app and the CLI, which can't remove themselves. Do it before you remove them: Uninstall EnvRouter… (at the bottom of the toolbar's Shells panel, and in the menu bar icon's menu on macOS), which asks first, or
envrouter uninstall # shows what it will do, then asks
envrouter uninstall --dry-run # shows it and changes nothing
envrouter uninstall --yes # doesn't ask; required without a terminalIt does five things, in this order:
- Turns routing off in every shell: it removes the marked block from every startup file that has one, whether or not that shell is on now.
- Clears
claudeCode.claudeProcessWrapperin every VS Code-family editor's settings and in the remote servers' machine settings, when it names EnvRouter's shim. A wrapper someone else set is left alone. - Deletes any MCP secrets EnvRouter kept in the system's store (the "EnvRouter MCP secrets" item).
- Deletes
~/.envrouter, with your profiles and MCP servers. If it is a link, only the link goes and the folder it points at is named and left. - Deletes the folders the window's webview keeps for itself (page data and caches). On macOS:
~/Library/WebKit/ca.pixel-perfect.envrouter,~/Library/Caches/ca.pixel-perfect.envrouterand~/Library/Application Support/ca.pixel-perfect.envrouter(where the window's size and position are kept) and~/Library/Preferences/ca.pixel-perfect.envrouter.plist(asking the system to forget those preferences first, withdefaults delete, so it can't write them back), plusHTTPStoragesandSaved Application Stateentries of that name, if the system made any. On Linux:~/.local/share/ca.pixel-perfect.envrouter(Tauri's local data folder, which holds the webview's storage and cache both) and~/.config/ca.pixel-perfect.envrouter(the window's size and position). It clears the same folders under the bundle identifier of releases up to 0.7.2 too, should any remain (the app deletes them itself at its first launch after updating). The command does this itself, since it only runs while the window is closed. The window's own uninstall can't while its webview is using them, so it deletes them as it quits, once everything else has finished. This step never fails the uninstall: a folder it can't delete is named ("Uninstalled, but this is left behind"), and so is one outside your home folder, which it won't touch (XDG_DATA_HOMEorXDG_CONFIG_HOMEpointing elsewhere on Linux).
If anything in steps 1 and 2 can't be done (a settings file you can't write, or one it can't read
that names the shim), it does the rest of those two steps and stops before step 3, so no editor is
ever left pointing at a shim that's gone. envrouter uninstall won't start while the EnvRouter window
is open (the window would put ~/.envrouter back the next time you switch to it): it says to quit
EnvRouter first and changes nothing. The window's own uninstall waits a few seconds for anything it
is still doing, such as checking an MCP server, and says so if that doesn't finish. While it runs the window says "Uninstalling EnvRouter…";
if it stops, "Uninstall stopped" shows the reason with Try Again; the command prints it and exits 1. Fix it, then run it again: every step skips what is
already done. If the store can't be reached at all (no Secret Service, WSL without interop), it
goes on and says any secrets are still there; if it can be reached but refuses the delete, it
stops before step 4.
When it finishes, the window shows what to run next and quits (if it can't, it says EnvRouter is uninstalled and asks you to quit it yourself), and the command prints it. Opening the app again sets EnvRouter up again, so remove the app next:
| Installed with | Remove it with |
|---|---|
| The macOS cask | brew uninstall --zap --cask envrouter (the --zap also clears the window's data, caches and preferences, should any come back), or quit the app and delete /Applications/EnvRouter.app |
The Linux .deb |
sudo apt remove env-router |
| The AppImage | Delete the file |
| The CLI from Homebrew | brew uninstall envrouter-cli |
| The CLI from a release archive | Delete envrouter and the helpers beside it |
Your agents' config folders are left alone.
By hand, if neither is available:
- Turn every shell off, from the toolbar's shell status or with
envrouter shell off <shell>. This removes the marked block from each startup file. You can also delete the lines between# >>> envrouter >>>and# <<< envrouter <<<by hand. - If you turned on an editor, turn it off (Editors…, or
envrouter editor off <editor>). This removesclaudeCode.claudeProcessWrapperfrom that editor's settings. - If you stored MCP secrets, delete them from the store:
- macOS: the "EnvRouter MCP secrets" item in Keychain Access, or
security delete-generic-password -s "EnvRouter MCP secrets" - Linux:
secret-tool clear service "EnvRouter MCP secrets" - WSL: in Windows, the "EnvRouter MCP secrets:wsl:…" entries under Windows Credentials in
Credential Manager (
cmdkey /listshows them;cmdkey /delete:<name>removes one)
- macOS: the "EnvRouter MCP secrets" item in Keychain Access, or
- Delete
~/.envrouter, and the window's data folders from step 5 above. - Remove the app and the CLI as in the table above (on macOS,
brew uninstall --zap --cask envrouteralso does step 4).
Contributions are welcome. EnvRouter is built with Tauri 2, Rust and React; see the contributing guide for setup, the development commands, how to review the UI safely in a browser, and the project layout.
Copyright © 2026 Tyler Robertson and Pixel Perfect Software Inc.
EnvRouter is free software under the GNU General Public License v3.0 or later. You can use, study, change and share it. If you distribute it, changed or not, you must share its source under the same licence, so nobody can ship a closed-source copy. Releases up to v0.4.0 were published under the MIT licence.
