Browse docs

Architecture overview

Learn the model

Control, gateways, and WireGuard flow

High-level architecture overview for policy, gateway runtime, and encrypted transport.

Section: Learn the model
Path: /architecture/overview

This page describes how Nanami moves from policy to packet flow.

Component map

Management service

Responsibilities:

API, auth, tenancy, RBAC,
inventory for networks/nodes/gateways,
desired-state generation,
observed-state ingestion.

Gateway coordination service

Responsibilities:

fetch desired state,
coordinate runtime nodes,
post observed state and tunnel telemetry.

Gateway runtime

Responsibilities:

register runtime node identity,
apply WireGuard interfaces/routes/NAT,
report runtime status and network snapshot.

End-to-end data paths

Direct path

Client <-> (direct UDP) <-> Client

Private network routing path

Client -> Gateway -> Private Network

Shared-region groundwork (current)

Nanami already has a shared region model, platform-managed placement truth, and internal oversight surfaces for region coverage.

That groundwork does not mean a live shared fallback-transport runtime is active today.

Future fallback path (planning-only)

Client <-> Shared fallback transport (future) <-> Client

Shared fallback transport remains planning-only and is not part of the current routing baseline.

Gateway assignment behavior (current public model)

default policy: assignmentMode=auto, selection=balanced, redundancy=1,
scheduler is workspace-scoped and stable to avoid churn,
default runtime architecture is single WireGuard interface per gateway (InterfacePerNetwork=false),
gateway security boundaries are enforced server-side:
- strict per-peer AllowedIPs (/32 overlay identity),
- deny-by-default forwarding ACL with workspace-scoped allowed prefixes.

Manual WireGuard configs are Limited Mode:

client-side AllowedIPs can be edited and are not a trust boundary,
server-side gateway policy remains authoritative,
advanced dynamic routing/policy workflows are managed-mode roadmap.

Failure boundaries

Control-plane failures affect config changes and management APIs.
Existing data-plane flows may continue until they need new config.
Gateway runtime failures affect routing for assigned networks only.

Roadmap hooks

Shared-region groundwork evolving into a future fallback transport runtime.
Multi-hop routing chains and path policy.
Gateway HA redundancy (2+ gateways per network).
Enterprise isolation mode: InterfacePerNetwork=true with VRF/namespaces.
Enterprise port pools / port profiles (platform-managed).

Next steps

Pick the most useful next step instead of the next random article.