Overpass

Overpass is a self-hosted remote access gateway. Users sign in with a local account or OIDC and connect with short-lived SSH certificates. Servers run an agent that connects outbound to Overpass, so they do not need a public SSH port.

Overpass includes a web dashboard and three commands:

• overpass runs the control plane or a server agent.
• op connects to servers.
• opctl manages Overpass from the command line.

Quick start

1. Start Overpass

The image already starts the control plane with its built-in defaults. The browser-facing address is inferred from the request, so no command override is needed for a first run.

docker compose up -d
docker compose logs overpass

Open https://localhost:8443/setup, enter the one-time claim code from the startup log, and create the first administrator. The certificate is self-signed on a new installation, so your browser will show a warning. The setup page can optionally record the Unix usernames you will use on servers; you can change them later.

For a deployment behind a reverse proxy, define public_url and public_addr in /etc/overpass.yaml, or use OVERPASS_PUBLIC_URL and OVERPASS_PUBLIC_ADDR as fallbacks when those YAML fields are omitted. See Configuration for the precedence rules.

2. Add a resource

After setup, open Servers, select Add a resource, and run the generated command on the machine you want to access. The agent installs as a service and connects back to Overpass.

3. Connect

Download op from the account page in Overpass, then run:

op login your-hostname:8443 --user admin --insecure
op ls
op ssh your-unix-user@your-server

--insecure is only needed while Overpass uses its self-signed certificate. You can also connect from the browser terminal.

If browser setup is unavailable, opctl --local still supports recovery against the data directory. After signing in with op, normal opctl commands reuse that login to administer the server through its API.

Production setup

• Keep the overpass-data volume. It contains the database, the SSH certificate authority keys, and the server-managed config directory (overpass.d/) holding configuration made through the web UI.
• Back up that volume.
• Configure a trusted certificate before removing --insecure.
• Limit access with roles and server labels.
• Configure OIDC if you do not want to manage local passwords.

See the documentation for configuration, certificates, OIDC, roles, reverse proxies, and node management.

Install without Docker

Download overpass, op, and opctl from the releases page. The getting started guide covers a binary installation. Linux and OpenBSD binaries are published for amd64 and arm64; Windows is published for amd64. On Apple Silicon, macOS receives overpass, op, and opctl; the overpass binary runs as a native node agent for SSH, file access, and local VNC Screen Sharing. The node installer sets up a service under launchd, systemd, OpenRC, runit, s6, sysvinit, or OpenBSD rc.d, and a node knows which one it runs under so a fleet update can restart it correctly.

NixOS

The repository flake builds Overpass from source and provides modules for the control plane and node agent. Add it to your system flake:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    # Do NOT set inputs.nixpkgs.follows: the package pins Go/pnpm hashes against
    # Overpass's own nixpkgs, and following a different one fails the build.
    #
    # No ref tracks main (rolling); ?ref=refs/tags/v0.19.0 pins one release.
    # Both are gated by a Nix build in CI.
    overpass.url = "git+https://forgejo.ofkm.us/ofkm/overpass.git";
  };

  outputs = { nixpkgs, overpass, ... }: {
    nixosConfigurations.gateway = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        overpass.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

Then enable the control plane in configuration.nix:

{
  services.overpass = {
    enable = true;
    openFirewall = true;
    settings = {
      cluster_name = "production";
      proxy = {
        public_addr = "overpass.example.com";
        public_url = "https://overpass.example.com";
      };
    };
  };
}

Apply it and read the one-time setup code from the service log:

sudo nixos-rebuild switch --flake .#gateway
sudo journalctl -u overpass -b

For a node, enable services.overpass-node on that host and provide a one-time join token through joinTokenFile. See the NixOS guide for node enrollment, TLS pinning, secret handling, all module options, and the package-managed update workflow.

License

Overpass is licensed under the BSD 3-Clause License.