title: Nodes and gateways description: Understand Nanami's current routing gateways and the planning-only fallback transport boundary.
Nanami separates routing-capable gateways from the planning-only fallback transport work that may arrive later.
Node
A node is a data-plane participant in one or more workspace networks.
Node records include identity material (public key), status, endpoint metadata, and network memberships.
Network Gateway (current)
A Gateway is a WireGuard node that can route traffic for one or more workspace networks.
Gateway behavior in MVP:
- workspace-scoped by default,
- can participate in ingress/egress and exit-node routing,
- receives desired state from gateway-manager,
- applies interfaces/routes/NAT through gateway-daemon,
- can be assigned automatically (
auto,balanced) or manually (coming soon UI controls).
Diagram (text)
Client -> Gateway -> Private network resources
Gateway manager and gateway daemon agents
Nanami currently uses two runtime agents:
- gateway-manager (compat:
gateway-manager): desired/observed control loop. - gateway-daemon (compat:
gateway-daemon): local runtime apply and telemetry.
Diagram (text)
Control plane -> gateway-manager -> gateway-daemon -> observed state -> control plane
Shared region groundwork (current)
The current release already carries shared-region groundwork that future fallback transport can build on:
- a platform-scoped region catalog,
- tenant/workspace access to named regions,
- internal read-only oversight surfaces for platform operators.
This groundwork is not a live transport gateway mesh. It is the current placement and explanation contract that keeps region truth explicit without pretending shared fallback workers exist today.
Future fallback transport (planning-only)
Fallback transport remains planned as connectivity fallback only (DERP-like), not as a routing gateway or policy router.
Planned properties:
- stateless forwarding layer,
- safe to share across workspaces because no route ownership,
- no workspace AllowedIPs/route/NAT control,
- explicit separation from the current routing-gateway baseline.
Diagram (text)
Client A <-> Shared fallback transport (future) <-> Client B
Why this split matters
- Gateways route and can be workspace-sensitive.
- Shared-region groundwork is current, but shared fallback transport is not.
- Future fallback transport should improve reachability without becoming a policy router.
- This keeps cross-workspace safety and operator mental model clear.
Future-only follow-up
- Shared fallback transport implementation on top of the current shared-region groundwork.
- Multi-hop routing chains and policy-based pathing.
- Gateway redundancy policies (
redundancy: 2+).