Install
This is a from-source install. The repository is private, the package is unpublished, and the shipped bin points at a build artifact, so the only way to get a runnable router today is clone, install, build, then run what the build produced.
Warning
There is no registry-hosted package for this project. Its package.json is
marked "private": true, which blocks publishing, and nothing has been
published. Any instruction you find that fetches this project from a package registry
does not work. Ignore it and use the sequence below.
Before you start
Three things, all checked against the repository's own pins. Getting the Node floor wrong is the most common way for this to fail late rather than early.
| Requirement | Version | Why |
|---|---|---|
| Node | >= 20.17.0 |
The engines floor. See
Why Node 20.17.0 below.
|
| pnpm | 10.28.2 |
Pinned in packageManager. On Node 24 and earlier,
corepack enable will honor it for you. Node 25 and later no longer
bundle corepack, so install pnpm 10.28.2 another way there.
|
| Repository access | CopilotKit/switchback | The repository is private. Without access, the clone step fails and there is no other route in. |
Continuous integration builds and tests on Node 20, 22 and 24, so any of those three is a
known-good runtime. The source is ESM-only ("type": "module").
Why Node 20.17.0
The CLI imports globSync from node:fs to expand the file globs
that switchback report takes. fs.globSync landed in Node 22.0.0
and was backported to 20.17.0; it does not exist on any earlier 20.x. A unit test pins the
floor for exactly this reason. On an older Node the import is what breaks, not the
reporting command, so the failure looks unrelated to its cause.
Clone, install, build, run
This is the whole install. Every line below was executed against the repository in this order.
# 1. clone the private repo (you need access to CopilotKit/switchback)
git clone git@github.com:CopilotKit/switchback.git
cd switchback
# 2. install deps with the pinned package manager
corepack enable # optional, Node <= 24 only; honors packageManager: pnpm@10.28.2
pnpm install
# 3. build the CLI + the route-core barrel
pnpm build
# 4. run the built bin
node dist/switchback-cli.js --help
pnpm build runs tsdown over two entry points (src/switchback-cli.ts
and src/route/index.ts), emitting both ESM and CJS with declarations and
sourcemaps, targeting ES2022, cleaning dist/ first. If step 4 prints the help
banner, you are done and can move on to the Quickstart.
Note
The router prints an experimental notice on every start:
[switchback] EXPERIMENTAL: the self-hosted router is under active development; config
shape and behavior may change without notice (§13.9).
That is expected, not a misconfiguration. Treat the config shape as unstable while this
notice is there.
What the build produces
Four things in dist/ matter to you. The rest is declarations, sourcemaps and
unbundled internals.
| Path | What it is | Run it? |
|---|---|---|
| dist/switchback-cli.js |
The CLI. ESM, mode 0755, with a
#!/usr/bin/env node shebang. This is what the package's
bin.switchback entry points at.
|
Yes |
| dist/switchback-cli.cjs | The CJS twin of the same entry, also 0755. |
No (see below) |
| dist/route/index.js | The route-core barrel: the policy, engine, report and budget types the router is built from. | Library only |
| dist/switchback/catalog/snapshot/ |
The signed price catalog: catalog.json plus
catalog.json.sig. Copied rather than inlined, because the loader
reads it from disk and verifies its Ed25519 signature at runtime.
|
Data |
That last row is the one that bites people who relocate a build. Because the catalog is
read from the filesystem and signature-checked, copying only the JavaScript out of
dist/ leaves the router without a catalog. Move the whole tree.
Danger
Do not run dist/switchback-cli.cjs. The module's self-run
guard matches only the basenames switchback,
switchback-cli.js and switchback-cli.ts.
switchback-cli.cjs is not on that list, so the file loads, starts nothing,
and exits 0 with no output at all. Verified:
node dist/switchback-cli.cjs --help prints nothing and succeeds. In a
supervisor or a health-gated deploy that reads as a clean start of a router that is not
running. Always use dist/switchback-cli.js.
Running from source, without a build
The same self-run guard accepts the .ts basename, so you can skip the build
entirely while you are working in the tree:
pnpm install
pnpm tsx src/switchback-cli.ts --help
This prints the same help banner as the built bin. It is the right thing for editing and re-running; the built entry is the right thing for anything long-running.
Other scripts in the repository
Everything you need for a normal contributor loop is a package script.
| Command | What it does |
|---|---|
| pnpm build | Runs tsdown and produces dist/. |
| pnpm test | Runs the unit suite under Vitest. |
| pnpm typecheck | TypeScript, no emit. |
| pnpm lint | ESLint over the tree. |
| pnpm format:check | Prettier in check mode. |
| pnpm build:verify-catalog | Verifies the bundled signed catalog. |
| pnpm switchback:catalog:sign | Signs the catalog artifact. |
| pnpm switchback:catalog:verify | Verifies the catalog artifact on its own. |
Dependency installs are deliberately conservative: the repository's
.npmrc sets minimum-release-age=1440 and
block-exotic-subdeps=true, so a brand-new release of a transitive dependency
will not be picked up the minute it lands.
What is not an install path
Stated plainly, so you do not spend an afternoon on any of these.
The package is private and unpublished, and the bin it declares is a build artifact
that only exists after pnpm build. Even a local install of the folder
would need the build first.
There is no published image or chart. The repository does carry a
Dockerfile and a docker-compose.yml, so you build the
image yourself from the clone. See Deploy for the process
posture that image needs to satisfy.
Being private blocks publishing, not local linking, so a global link may well work. We have not run it, so this page does not document it as a supported path. Invoke the built entry by path instead.
The package declares no exports field, so there is no subpath to import
the route core from. Comments in the source that mention one are out of date.
dist/route/index.js is a real file; a public subpath for it is not.
Where to go next
With node dist/switchback-cli.js --help printing, write your first config in
the Quickstart and send a request through the router. For every
flag, subcommand and exit code the built entry accepts, see the
CLI reference.