Skip to content

QUICKSTART.md

Latest commit

 

History

History
212 lines (147 loc) · 5.53 KB

QUICKSTART.md

File metadata and controls

212 lines (147 loc) · 5.53 KB

Claudia Router Quick Start

Use the default NVIDIA flow first.

One Path

Clone once:

git clone https://github.com/ChunkyMonkey11/Claudia-Router.git
cd Claudia-Router
npm install

Then run:

npm run quickstart
npm run dev
npm run claude:fast

If setup fails:

npm run doctor

npm run quickstart is the main setup path. Add -- --start if you want it to launch the router automatically after setup.

If you want a different profile during setup, you can pass -- --profile glm, but that is optional.

If your NVIDIA key changes later, run npm run key.

Prerequisites (All Providers)

  • Node.js 18 or newer
  • Claude Code CLI installed (claude in your PATH)
  • Terminal with interactive capability (TTY)

Advanced: NVIDIA NIM (Recommended for Quality)

NVIDIA hosted models like nvidia/nemotron-3-super-120b-a12b, z-ai/glm4.7, and nvidia/nemotron-3-nano-30b-a3b. From the cloned repo root:

# 1. Run the one-command setup flow
npm run init

# 2. When prompted, enter your NVIDIA API key
#    - The setup flow uses NVIDIA by default
#    - It will test connectivity automatically

# 3. Start the router
npm run dev

# 4. Open another terminal and launch Claude
npm run claude:fast

Need an NVIDIA API key? Get one at NVIDIA NIM.

Advanced: OpenRouter (Many Models)

Access to many models (Qwen, Claude, Llama, etc.) via OpenRouter. From the cloned repo root:

# 1. Run setup for OpenRouter
npm run init -- --provider openrouter

# 2. When prompted, enter your OpenRouter API key

# 3. Start the router
npm run dev

# 4. Launch Claude
claudia-claude --model claude-3-5-sonnet-latest

Need an OpenRouter key? Get one at OpenRouter.

Advanced: Local Models (LM Studio / Ollama)

Use models running on your own machine. From the cloned repo root:

# 1. Start your local model server
# For LM Studio: http://localhost:1234/v1
# For Ollama: ollama serve (then configure baseUrl to http://localhost:11434/v1)

# 2. Run setup for local models
npm run init -- --provider local

# 3. Local uses a dummy API key by default

# 4. Start the router
npm run dev

# 5. Test it
curl http://localhost:8082/health

# 6. Launch Claude
claudia-claude --model local-model

Common Commands

Command Description
npm run dev Start the router (development mode with logging)
npm start Start the router (production build)
npm run quickstart One-command setup + doctor (add -- --start to auto-start router, -- --profile glm to switch profile)
npm run init First-run setup (default NVIDIA)
npm run key Update the provider API key in .env
npm run profile Open the interactive preset chooser (or use fast, glm, qwen, smoke, toggle, list, show)
npm run status Show router health plus active profile, routing summary, and next action
npm run doctor Check prerequisites and configuration
npm run release:check Release gate: typecheck + tests + build + package smoke
npm run config Re-run the configuration wizard
claudia-claude Launch Claude Code connected to the router
npm run claude:fast Default long-context model (nvidia/nemotron-3-super-120b-a12b)
npm run claude:glm High-quality thinking model, slower on purpose (z-ai/glm4.7)
npm run claude:qwen Backup coding model, less consistent on complex code (nvidia/nemotron-3-nano-30b-a3b)
npm run claude:smoke Quick smoke test only (nemotron-mini-4b)

Verify Installation

After starting the router (npm run dev), check health:

curl http://localhost:8082/health

Expected response:

{
  "ok": true,
  "name": "claudia-router",
  "version": "0.1.0"
}

Test a Claude-style request:

curl http://localhost:8082/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: dummy" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "Say hello"}]
  }'

Troubleshooting

"Claude Code CLI not found"

Install Claude Code: https://docs.anthropic.com/en/docs/claude-code/getting-started

Port 8082 already in use

Change the port in config.json and restart the router.

Router won't start

Run npm run doctor to diagnose common issues:

npm run doctor

Claude says "Anthropic API key is invalid"

Make sure your router is running and ANTHROPIC_BASE_URL is set to http://localhost:8082. The claudia-claude wrapper sets this automatically.

Need to switch providers later?

Run npm run init -- --provider openrouter or npm run init -- --provider local, or use npm run config for the interactive wizard.

Need to switch local Claude profiles?

Run npm run profile and choose a preset, or use npm run profile -- fast, npm run profile -- glm, npm run profile -- qwen, or npm run profile -- toggle.

If you want to set a preset during onboarding, use npm run quickstart -- --profile glm.

Press Enter at the chooser to keep the fast preset.

Run npm run profile -- list to see all presets.

Run npm run profile -- show to see the current active profile.

What's Next?