Getting Started

Getting Started

This guide brings the full Nexus Gateway stack up on your machine and sends your first request through it. It takes a few minutes.

Prerequisites

Tool	Version
Node.js	20 or newer
Go	1.25 or newer
Docker	any recent release

Docker hosts the backing services — PostgreSQL, Valkey, and NATS. The Go services and the Control Plane UI run directly on your machine.

One-shot bootstrap

./scripts/dev-start.sh

The script verifies the prerequisites, starts PostgreSQL, Valkey, and NATS, creates a repo-root .env with safe development defaults, installs the npm dependencies, applies the database schema and seed data, generates a development certificate authority for the Compliance Proxy, prints the per-service start commands, and launches the Control Plane UI.

Two flags are available:

• --force-reset — destructive: wipes the local PostgreSQL, Valkey, and NATS volumes and the nexus_gateway database before re-applying the schema.
• --no-dev — bootstrap only; print the per-service commands and exit without starting the UI.

Start the services

After the bootstrap finishes, open one terminal per Go service:

cd packages/nexus-hub        && go run ./cmd/nexus-hub/        -config nexus-hub.dev.yaml         # port 3060
cd packages/control-plane    && go run ./cmd/control-plane/    -config control-plane.dev.yaml     # port 3001
cd packages/ai-gateway       && go run ./cmd/ai-gateway/       -config ai-gateway.dev.yaml        # port 3050
cd packages/compliance-proxy && go run ./cmd/compliance-proxy/ -config compliance-proxy.dev.yaml  # port 3128
npm run dev:control-plane-ui                                                                       # port 3000

The -config <svc>.dev.yaml flag is required. Each binary otherwise defaults to its production-shape template, which intentionally omits development-only fields, and fails fast at boot.

Open the console

Browse to http://localhost:3000 and sign in as the seeded super-admin:

admin@nexus.ai / admin123

Make your first request

The AI Gateway accepts OpenAI-format requests on /v1/chat/completions, authenticated by a virtual key. Create a virtual key in the console — under Virtual Keys, or your Personal Virtual Keys — and copy it; gateway virtual keys are prefixed nvk_. Then send a request:

export VK="nvk_<your-virtual-key>"

curl -sS http://localhost:3050/v1/chat/completions \
  -H "Authorization: Bearer $VK" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "What is the capital of Japan?"}]
  }'

The gateway authenticates the key, matches the routing rule for the requested model, picks a provider and credential, and forwards the request upstream. You get an OpenAI-shaped response, and the x-nexus-request-id response header is your handle for the audit lookup. The seeded openai provider needs a real API key in its credential — add one through the Control Plane UI under Settings → Providers if the placeholder is still in place.

Every request that any intercept layer handles is recorded as one traffic-event row carrying the request id, the resolved provider and model, token counts, and latency. The full hello-world walkthrough — including how to read that row back from the database — lives in the examples/01-hello-world/ demo.

See also

• Installation and Deployment — SaaS, self-hosted, and air-gapped options.
• Core Concepts — virtual keys, providers, routing, caching, and compliance.
• Connecting a Provider — add a provider and a credential.
• API and Client Integration — the /v1 endpoints and client setup.