Weave Router quickstart

What do you need before setup?

The Router installer requires Node.js 18 or newer, with npm and npx. Have the coding client you want to configure available separately. On macOS and Linux, the installer uses Bash. On Windows, PowerShell supports basic setup; additional shell-based features require Git Bash or WSL.

The installer can reuse jq or download a checksum-verified copy on supported platforms. Network access to npm, GitHub, and your chosen Router endpoint is needed. See the current installer requirements for architecture and platform details.

How do you start hosted setup?

Run this in a terminal:

npx @weave-os/router

With no explicit client target, the command opens the hosted setup page. To configure a native client from the terminal, select it explicitly:

# Choose the client you use.
npx @weave-os/router --claude
npx @weave-os/router --codex

Follow the authentication and setup prompts. These commands configure a connection to hosted Weave Router. They do not start a local Router server. Plan features and access are described on the Router pricing page.

Use the client-specific guides for Claude Code and Codex CLI before changing an existing configuration.

How do you verify that setup worked?

Check the configured client explicitly:

npx @weave-os/router status --claude
npx @weave-os/router status --codex

The status command checks connectivity, native configuration, and account health. Resolve an error there before treating the installation as ready. A command completing is not proof that a new session used the Router.

Quit and reopen Claude Code after changing its routing setting. Codex picks up the change on its next run. Check status again if a session continues using an older configuration.

Router chooses a model for each upstream API request, called an action in its documentation. A single user interaction can contain several actions. A model shown for one request does not describe the entire conversation.

Should you use user scope or project scope?

The native installer supports user-level and project-level configuration. To select a project installation, run it from the intended repository:

npx @weave-os/router --claude --scope project
# Or, for Codex:
npx @weave-os/router --codex --scope project

Project scope changes where configuration is managed. Follow the installer’s credential handling and inspect any files before committing them. Never commit Router keys or provider credentials.

How does self-hosted setup differ?

Use the local option for the Docker Compose setup, or supply an existing deployment URL:

npx @weave-os/router --local
npx @weave-os/router --base-url https://router.example.com

The URL above is a placeholder. Replace it with your deployment. Self-hosting has its own provider credentials, service dependencies, and operations requirements. Follow the deployment instructions rather than assuming hosted account or plan behavior applies to your server.

How do you switch back or remove the configuration?

For a user-scope install, disable the chosen client without deleting its Router configuration:

npx @weave-os/router off --claude
npx @weave-os/router off --codex

Use on in place of off to enable routing again. Reopen Claude Code or start the next Codex run after switching. For a project install, include --scope project from the same repository.

To remove the installed client configuration, use --uninstall --claude or --uninstall --codex. Match the original scope. The client-specific guides explain what the installer owns and preserves.