This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This walks through running a control plane, enrolling a node, and connecting — on a single machine to start.

Install

Binary

Download the binaries for your OS/arch from the releases page and put overpass, op and opctl on your PATH. Linux and OpenBSD are published for amd64 and arm64; Windows is published for amd64. macOS on Apple Silicon receives all three binaries, with overpass supported as a native node agent.

Homebrew

The op and opctl CLIs are published to a tap on OFKM's Forgejo. The tap repository is not on GitHub, so pass its URL when adding it:

brew tap ofkm/tap https://forgejo.ofkm.us/brew/tap.git
brew install --cask ofkm/tap/op

Upgrades then come from brew upgrade. The cask installs both op and opctl; the overpass daemon is not distributed through Homebrew.

Docker

docker run -d --name overpass \
  -p 8443:8443 -p 3023:3023 -p 3024:3024 -p 3025:3025 \
  -v overpass-data:/var/lib/overpass \
  forgejo.ofkm.us/ofkm/overpass:latest

Then read the claim code with docker logs overpass, open /setup, and follow the browser setup. See Docker for optional public-address settings.

NixOS

Import overpass.nixosModules.default from the repository flake, then enable services.overpass or services.overpass-node. See NixOS for the complete module options, secret handling, and update workflow.

From source

git clone https://github.com/ofkm/overpass && cd overpass
just build      # builds the UI + the three binaries into ./bin

1. Start the control plane

The control plane generates its certificate authorities and a self-signed TLS certificate on first run.

overpass server --data-dir ./data

It listens on four ports (see Configuration): 8443 (web UI + API), 3023 (client SSH), 3024 (node tunnels) and 3025 (gRPC). With TLS routing enabled, the web port alone carries all of them.

2. Complete the initial setup

Open https://localhost:8443/setup and enter the one-time claim code printed by the control plane. Create the first administrator and optionally add the Unix logins you will use on target servers. Setup signs you in automatically and shows the next steps in the dashboard.

The claim code is deliberately shown only in startup logs and is stored encrypted at rest until it is used. If a browser flow is unavailable, opctl can still create users and tokens directly for recovery or automation.

Note

The optional Unix logins are the usernames the administrator may use on target nodes. The admin role grants full management plus access to every node; see RBAC to scope access by node labels.

3. Enroll a node

On the server you want to expose (here, the same machine), run the agent. The agent dials out to the proxy — no inbound ports are needed on the node.

overpass node --name web-1 --proxy localhost:3025 \
  --token <token-from-the-wizard> --labels env=dev --insecure

--insecure skips TLS verification of the proxy, which is convenient against a local self-signed certificate. For a real cluster, put a reverse proxy with a trusted certificate in front, or keep the self-signed cert and use --insecure only while testing. The node enrolls, then establishes its reverse tunnel and shows as online. The server’s Details card shows whether that tunnel used ECDSA P-256 or ML-DSA-44.

For a remote machine, use the one-line installer served by your control plane instead — it downloads the right binary, enrolls and sets up a system service (launchd, systemd, OpenRC, runit, s6, sysvinit, or OpenBSD rc.d — see Servers for the full list):

# Linux
curl -fsSL https://<your-server>/install.sh | sh -s -- --token <token-from-the-wizard>

# macOS on Apple Silicon
curl -fsSL https://<your-server>/install.sh | sh -s -- --token <token-from-the-wizard>

# OpenBSD — ftp, sha256 and doas are provided by the base system
ftp -V -o - https://<your-server>/install.sh | sh -s -- --token <token-from-the-wizard>

Run it as root, or as a user with sudo/doas — the script re-runs itself with whichever is available.

Tip

Prefer the web UI? Sign in at https://localhost:8443, click Add a resource, and follow the guided wizard — it generates the exact command and waits for the node to come online. See Onboarding nodes.

4. Log in and connect

op login localhost:8443 --user admin --insecure
op ls                       # list nodes you can reach
op ssh "$(whoami)@web-1"    # open a session

op login obtains a short-lived SSH certificate; op ssh connects through the proxy to the node — end to end, the proxy never sees your session in the clear.

Next steps

• How it works — The certificate + reverse-tunnel model.
• RBAC — Scope access with roles and node labels.
• OIDC sign-in — Wire up your identity provider.