# OmniRoute Embedded Services: The Complete Guide to 9Router, CLIProxyAPI, Mux, and Bifrost

> Explore OmniRoute's embedded services 9Router CLIProxyAPI Mux and Bifrost Learn how these lightweight sidecar processes enable AI routing authentication proxying orchestration and gateway relay

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-19

---

**OmniRoute provides four embedded services—9Router, CLIProxyAPI, Mux, and Bifrost—each offering lightweight sidecar processes for local AI routing, authentication proxying, background orchestration, and gateway relay functionality.**

OmniRoute's **embedded services** architecture lets developers run managed, loopback-only services alongside the main process without external dependencies. Unlike third-party LLM providers, these services install, start, stop, and monitor entirely on the local host, with HTTP endpoints restricted to `localhost` only. This article examines each service's functionality, supervisory lifecycle, and practical usage based on the OmniRoute source code.

## OmniRoute Embedded Services Overview

| Service | Package | Default Port | Primary Function |
|---------|---------|--------------|------------------|
| **9Router** | `9router` | 20130 | Embedded AI router for internal LLM call routing |
| **CLIProxyAPI** | `@anthropic/cli-proxy` | Auto-assigned | Local proxy for Anthropic CLI authentication flows |
| **Mux** | `mux` | 8322 | Background agent-orchestration daemon |
| **Bifrost** | `@maximhq/bifrost` | 8080 | Go-based AI-gateway relay backend |

All four services share a unified **supervisory model** implemented in [`src/lib/services/ServiceSupervisor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/ServiceSupervisor.ts), ensuring consistent lifecycle management and security boundaries.

## 9Router: Embedded AI Router

**9Router** acts as an internal routing provider accessible via the `9router/{sub}/{model}` namespace. It exposes an OpenAI-compatible HTTP endpoint that OmniRoute treats as a first-class provider.

### How 9Router Integration Works

When you target a model with the `9router/` prefix, the executor in [`open-sse/executors/ninerouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/ninerouter.ts) dynamically reads the current port and injected API key, strips the prefix, and proxies your request to the running 9Router process:

```bash
curl -X POST http://localhost:20128/v1/chat/completions \
     -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"9router/openai/gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

```

The installer at [`src/lib/services/installers/ninerouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/installers/ninerouter.ts) handles `npm install` under `DATA_DIR/services/9router` using `execFile('npm', …)` without shell interpolation, mitigating injection risks.

## CLIProxyAPI: Anthropic Authentication Proxy

**CLIProxyAPI** provides seamless fallback for Anthropic CLI workflows. Rather than requiring an injected API key like other services, it authenticates using the host's existing Anthropic CLI configuration.

### Authentication Flow Handling

When OAuth tokens expire, CLIProxyAPI automatically negotiates fresh credentials through the local proxy. This eliminates manual token refresh interruptions in automated pipelines. The installer resides at [`src/lib/services/installers/cliproxy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/installers/cliproxy.ts), spawning the `cliproxy` binary from the `@anthropic/cli-proxy` package.

## Mux: Background Agent Orchestration

**Mux** runs as a **lifecycle-managed background daemon only**—it has no routing executor and never appears in the provider registry. This design suits custom tooling requiring persistent local agents without exposing HTTP endpoints through OmniRoute's routing layer.

Key characteristics:
- Runs headless on port 8322
- No `open-sse/executors/` counterpart exists
- Useful for scheduled tasks, file watchers, or custom automation

The installer at [`src/lib/services/installers/mux.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/installers/mux.ts) configures the headless mux server with identical supervision guarantees as routable services.

## Bifrost: AI Gateway Relay

**Bifrost** operates as a **local relay backend** for AI-gateway traffic. When the supervised Bifrost instance reports healthy, OmniRoute automatically constructs the relay base URL at `http://127.0.0.1:{port}` unless you explicitly override with `BIFROST_BASE_URL`.

The routing backend logic in [`src/lib/services/routingBackend.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/routingBackend.ts) detects Bifrost's availability and remaps `/v1/relay/` traffic accordingly, transparently integrating the Go-based gateway into request flows.

## Unified Service Supervision Model

All embedded services follow a four-stage lifecycle enforced by [`ServiceSupervisor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/ServiceSupervisor.ts):

### Installation

`npm install {package}` executes under `DATA_DIR/services/{name}` using direct process spawning without shell interpolation. Referenced in [`src/lib/services/installers/ninerouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/installers/ninerouter.ts) and sibling installer files.

### Process Spawning and Security

`ServiceSupervisor` spawns services with:
- **Ephemeral API keys** generated and AES-256-GCM encrypted at rest ([`src/lib/services/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/apiKey.ts))
- **5 MiB circular log buffer** for telemetry without disk exhaustion
- **Environment isolation** preventing credential leakage

### Health Probing

Periodic HTTP health checks from [`src/lib/services/healthCheck.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/healthCheck.ts) promote service state to **running** or trigger restart/**error** classification. Failed health probes surface through the status API immediately.

### Local-Only Access Enforcement

[`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts) classifies all `/api/services/*` routes as `LOCAL_ONLY`, rejecting non-loopback requests regardless of authentication. This hard-rule (#17) prevents network exposure of service management endpoints.

## Managing Embedded Services via API

OmniRoute exposes REST endpoints for complete lifecycle control. All examples assume OmniRoute runs on its default port 20128.

### Installation

```bash
curl -X POST http://localhost:20128/api/services/9router/install \
     -H "Content-Type: application/json" \
     -d '{"version":"latest"}'

```

### Startup

```bash
curl -X POST http://localhost:20128/api/services/9router/start

```

### Status Monitoring

```bash
curl http://localhost:20128/api/services/9router/status

```

Returns combined database metadata and live health state.

### Log Streaming (Server-Sent Events)

```bash
curl -N http://localhost:20128/api/services/9router/logs?tail=200

```

Streams from the 5 MiB ring buffer maintained by `ServiceSupervisor`.

### Auto-Start Configuration

```bash
curl -X POST http://localhost:20128/api/services/9router/auto-start \
     -H "Content-Type: application/json" \
     -d '{"enabled":true}'

```

Persists across OmniRoute restarts via [`src/lib/services/bootstrap.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/bootstrap.ts) registration.

## Key Implementation Files

| File | Responsibility |
|------|--------------|
| [`src/lib/services/ServiceSupervisor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/ServiceSupervisor.ts) | Core lifecycle, health checks, ring-buffer logging |
| [`src/lib/services/bootstrap.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/bootstrap.ts) | Service registration at process start (port, health path, auto-start) |
| [`src/lib/services/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/registry.ts) | Global `tool → ServiceSupervisor` map |
| [`src/lib/services/apiKey.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/apiKey.ts) | Per-service key generation and AES-256-GCM encryption |
| [`src/lib/services/modelSync.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/modelSync.ts) | Periodic model fetching to `service_models` table |
| `src/lib/services/installers/*.ts` | Package-specific npm installation logic |
| [`open-sse/executors/ninerouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/ninerouter.ts) | 9Router request proxying and prefix stripping |
| [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts) | `LOCAL_ONLY` enforcement for management routes |
| `src/app/api/services/{name}/*/route.ts` | HTTP route handlers per service |

## Summary

- **9Router** (`9router` package, port 20130) enables internal AI routing with OpenAI-compatible endpoints, accessible via `9router/{sub}/{model}` provider syntax
- **CLIProxyAPI** (`@anthropic/cli-proxy`, auto port) provides transparent Anthropic CLI authentication fallback without injected credentials
- **Mux** (`mux` package, port 8322) runs background agent workloads without routing exposure
- **Bifrost** (`@maximhq/bifrost`, port 8080) relays AI-gateway traffic automatically when healthy
- All services share **supervised lifecycle management**: npm installation, encrypted API key injection, health probing, and `LOCAL_ONLY` access restrictions
- Management APIs at `/api/services/*` offer complete install, start, stop, status, logging, and auto-start control

## Frequently Asked Questions

### How do OmniRoute embedded services differ from external LLM providers?

Embedded services install and run locally on the same host as OmniRoute, managed by [`ServiceSupervisor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/ServiceSupervisor.ts), whereas external providers require network egress to third-party APIs. Embedded service endpoints are hard-restricted to `localhost` through [`routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/routeGuard.ts), and their processes receive AES-256-GCM encrypted ephemeral API keys rather than persistent credentials stored in environment variables.

### Can I use 9Router to route to arbitrary OpenAI-compatible endpoints?

Yes. The `9router/{sub}/{model}` pattern strips the prefix and forwards to whatever upstream the 9Router process configures. The executor at [`open-sse/executors/ninerouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/ninerouter.ts) resolves the current port and credential dynamically per-request, allowing 9Router's internal routing table to evolve without OmniRoute restarts.

### Why does Mux not appear as a routing target?

Mux lacks an executor implementation in `open-sse/executors/` because it serves purely as a background daemon for custom tooling. It registers in [`src/lib/services/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/registry.ts) for lifecycle supervision but never enters the provider registry, keeping its port 8322 interface private to local consumers you configure separately.

### What happens to embedded services when OmniRoute shuts down?

`ServiceSupervisor` terminates child processes gracefully on exit. Services with `auto-start` enabled relaunch automatically when OmniRoute boots, as processed by [`src/lib/services/bootstrap.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/bootstrap.ts). The 5 MiB log ring buffer persists only in memory—logs must be streamed via SSE or exported before restart if retention is required.