Nanami DocsGuide
Search docsFilter pages by title

Control, gateways, and WireGuard flow

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

Component map

Control plane (apps/control-plane)

Responsibilities:

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

Gateway manager (apps/gateway-manager, compatibility name)

Responsibilities:

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

Gateway daemon (apps/gateway, compatibility name)

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

Future fallback path (coming soon)

Client <-> Transport Gateway (future) <-> Client

Transport gateways are planned as connectivity fallback only, not routing gateways.

Gateway assignment behavior (MVP)

  • default policy: assignmentMode=auto, selection=balanced, redundancy=1,
  • scheduler is tenant-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 tenant-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.

TODO roadmap hooks

  • Shared transport gateways (DERP-like).
  • 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).

Related pages

Edit this page