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.
Gateway workers (current)
A Gateway is a shared platform dataplane worker that can route traffic for assigned workspace networks when the runtime can isolate each tenant/network route domain safely.
Gateway behavior in MVP:
- runtime inventory is platform/operator managed; workspaces do not own one gateway each,
- assignment rows, network membership, policy, and audit stay workspace-scoped,
- shared multi-tenant assignment is product-owned and must fail closed unless route-domain isolation, per-network protocol interfaces, and packet-time source+destination ACLs are available,
- 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) and exposed through explicit operator controls where those controls are implemented.
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 and gateway-worker inventory 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 DERP-like fallback transport mesh. It is the current placement and explanation contract for gateway runtime without pretending fallback relay behavior exists 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 carry workspace-sensitive policy, so tenant isolation remains in assignments and generated runtime state.
- 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.
Planned follow-up areas
- 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+).