passtunnel

PassTunnel

Connect your VPN without ever typing a one-time code again.

PassTunnel is an open-source macOS app for OpenVPN and FortiGate SSL VPN. It keeps your TOTP secret in the Keychain and fills in the current code (and your password) every time you connect.

Features · Install · Quick start · Code format · CLI · AI assistants · FAQ · Security · Türkçe

Features

One-time codes, handled

• No more typing codes. The TOTP secret lives in the macOS Keychain; PassTunnel generates the code and sends it with your password when you click Connect. If fewer than 8 seconds are left in the current window, it waits for a fresh code instead of racing the clock.

• Any format your server expects. Append, prepend, password:code, password,code, or a custom template with any literal text, or send the code separately (OpenVPN static challenge, FortiGate OTP field). See Configuring the code format.

• Authenticator-style main window. Every profile shows its live code in large digits with a countdown ring. Click to copy; the clipboard is cleared again after 30 seconds. Codes can be hidden until copied.

• QR import. Drop a screenshot of your provider's QR code, choose an image or paste from the clipboard. Digits, period and algorithm (SHA-1/256/512) are read from the otpauth:// link. Pasting a Base32 secret or an otpauth:// link works too.

• Auto-type (optional, off by default). With global shortcuts on, ⌃⌥C types the current code into the focused field (also in the menu bar menu), for web portals and other places that still ask for it. Needs Accessibility permission, which is only requested when you turn the feature on.

• Confirm with Touch ID (optional, per profile). Touch ID or your Mac password before connecting, or also before showing codes; the saved secrets are then encrypted with a key in the Mac's Secure Enclave, so a one-click connect needs you, not just your unlocked Mac.

VPN client

• OpenVPN and FortiGate SSL VPN, using bundled, signed copies of openvpn and openfortivpn. Nothing else to install.

• Menu bar badges. One colored badge per pinned or active profile (letter, icon or both), five color palettes, and an alert when a connection drops unexpectedly.

• Stays connected. Optional auto-reconnect with backoff, a health check host inside the VPN, reconnect after wake, and a reminder before a server-side session limit runs out.

• Several VPNs at once, each with its own status, log and settings.

• Shareable profiles. Export a .passtunnel file for your team. It never contains passwords, TOTP secrets or user names.

• Command-line tool. passtunnel connect, passtunnel code -c, --json output, stable exit codes and shell completions: the same features as the app.

• Works with AI assistants. passtunnel mcp is an MCP server, so Claude Code, Claude Desktop and other MCP clients can check your VPNs, read logs and diagnose problems. Read-only unless you allow connecting, and it never hands out passwords, secrets or codes.

• No sudoers rule, no admin password at every connect. A small privileged helper, registered through macOS's own SMAppService and approved once, runs only the VPN tools signed and shipped inside the app, with sanitized configurations. See SECURITY.md.

• English and Turkish user interface (follows your macOS language).

How it works

PassTunnel.app ──XPC──▶ PassTunnelHelper (root) ──▶ bundled openvpn / openfortivpn
  │  (code-signature checked)                             │
  ├─ Keychain: password + TOTP secret                     └─ management socket (OpenVPN),
  └─ ~/Library/Application Support/PassTunnel                log file, status ──▶ back to the app

1. You click Connect. The app reads your password and TOTP secret from the Keychain, computes the current code and builds what the server expects (for example secret123456).

2. The app hands the request to the privileged helper over XPC. The helper accepts only the signed PassTunnel app, checks that the profile folder belongs to you, sanitizes the OpenVPN config (or writes the openfortivpn config itself from typed fields) and starts the bundled tool, which it lets run only after checking the signature of the code that was actually loaded.

3. The app follows the connection state (OpenVPN through a management socket that only your user can open, FortiGate through the log) and shows it in the window and the menu bar.

The full security model, including what is not protected, is in SECURITY.md. The code layout is described in docs/ARCHITECTURE.md.

Install

Requires macOS 13 Ventura or later on a Mac with Apple silicon.

Download

Download PassTunnel-.dmg from GitHub Releases, open it and drag PassTunnel to Applications. Launch it from there: the helper can only be installed from the Applications folder. The app is signed with a Developer ID and notarized by Apple.

PassTunnel keeps itself up to date (Settings → Updates); updates are signed and checked before they are installed. After an update, the helper is updated automatically as soon as no VPN connection is active (only when PassTunnel runs from the Applications folder).

Homebrew

brew trust passtunnel/tap
brew install --cask passtunnel/tap/passtunnel

Since Homebrew 6, casks from third-party taps load only once you trust the tap, hence the first line. The cask also links the passtunnel command. Updates arrive through the app itself, so brew upgrade leaves it alone unless you run brew upgrade --greedy.

Build from source

You need Xcode 15.3 or later (Swift 5.10, plus xcstringstool for the Turkish strings) and Homebrew, which provides the VPN tools that get bundled into the app:

brew install openvpn openfortivpn
git clone https://github.com/passtunnel/passtunnel.git
cd passtunnel
scripts/build-app.sh                  # → build/PassTunnel.app (ad-hoc signed)

build-app.sh builds a release binary, assembles the bundle, copies openvpn, openfortivpn and their libraries in (scripts/bundle-tools.sh, with their license files), compiles the helper with the code-signature hashes of exactly these tools and libraries, and signs everything inside-out with the hardened runtime.

Important

The helper only talks to an app, and only runs tools, signed with the project's Developer ID Team ID. An ad-hoc build is fine for the window, codes, QR import, profiles and the CLI, but cannot connect. To connect with your own build, set teamID in Sources/PassTunnelShared/Identifiers.swift to your Team ID and sign with your certificate:

scripts/build-app.sh --sign "Developer ID Application: Your Name (TEAMID)"

Then move build/PassTunnel.app to /Applications before installing the helper.

Quick start

On first launch PassTunnel walks you through three steps:

1. Welcome.

2. Install the helper. Click Install Helper, then turn PassTunnel on in System Settings → General → Login Items (macOS asks once). You can also do this later from Settings → Helper.

3. Add your first VPN.

Add a profile

Use the + button in the toolbar, or drop a file onto the window:

Then open the profile editor (⋯ → Edit…):

• Sign-in: user name (leave empty to be asked each time) and password: saved in the Keychain, asked each time, or none (certificate-only OpenVPN).

• One-time code: Generate (TOTP), Ask each time, or None. With Generate, scan the QR code or paste the secret, and compare the live code with your phone before saving.