overpass has three moving parts: a control plane, node agents, and clients. The design goal is that the proxy brokers connectivity but never sees your SSH traffic in the clear.

Certificate authorities

On first run the control plane generates two Ed25519 certificate authorities:

• User CA — signs short-lived user certificates when you log in.
• Host CA — signs node host certificates when a node enrolls.

Nodes trust the User CA (so they accept user certificates); clients trust the Host CA (so they can verify they're talking to a genuine node). Neither side needs long-lived authorized-keys files.

Logging in

op login authenticates (local password or OIDC) and receives a user certificate valid for a few hours. The certificate encodes:

• the principals (unix logins) you may use, and
• access groups — which logins are allowed on which nodes, derived from your roles (see RBAC).

The certificate, not a static key, is what authorizes the SSH connection.

The reverse tunnel

Node agents dial out to the proxy's tunnel port and hold the connection open (multiplexed with yamux over TLS). This means:

• nodes need no inbound firewall rules — only outbound to the proxy;
• the proxy always has a live path to each online node.

flowchart LR
  subgraph client[Your laptop]
    OP[op ssh]
  end
  subgraph proxy[Control plane]
    P[Proxy :3023]
  end
  subgraph node[Server]
    N[node agent + sshd]
  end
  N -- "dials out :3024" --> P
  OP -- ":3023" --> P
  P == "byte bridge" ==> N

(With TLS routing enabled, both of those flows — and gRPC and the web UI — share the web port, distinguished by TLS ALPN.)

End-to-end SSH — the core invariant

When you run op ssh, the proxy splices two byte streams together: your client and the node's tunnel. It performs no SSH handshake of its own — it is a dumb L4 bridge. The SSH session is negotiated directly between your client and the node's host key, so:

• the proxy cannot read or modify your session;
• the node authenticates your user certificate against the User CA and enforces your access groups fail-closed.

Note

The one deliberate exception is the browser terminal: there your private key lives in the browser, so the control plane is a legitimate SSH endpoint. It mints a single-use, single-node delegated certificate and bridges the session over a WebSocket. See the web UI.

Authorization at the node

Every node validates an incoming user certificate with ssh.CertChecker: it checks the User CA signature, validity window, principals, and critical options, then enforces the certificate's access groups against its own labels. A user only reaches nodes their roles allow, and the proxy never participates in that decision.