Skip to content

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 bgp value 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.