Make AI safe to use across the enterprise.
Nexus Gateway intercepts enterprise LLM traffic at three layers and runs all of it through one compliance engine, one audit pipeline, and one control plane.
| Mode | Where it intercepts | Code |
|---|---|---|
| 🔑 AI Gateway | ||
SDK layer — virtual keys on /v1/chat/* , /v1/responses , /v1/embeddings , /v1/messages |
||
packages/ai-gateway/ |
||
| 🌐 Compliance Proxy | ||
Network layer — transparent TLS bump (CONNECT + MITM) |
||
packages/compliance-proxy/ |
||
| 💻 Desktop Agent | ||
| OS layer — macOS / Linux / Windows builds all in development, awaiting QA | packages/agent/platform/{darwin,linux,windows}/ |
The three pipes are independent: AI Gateway, Compliance Proxy, and Agent each run the full hooks pipeline on their own traffic (packages/shared/policy/hooks/
, plus the per-service compliance pipeline — e.g. packages/agent/internal/compliance/pipeline.go
). The Agent always egresses directly to the upstream provider — it does not care whether enterprise network policy then routes that traffic through the Compliance Proxy.
When it does — Agent stamps an Ed25519-signed X-Nexus-Attestation
header on the outbound request (E60, packages/agent/internal/identity/attestation/
). The Compliance Proxy peeks this header before the TLS bump (packages/shared/transport/tlsbump/forward_handler.go:119
); if the signature verifies, the CONNECT becomes pure passthrough — no MITM, no hooks, no audit on that flow, since the Agent already ran them.
Applications speak the OpenAI SDK. Nexus normalises every request to a canonical OpenAI shape, then translates wire format on the way to the actual provider. Shipped adapter codecs today (packages/ai-gateway/internal/providers/specs/
):
First-class codecs (11):openai
,anthropic
,gemini
,vertex
,azure
,bedrock
,cohere
,minimax
,glm
,replicate
,voyage
.OpenAI-compatible passthrough (9):deepseek
,moonshot
,mistral
,groq
,fireworks
,together
,perplexity
,xai
,huggingface
— all underpackages/ai-gateway/internal/providers/specs/compat/
.
Reasoning tokens, function calls, vision inputs, structured outputs are carried through the translation. Adding a new provider is a documented procedure under .claude/skills/add-provider-adapter/
.
Exact-match response cache— Valkey-backed, Redis-wire-compatible.** Provider-native cache accounting**— surfaces Anthropiccached_tokens
and GeminicachedContentTokenCount
in billing when the provider reports them.Semantic vector cache via thevalkey-search
module —packages/ai-gateway/internal/cache/semantic/
(lookup, writer, client, circuit breaker, singleflight, poison guard, index lifecycle).In-flight singleflight— concurrent identical prompts fold into one upstream call.
Multi-axis quotas— per organization, per virtual key, per provider, per model. Each axis has its own budget and sliding-window enforcement.Token-based or USD-based budgets.Hard limits and soft limits— soft fires an alert; hard rejects with 429. Real-time accounting— counters update on every traffic event, no batch lag.** Routing strategies**inpackages/ai-gateway/internal/routing/strategies/
:single
,fallback
,loadbalance
,conditional
,absplit
,policy
,smart
.
PII detection · data classification · keyword filtering · content safety · rate limiting · IP allowlists · request-size validation · webhook forwarders · per-stage audit (request hooks and response hooks recorded independently) · body capture (256 KiB inline + spillstore for the rest, see packages/shared/storage/spillstore/
) · SIEM forwarder (packages/compliance-proxy/internal/siem/
) · three-tier kill switch · emergency passthrough (bypassHooks
/ bypassCache
/ bypassNormalize
).
Chat · Embeddings · Structured outputs · Function / tool calling · Vision input · Reasoning tokens. Multimodal (epic E62) in development.
IAM— RBAC + ABAC with an NRN resource model (packages/shared/identity/iam/
).Virtual keys with per-key model scope.OIDC federation with JIT user provisioning (packages/control-plane/internal/identity/authserver/login/oidc.go
, JIT flag inscim_store.go
).Organization / project hierarchy with per-org quota.Credential vault— AES-256-GCM (packages/control-plane/internal/platform/crypto/aes_gcm.go
,packages/ai-gateway/internal/credentials/decrypt/decrypt.go
) with key rotation.Agent fleet management— Hub CA, Thing-based config sync, drift detection.
Five Go services + one React control console. The diagram below shows only the traffic plane — the three independent intercept pipes and where each one egresses. Control plane (Hub-centric) and storage are summarized in the component table immediately after.
flowchart TB
SDK["SDK app<br/>(OpenAI SDK)"]
HTTPS["HTTPS app<br/>(network-proxied)"]
Endpoint["Developer endpoint<br/>(Cursor / Claude Code / …)"]
AIGW["AI Gateway :3050<br/>routing · cache · quota<br/>+ hooks pipeline"]
CPProxy["Compliance Proxy :3128<br/>MITM TLS<br/>+ hooks pipeline"]
Agent["Desktop Agent · local<br/>OS-level intercept<br/>+ hooks pipeline"]
Provider["LLM Provider<br/>(OpenAI / Anthropic / Gemini / …)"]
SDK ==>|"/v1 + VK"| AIGW
HTTPS ==>|HTTPS via proxy| CPProxy
Endpoint ==>|OS-level capture| Agent
AIGW ==> Provider
CPProxy ==> Provider
Agent ==> Provider
Agent -. "X-Nexus-Attestation verified<br/>→ passthrough" .-> CPProxy
The lateral dotted arrow is the attestation handoff: the Agent always egresses directly, but when enterprise network policy happens to route Agent traffic through the Compliance Proxy, the Agent's Ed25519-signed X-Nexus-Attestation
header (E60, packages/agent/internal/identity/attestation/
) is verified at TLS-bump time (packages/shared/transport/tlsbump/forward_handler.go:119
); on success the CONNECT becomes pure passthrough — no MITM, no hooks, no audit on that flow, since the Agent already ran them on its end.
Control plane (out-of-band). All four Go services register with Nexus Hub as Things via packages/shared/transport/thingclient/
(WebSocket primary, HTTP fallback) and pull configuration from the Hub's device shadow on boot and on change-signal — the Hub never pushes full state. The Control Plane admin API (:3001
) and the React UI (:3000
) sit alongside, talking to the Hub the same way.
| Component | Port | Code |
|---|---|---|
| Nexus Hub | ||
| 3060 | packages/nexus-hub/ — Thing Registry, Device Shadow, config sync, jobs, agent CA, SIEM bridge |
|
| Control Plane | ||
| 3001 | packages/control-plane/ (Echo) — admin API / BFF, IAM, SSO, analytics |
|
| AI Gateway | ||
| 3050 | packages/ai-gateway/ — /v1 AI traffic, provider adapters, routing, quota |
|
| Compliance Proxy | ||
| 3128 | packages/compliance-proxy/ — CONNECT, MITM, compliance pipeline |
|
| Agent | ||
| local | packages/agent/ — macOS uses pf packet filter (packages/agent/internal/platform/darwin/pfintercept/ ); Linux uses iptables ; Windows uses WinDivert . The legacy NETransparentProxyProvider path (packages/agent/platform/darwin/NexusAgent/NexusAgentExtension/ ) is still in the repo behind interceptMode=ne , but new builds default to pf. All three platforms are development-complete, not yet QA-signed-off. |
|
| Control Plane UI | ||
| 3000 | packages/control-plane-ui/ — React + Vite + TypeScript |
Storage stack
PostgreSQL 16— durable storage. Prisma schema intools/db-migrate/
is the source of truth for dev-time migrations; runtime code reads via hand-written SQL +pgx
(nosqlc
).Valkey 8— Redis-wire-compatible, pinned tovalkey/valkey-bundle:8-trixie
indocker-compose.yml
for BSD-license parity; thevalkey-search
module ships in the bundle image and backs the semantic vector cache. Pure cache only — no pub/sub.NATS JetStream— event streaming and Hub coordination viapackages/shared/transport/mq/
.
| Tool | Version | Notes |
|---|---|---|
| Node.js | 20+ | |
| npm workspaces require npm 10+ | ||
| Go | 1.25+ | |
All Go modules share go.work at the repo root |
||
| Docker | any recent | Hosts PostgreSQL, Valkey, NATS via docker-compose.yml |
./scripts/dev-start.sh
The script:
- Verifies prerequisites (Node 20+, Go 1.25+, Docker, OpenSSL).
- Auto-creates
repo-root from
.env
.env.example
with safe dev defaults forCHANGE_ME_*
secrets (INTERNAL_SERVICE_TOKEN
,ADMIN_KEY_HMAC_SECRET
,CREDENTIAL_ENCRYPTION_KEY
=openssl rand -hex 32
, …). All four Go services read this viapackages/shared/core/bootenv/
at boot. - Starts PostgreSQL + Valkey + NATS via
docker-compose.yml
. - Runs
npm install
. - Auto-creates
and propagatestools/db-migrate/.env
CREDENTIAL_ENCRYPTION_KEY
into it soprisma db seed
can re-encrypt the seed credentials. - Applies the Prisma schema (
db push
) and seed undertools/db-migrate/
. - Auto-generates the
Compliance Proxy dev CA atpackages/compliance-proxy/dev-certs/{ca.crt,ca.key}
so the TLS-bump cert issuer can boot. - Prints the per-service
go run … -config <svc>.dev.yaml
commands. - Finally starts the Control Plane UI dev server.
Flags:
--force-reset
— DESTRUCTIVE: wipe local Postgres / Valkey / NATS volumes + the entirenexus_gateway
database before re-applying the schema.--no-dev
— bootstrap only; print the per-service commands and exit instead of starting the UI dev server.
Open one terminal per Go service after the bootstrap finishes:
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 defaults to <svc>.config.yaml
, which is the prod-shape template and is intentionally missing dev-only fields like hub.id
. Without the flag the service fails fast at boot.
Each Go service tees logs to packages/<service>/logs/<service>.log
in dev mode (configured in the service's *.dev.yaml
). Override the path with LOG_FILE=/path/to/file
.
Browse to http://localhost:3000 and sign in as the seeded super-admin:
admin@nexus.ai / admin123
Additional seeded roles (alice@nexus.ai
, carol@nexus.ai
, bob@nexus.ai
, diana@nexus.ai
) are defined in tools/db-migrate/seed/seed.ts
.
After the stack is up, walk through examples/01-hello-world/ — a 3-minute curl-through-the-gateway demo that ends with you reading the resulting
traffic_event
Postgres row.The Control Plane uses OAuth + PKCE bearer tokens. Helpers wrap the flow:
cp tests/.env.local.example tests/.env.local # gitignored; edit if you need to override defaults
source tests/lib/loadenv.sh local # picks up tests/.env.local + tests/.env.local.example defaults
source tests/lib/auth.sh
cp_login # idempotent; caches token at /tmp/nexus_test_token_local
cp_curl /api/admin/analytics/cost?groupBy=device
cp_curl -X POST /api/admin/routing-rules -d @rule.json
For direct DB inspection in dev:
docker exec $(docker ps --filter "name=postgres" -q | head -1) \
psql -U postgres -d nexus_gateway -c "SELECT ..."
You came for an AI gateway. You also get the disciplined AI pair-programming setup that built it. CLAUDE.md,
.cursor/rules/
.claude/skills/
lint suite form a fork-adoptable methodology:
scripts/check-*
Binding rules inCLAUDE.md
plus35 entries (.cursor/rules/
ls .cursor/rules/
).26 invocable skills under.claude/skills/
—/prod-deploy
,/smoke-gateway
,/spec-writing
,/add-provider-adapter
, hardened runbooks for repeatable procedures.23— every binding rule has a mechanical gate; pre-commit + CI dual layer.scripts/check-*
lint scripts95% per-package coverage gate enforced byscripts/check-go-coverage.sh
+scripts/.coverage-allowlist
.2-round completion self-audit before claiming "done" (seeCLAUDE.md
→ Mandatory rules → Workflow discipline → Self-audit).
packages/
nexus-hub/ Go — Thing Registry, Shadow, config sync, jobs, SIEM bridge, agent CA
control-plane/ Go + Echo — admin API / BFF, IAM, SSO, analytics
ai-gateway/ Go — /v1 AI traffic, provider adapters, routing, quota
compliance-proxy/ Go — transparent TLS proxy, CONNECT, compliance pipeline
agent/ Go — desktop traffic interception (macOS / Linux / Windows;
all builds in development, awaiting QA)
shared/ Go — cross-service business logic (hooks, traffic, configtypes,
mq, thingclient, cache, …)
control-plane-ui/ React + Vite + TypeScript — admin dashboard
ui-shared/ Shared design tokens, chart colors, i18n bundles
tools/db-migrate/ Prisma schema + migrations + seed (dev-time only)
scripts/ dev-start.sh + check-* lint scripts
tests/ Test harnesses, .env.local.example, auth.sh helper, smoke scripts
examples/ Self-contained demos (01-hello-world, …)
docker-compose.yml Local PostgreSQL + Valkey + NATS
go.work Go workspace (one module per package + tools)
Makefile build / test targets per service
Go services— Go 1.25+ withgo.work
; Echo on Control Plane / Nexus Hub / AI Gateway (labstack/echo/v4 v4.15.2
); structured logging vialog/slog
; metrics via Prometheuspromauto
; Redis-wire clientredis/go-redis/v9 v9.19.0
; WebSocket viacoder/websocket v1.8.14
.Control Plane UI— React + Vite + TypeScript (strict mode); React Query via theuseApi
hook; layered design tokens inpackages/ui-shared/src/styles/
(global.css
raw →light.css
/dark.css
semantic, flipped bydata-theme
); i18n withreact-i18next
(en
/zh
/es
underpackages/control-plane-ui/public/locales/
andsrc/i18n/locales/
); tests via Vitest.Database— PostgreSQL 16. Prisma is the dev-time source of truth (tools/db-migrate/
); runtime queries use hand-written SQL +pgx
.Cache— Valkey 8 (Redis-wire-compatible, BSD-licensedvalkey/valkey-bundle:8-trixie
image). Pure cache only — no pub/sub anywhere.MQ— NATS JetStream behind thepackages/shared/transport/mq/
interface.Monorepo— npm workspaces (packages/control-plane-ui
,packages/agent/ui/frontend
,tools/db-migrate
) +go.work
for Go.
Every Go module under packages/
references its sibling workspace packages by require github.com/AlphaBitCore/nexus-gateway/packages/<sibling> v0.0.0-<timestamp>-<commit>
. Those pseudo-version require
s are only there to make each module syntactically valid on its own — real resolution comes from go.work
at the repo root.
This has one consequence: if go.work
is missing from the build context, Go falls back to the literal pseudo-version in require
and tries to fetch the module from GitHub instead of using the local source tree. The build "succeeds" against an old remote snapshot, masking local changes.
Rules for every build environment:
Fresh clone—git clone
already includes the committedgo.work
andgo.work.sum
. Rungo build
from inside the repo.Docker— copygo.work
+go.work.sum
and every, not just the service's own folder. Minimum viable layout:packages/<module>
directory the service transitively depends on
WORKDIR /build
COPY go.work go.work.sum ./
COPY packages/shared packages/shared
COPY packages/<svc> packages/<svc>
WORKDIR /build/packages/<svc>
RUN go build -o /out/<svc> ./cmd/<svc>/
CI— use fullactions/checkout
(default fetch-depth, no sparse-checkout).Sanity probe—GOWORK=off go build ./cmd/<svc>/
from inside a workspace package should refuse to build or pull a remote snapshot.
If a contributor reports "Go keeps down our own modules from GitHub", the answer is always: their build context is missing go.work
(or they have GOWORK=off
set).
| Command | Purpose |
|---|---|
./scripts/dev-start.sh |
|
| One-shot bootstrap (Docker + DB + seed + UI) | |
npm run dev:control-plane-ui |
|
| Start the UI dev server only | |
make build-all |
|
Build the Go services + UI. Go binaries land in dist/bin/<service>/<binary> . |
|
make test-all |
|
Run go test -race -count=1 for every Go module + UI Vitest |
|
make clean |
|
Remove dist/bin/ and packages/control-plane-ui/dist/ . Platform agent packages under dist/{macos,linux,windows}/ are preserved — clean those via the per-platform targets (agent-clean-macos , agent-clean-windows ). |
|
npm run check:all |
|
| Run every pre-commit lint (i18n parity, design tokens, terminology, migration timestamps, useApi keys, sidebar icons, …). CI runs the same set. | |
npm run db:migrate |
|
Create a new Prisma migration in tools/db-migrate/ |
To build, sign, notarize, or package the macOS Agent (.app
/ .pkg
), always invoke the build-agent
Claude Code skill — not the raw wails
/ codesign
/ notarytool
commands. See CLAUDE.md
→ "macOS Agent builds MUST go through Skill('build-agent')
" binding rule for why.
— binding charter. Plan + Todo gate, English-only artifacts, IAM impact review, macOS NE fail-open, pre-edit reading, completion-time self-audit, real-implementation-only, development-phase greenfield policy.CLAUDE.md
— workflow summary, pre-commit checks, high-blast-radius surfaces, review pointers.CONTRIBUTING.md
Project Maintainer— the original idea behind Nexus Gateway came from him, and he stayed hands-on throughout: code, tests, design reviews, architectural decisions.The wider team— engineers, code reviewers, QA, design folks, and the people running prod. The architecture decisions, design reviews, code-review catches, and prod incidents that shaped this codebase all came from team collaboration.— Anthropic's CLI assistant did the lion's share of the implementation work, side-by-side with the human maintainers.Claude Code
AI is already here. Keep learning, keep adapting.