Como rodar seu próprio roteador de modelos de IA com o 9router

O 9router é um proxy de roteamento open source, sob licença MIT, que roda na sua própria máquina ou servidor e coloca todos os provedores de IA que você conectar atrás de um único endpoint compatível com a OpenAI em http://localhost:20128/v1.

Se você usa o Claude Code em um terminal, o Cline no editor e o SDK da OpenAI em um projeto paralelo, provavelmente tem três conjuntos de chaves e três base URLs, e cada ferramenta exige uma alteração de configuração própria sempre que você troca de modelo. O 9router substitui tudo isso por um único endpoint local. Este guia mostra como instalá-lo com npm ou Docker, testá-lo com curl, apontar suas ferramentas para ele e protegê-lo antes que qualquer coisa fora do localhost consiga acessá-lo.

O que é o 9router?

O 9router é um proxy self-hosted que aceita requisições no formato da OpenAI, as encaminha para o provedor upstream que você tiver configurado e faz a conversão entre os formatos de requisição da OpenAI, do Claude e do Gemini conforme necessário. O README do projeto lista mais de 40 provedores suportados, e a CLI é distribuída como o pacote npm 9router.

A principal diferença entre o 9router e o OpenRouter é onde o roteador roda. O OpenRouter é um serviço hospedado para o qual você envia requisições. O 9router é um software que você mesmo executa, e o OpenRouter aparece na sua lista de provedores, então você pode colocar uma conta do OpenRouter atrás do seu próprio roteador.

Por que rodar um roteador de modelos self-hosted

Um roteador local oferece o mesmo endpoint para todas as ferramentas e mantém as credenciais dos provedores em um só lugar, permitindo trocar de modelo sem mexer nas configurações das ferramentas nem no código da aplicação.

• Um único endpoint. Todo cliente compatível com a OpenAI usa a mesma base URL.
• Chaves em um só lugar. Você adiciona as contas dos provedores uma única vez, no dashboard. Cada ferramenta precisa apenas de uma chave de API do 9router.
• Troca de modelo por string. Mudar de modelo significa alterar o valor de model e nada mais.
• Combos. Um combo é uma lista nomeada e ordenada de modelos que você usa como nome do modelo. Quando o primeiro modelo esgota a cota, sofre rate limiting (429) ou retorna um erro, o roteador tenta o próximo.

O padrão mais comum é colocar o seu modelo preferido em primeiro lugar e modelos mais baratos depois dele. Para comparar os preços por token antes de escolher os fallbacks, use a calculadora de custos de API de LLM.

Como instalar e rodar o 9router

O 9router é instalado como uma CLI global do npm com npm install -g 9router e iniciado com o comando 9router. O servidor escuta na porta 20128.

npm install -g 9router
9router
# Dashboard: http://localhost:20128
# API:       http://localhost:20128/v1

Se você não quiser uma instalação global, npx 9router o executa uma única vez.

Para rodá-lo no Docker, use a imagem oficial decolua/9router, que também é publicada em ghcr.io/decolua/9router:

docker run -d --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  -e INITIAL_PASSWORD='change-me' \
  decolua/9router:latest

O volume montado preserva o banco de dados SQLite (/app/data/db/data.sqlite dentro do container) quando o container é reiniciado. Novas versões são lançadas com frequência e a tag latest acompanha cada uma delas, então fixe uma tag de versão específica se você precisar de deploys reproduzíveis.

Depois que o 9router iniciar, conclua a configuração no dashboard:

1. Abra http://localhost:20128 e faça login no dashboard.
2. Adicione pelo menos uma conta de provedor.
3. Crie uma chave de API para as suas ferramentas.

Verifique o roteador com curl

A forma mais rápida de verificar se o 9router está funcionando é enviar uma requisição GET para /v1/models antes de configurar qualquer ferramenta. A resposta é uma lista JSON com todos os modelos e combos que o roteador consegue servir, no formato de lista padrão da OpenAI.

curl http://localhost:20128/v1/models

A lista de modelos responde sem chave. Já as requisições de chat são diferentes: a configuração “Require API key” do dashboard vem ativada por padrão, então elas exigem uma chave gerada no dashboard. Enviar a chave também na requisição da lista de modelos é uma boa prática, porque uma chave restrita a determinados modelos só enxerga esses modelos:

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINE_ROUTER_API_KEY"

Se um ID de modelo do seu provedor aparecer na lista, o roteamento está funcionando. Se a lista estiver vazia, o provedor ainda não está conectado.

Aponte suas ferramentas para o 9router

Qualquer cliente que aceite uma base URL personalizada da OpenAI pode usar o 9router. Defina a base URL como http://localhost:20128/v1 e informe uma chave de API criada no dashboard.

SDK da OpenAI

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:20128/v1",
  apiKey: process.env.NINE_ROUTER_API_KEY, // created in the 9router dashboard
});

const res = await client.chat.completions.create({
  model: "<an id or combo name from /v1/models>",
  messages: [{ role: "user", content: "Say hello" }],
});
console.log(res.choices[0].message.content);

Para trocar para outro modelo ou para um combo, altere a string de model. Nada mais no código muda.

Agentes de código

No Cline, escolha OpenAI Compatible como API provider e preencha três valores: a base URL http://localhost:20128/v1, a sua chave de API do dashboard e um ID de modelo copiado de /v1/models. Agentes de terminal que permitem usar seu próprio provedor, como o OpenCode, recebem esses mesmos três valores.

Pi com pi-9router-ext

A extensão pi-9router-ext conecta o agente de código Pi ao 9router por meio de duas variáveis de ambiente:

pi install npm:pi-9router-ext
NINE_ROUTER_BASE_URL=http://localhost:20128 NINE_ROUTER_API_KEY=<key> pi
# inside Pi:
/9router-models

Ao iniciar, a extensão lê os modelos de chat a partir de /v1/models. Na versão 0.2.4, ela também consulta /v1/models/web para descobrir as rotas de busca e fetch na web do 9router. Execute /9router-models dentro do Pi para ver o que ela encontrou.

Como proteger o 9router antes de expô-lo?

Para proteger o 9router antes que outra máquina consiga acessá-lo, defina uma senha para o dashboard e os secrets de JWT e de chave de API, e mantenha a opção “Require API key” ativada. Os valores padrão são adequados no localhost, mas não fora dele. Se INITIAL_PASSWORD não estiver definida, o primeiro login no dashboard usa 123456 até que uma senha seja salva. Defina estes valores a partir do .env.example oficial antes de abrir uma porta ou fazer deploy em um host público:

INITIAL_PASSWORD=<long-random-string>   # first login otherwise uses 123456
JWT_SECRET=<long-random-string>         # listed under "Required" in .env.example
API_KEY_SECRET=<long-random-string>     # the example default is publicly known
AUTH_COOKIE_SECURE=true                 # set when serving behind an HTTPS reverse proxy

A verificação da chave de API em si é uma configuração do dashboard. Abra a página Endpoint e confirme que Require API key está ativada, para que requisições sem uma chave válida sejam rejeitadas. Ela vem ativada por padrão, e o dashboard exibe um aviso se o endpoint estiver acessível a partir de um host remoto sem ela.

Só defina AUTH_COOKIE_SECURE=true quando o TLS for terminado à frente do 9router. Em HTTP simples, o navegador não enviará o cookie de autenticação de volta.

Conclusão

Um roteador self-hosted como o 9router oferece a todas as suas ferramentas um único endpoint e um único conjunto de credenciais, e trocar de modelo passa a significar apenas alterar a string de model. Instale-o, verifique se /v1/models lista os modelos do seu provedor e, em seguida, aponte uma ferramenta para http://localhost:20128/v1. Defina a senha e os secrets, e mantenha “Require API key” ativada, antes que o roteador saia do localhost.

Perguntas frequentes

Como rodar o 9router em uma porta diferente da 20128?

Inicie a CLI do npm com 9router --port 8080 para usar uma porta personalizada. Ao rodar a partir do código-fonte, defina a variável de ambiente PORT, junto com NEXT_PUBLIC_BASE_URL apontando para a mesma porta. No Docker, altere o lado do host no mapeamento de portas, por exemplo -p 8080:20128. Todas as ferramentas passam então a precisar da nova base URL, como http://localhost:8080/v1.

Onde o 9router armazena sua configuração e seus dados?

O 9router armazena seus dados no diretório definido por DATA_DIR, que por padrão é ~/.9router, e mantém seu banco de dados SQLite em db/data.sqlite dentro desse diretório. Se JWT_SECRET não estiver definido, um secret de assinatura gerado automaticamente também é armazenado ali, em ~/.9router/jwt-secret. A imagem Docker oficial define DATA_DIR como /app/data, então montar um volume em /app/data persiste tudo.

Como apontar ferramentas de outra máquina para um servidor 9router remoto?

Execute npx 9router connect http://server-host:20128 na máquina cliente. O comando não inicia nenhum servidor local. Ele faz login com a senha do dashboard, reutiliza ou cria uma chave de API chamada cli- seguida do hostname e grava a configuração de cada ferramenta selecionada. Ele faz backup de cada configuração original uma única vez, com o sufixo .bak-9router. Use --tools claude,codex para escolher as ferramentas de antemão e --reset para desfazer as alterações.

O 9router pode usar mais de uma conta para o mesmo provedor?

Sim. O 9router suporta várias contas por provedor e distribui as requisições entre elas usando roteamento round-robin ou baseado em prioridade. Quando uma conta atinge a cota, o roteador passa para a próxima conta. Isso é diferente dos combos: a rotação de contas mantém o mesmo modelo e troca as credenciais por trás dele, enquanto um combo passa para um modelo diferente.