switchback — part of the aimock family private · pre-launch

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.

from nothing to a runnable router shell
# 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:

contributor loop shell
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.

A package registry unavailable not supported

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.

A container image unavailable not supported

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.

A globally linked bin unverified untested

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.

An importable subpath unavailable not supported

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.