Architecture overview¶
JANUS is a Git-backed, API-first policy and routing control plane for WireGuard remote access. It lets an organisation grant access to its own network precisely — per user, per device, per resource — and deny everything else, without exposing anything it has not explicitly permitted.
The mental model¶
Browser / operator / API
|
v
+--------------------------+
| Controller | configuration of record (Git)
| WebUI · API · Portal | runtime state (PostgreSQL)
| compiles desired state |
+--------------------------+
|
delivers desired state per Gateway
v
+--------------------------+
| Gateway node | applies state in its own runtime
| gateway agent | domain; enforces policy
+--------------------------+
|
WireGuard Site Edge
v |
Clients Customer site
A client enrols with its own WireGuard key and opens a tunnel to a Gateway. The Gateway forwards the client's traffic only to what policy permits; every other forwarded packet is dropped. Access decisions come from declarative configuration held in Git, compiled by the Controller into a per-Gateway desired state, and enforced on the Gateway in the data plane.
Components¶
| Component | Role |
|---|---|
| Controller | Holds the configuration of record in Git, keeps runtime state in PostgreSQL, compiles desired state per Gateway, and serves the management API. It never touches the data plane directly. |
| WebUI | The administrative interface. It is an API client and holds no JANUS semantics of its own. |
| Portal | The user self-service interface, scoped to one user's own devices and access. |
| Gateway node | A host running a gateway agent. It may serve several Deployments as isolated runtime domains. |
| Gateway agent | Accepts desired state for its domain, applies it, and reports back what it actually applied. |
| Site Edge | A participant representing a customer site. It routes; it never authorizes. |
| Client | Enrols with its own key, connects to an eligible Gateway, reaches only permitted resources. |
| Git repository | The source of truth for desired state. |
| PostgreSQL | Controller runtime state: identity, runtime/observability data, audit. |
Control plane versus data plane¶
The control plane decides what the network should look like. The data plane carries — and refuses — traffic. The two are separated on purpose:
- the Controller never configures a kernel;
- a Gateway that cannot apply its state says so instead of silently diverging;
- what was intended and what is running are separately observable.
See Data plane and Gateway agent.
Where each kind of information lives¶
| Category | Storage | Examples |
|---|---|---|
| Desired state | Git (YAML) | Users, Groups, Devices, Resources, Prefixes, policies |
| Runtime state | PostgreSQL | enrolment state, runtime/observability data, audit events |
| Secrets | Outside Git | private keys, password hashes, API tokens |
| Installation configuration | local files on each host | database connection, Git transport, listeners, TLS trust |
Nothing in Git is a secret, and no administrative identity or authorization state is desired state.
Tenancy and placement¶
Tenant an administrative and ownership boundary. Never a runtime identity.
Deployment the unit of policy, addressing, clients and runtime domains.
GatewayNode an infrastructure node; executes one runtime domain per Deployment.
Three distinctions are load-bearing throughout JANUS:
- Capability ≠ Entitlement ≠ Placement. What a node can do, what a Tenant is entitled to, and where a workload is placed are three separate decisions, declared separately.
- A GatewayNode is where a Deployment runs — not what it is. Two Deployments on one physical node are two independent runtime domains: separate WireGuard interfaces and keys, routes, firewall tables, NAT and conntrack, and separate applied identity.
- Deployments are isolated, including their addresses. Two Deployments may reuse the same client, resource and site address space without colliding.
The runtime identity of a domain is the pair (GatewayNode, Deployment). It is
address-blind and stable across effective-state changes.
Configuration is the source of truth¶
Configuration is authored as objects (Management API, WebUI, or directly in Git), versioned in Git, compiled, delivered, and applied. Administration through the API or WebUI produces Git commits — the browser is a client of the API, not a second source of truth.
author intent -> configuration objects (Git)
configuration -> compiled desired state (per Gateway)
desired state -> delivered to the Gateway
applied state -> reported back by the Gateway
observed state -> derived from real runtime signals
Intent and reality are reconciled continuously, and the difference is always observable. See Operations.
Safety properties¶
- Deny by default. Only explicitly enabled policy grants access. Forwarded traffic that no policy authorizes is dropped.
- NAT is never implicit. No NAT policy means no NAT rules; NAT translates already-authorized traffic and never grants access.
- Fail-closed. A Gateway that loses its Controller, an apply that cannot complete, and a destination that becomes internal all converge to a deterministic safe state rather than an open one.
- The fabric is not implicitly trusted. Traffic between Gateway nodes is subject to the same authorization as any other flow.
- The Controller configuration is the upper safety boundary. Git desired state operates within it and cannot expand it.
Controller configuration imposes maximum authority
v
Git desired state requests assignments within that authority
v
Validator rejects requests outside it
v
Compiler produces the per-Gateway desired state
Technology¶
| Component | Technology |
|---|---|
| Operating system | Debian 13 |
| Implementation language | Go |
| Source of truth | Git |
| Database | PostgreSQL |
| VPN | WireGuard |
| Firewall | nftables |
| Configuration format | YAML |
| API | REST / JSON |
| Front end | Go + templ + HTMX + Tailwind |
| Routing | declarative and static |
What this release does not include¶
Documented deliberately, so the boundary is not mistaken for a feature:
- No dynamic routing protocols. The route policy schema carries a mode field
whose
bgpvalue is accepted and compiled into a desired state, but no routing daemon is installed or managed by JANUS, so BGP is not usable in this release. Routing is declarative and static. - No NAT66. IPv6 is routed, never translated.
- One provider attachment per Site Edge, and no automatic Site Edge HA.
- No local breakout at a Site Edge: customer traffic always exits at the provider Gateway.
- No automatic MTU/PMTU derivation or validation.
- No external identity provider, SSO or federation integration.