Router: Optimize AI Model Selection and Costs for Agentic Systems

Introduction

The weave-os/router is an innovative open-source project designed to revolutionize how agentic systems interact with large language models (LLMs). Acting as a smart proxy, it intelligently routes every prompt to the most appropriate AI model, ensuring optimal performance and significant cost reductions. With a single endpoint change, users can achieve 40-70% cost savings while leveraging the best models from providers like Anthropic, OpenAI, and Gemini. This project, written in Go, has garnered significant attention, boasting over 5,300 stars on GitHub.

Why Use It and Key Benefits

The Weave-OS Router offers a compelling set of features that make it an essential tool for developers building agentic AI applications:

• ? Routes per action: An advanced cluster scorer, derived from research like Avengers-Pro, picks the right model from your enabled providers for every upstream API request. This ensures that each action within your agentic system is handled by the most suitable LLM.
• ? Speaks everyone's API: It supports a wide range of API formats, including Anthropic Messages, OpenAI Chat Completions, and Gemini native, along with features like streaming, tools, and vision capabilities.
• ? Knows OSS too: Beyond commercial providers, the router integrates with open-source models such as DeepSeek, Kimi, GLM, Qwen, Llama, and Mistral via OpenRouter or any OpenAI-compatible endpoint.
• ? BYOK by default: Provider keys remain on your local machine, encrypted at rest, ensuring enhanced security and control over your credentials.
• ? Observable: Out-of-the-box OTLP traces provide deep observability, allowing you to monitor routing decisions and integrate with dashboards like Weave, Honeycomb, Datadog, or Grafana.

Installation

Getting started with the Weave-OS Router is quick and straightforward.

30-second Quickstart (Hosted)

The fastest way to use the hosted Weave Router is with npx:

npx @weave-os/router

This command opens the hosted setup page in your browser. You can also choose a target explicitly:

npx @weave-os/router --claude              # skip the picker, Claude Code
npx @weave-os/router --local               # self-hosted localhost:8080

Requires Node ? 18. For a full flag reference, see the install/npm/README.md file.

Self-host the Whole Stack

For a self-hosted solution running the router and dashboard on your own machine:

1. Drop a provider key in. OpenRouter is recommended as a baseline.

   echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local
   

2. Set a dashboard password.

   echo "ROUTER_ADMIN_PASSWORD=replace-with-a-strong-password" >> .env.local
   

3. Boot Postgres + router on :8080 and seed an rk_ key.

   make full-setup
   

The router will be accessible at http://localhost:8080 and the dashboard at http://localhost:8080/ui/.

Examples

Once the router is running, you can interact with it using standard API calls:

Call it like Anthropic

curl -sS http://localhost:8080/v1/messages \
  -H "Authorization: Bearer rk_..." \
  -d '{"model":"claude-sonnet-4-5","max_tokens":256,
       "messages":[{"role":"user","content":"hi"}]}'

Or like OpenAI

curl -sS http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer rk_..." \
  -d '{"model":"gpt-4o-mini",
       "messages":[{"role":"user","content":"hi"}]}'

Peek at the routing decision without proxying

curl -sS http://localhost:8080/v1/route -H "Authorization: Bearer rk_..." -d '...'

Links

For more detailed information, documentation, and to contribute to the project, please visit the official resources:

• GitHub Repository: https://github.com/weave-os/router
• Official Website: https://www.workweave.ai
• License: Apache License 2.0
• Configuration Reference: docs/CONFIGURATION.md
• Semantics and Terminology: docs/SEMANTICS.md
• Analytics Export: docs/ANALYTICS_EXPORT.md
• Contributing Guide: CONTRIBUTING.md