Quickstart

From zero to a fully functional Open Next Router gateway in under 2 minutes.

Welcome to Open Next Router! This guide will help you install, configure, and route your first LLM request through the gateway locally.

Prerequisites: Ensure you have Go 1.25+ and Make installed on your system. If you prefer Docker, check out the Docker Guide.

Getting Up and Running

1. Clone the Repository

   First, grab the source code from GitHub:

   git clone https://github.com/r9s-ai/open-next-router.git
   cd open-next-router
   
2. Build the Binary

   Compile the onr binary using the provided Makefile:

   make build
   

   This will place the executable in the bin/ directory or your $GOPATH/bin. If it’s globally available, you can simply run onr.

3. Initialize Configuration Files

   Open Next Router relies on three main YAML configuration files. You can start with the defaults provided in the repository.

   onr.yaml (Server Config)

   Main server configurations including ports, logger, and paths to other config files.

   keys.yaml (Authentication & Routing)

   Defines your downstream API keys, rate limits, and which DSL routing profile to apply.

   models.yaml (Provider Secrets)

   Safely store the actual upstream API keys (e.g., OpenAI, Anthropic tokens) required to dispatch requests.

4. Run Configuration Tests

   It’s always a good idea to validate your configuration syntax before starting the server:

   onr test -c onr.yaml
   

   If everything is correct, you’ll see a Configuration is valid message.

5. Start the Gateway

   Launch the router:

   onr run -c onr.yaml
   

   You should see the server boot up and begin listening on http://localhost:3300.

6. Send Your First Request

   Open Next Router natively exposes an OpenAI-compatible /v1/chat/completions endpoint. Try calling it:

   curl -X POST http://localhost:3300/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-onr-client-token" \
     -d '{
       "model": "gpt-4o-mini",
       "messages": [{"role": "user", "content": "Hello, Open Next Router!"}]
     }'
   

   Replace your-onr-client-token with a token defined in your keys.yaml.

Next Steps

Now that you have traffic flowing, explore these essential topics to unlock the power of ONR:

DSL Overview

Learn how to write dynamic routing rules, rewrites, and token tracking.

Load Balancing & Fallbacks

Configure multi-provider failover for maximum resilience.

Observability

Set up Promtail, Loki, and Grafana for comprehensive gateway monitoring.

Admin Panel

Manage keys and live DSL configurations visually.