Install
Get running in a few steps
Four pieces on four machines. The Gateway is a Linux server (the broker); the OSH Client, CA Signer & iPhone Approver are cross-platform — see the apps block below. Copy-paste per platform.
gateway — linux server
# 1) Download the .deb / .rpm above (your OS + arch), then install it
sudo apt install ./pam-zta-gateway_0.1.0_amd64.deb # Ubuntu / Debian
sudo yum install ./pam-zta-gateway-0.1.0-1.x86_64.rpm # RHEL / Rocky / Fedora (dnf works too)
# 2) Point it at SQLite (no PostgreSQL) + set a CA token — edit /etc/pam-zta/gateway.toml:
# [database] driver = "sqlite" path = "/var/lib/pam-zta/gateway.db"
# [ca] token = "PASTE" # openssl rand -hex 32 — hand this token to the CA operator
sudo systemctl enable --now pam-zta-gateway
sudo journalctl -u pam-zta-gateway -f # watch for the root-enroll QR
# 3) Connect to this gateway:
# OSH client → http://SERVER:8443 (osh --gateway http://SERVER:8443)
# CA Signer → ws://SERVER:8443/v1/ca/ws + the [ca].token you set above
# HA / multi-node? Use PostgreSQL instead of SQLite ([database] host/user/... ).
desktop & ios — apps
# macOS — CA Signer (.dmg)
Open the .dmg ▸ drag "PAM-ZTA CA" to Applications ▸ open ▸ plug YubiKey ▸ enter PIN (PIV 9c) ▸ "Save PIN to Keychain".
# macOS — OSH Client (.pkg · all-in-one: GUI app + `osh` command)
Double-click OSH-1.1.0-arm64.pkg ▸ Install. # notarized · installs the OSH app + the `osh` CLI into PATH
osh connect dev@your-server # or open the OSH app and click Connect · (new terminal: run `rehash`)
# Windows — CA Signer / OSH Client (.exe · not yet code-signed)
Run the .exe ▸ on SmartScreen "Windows protected your PC" ▸ More info ▸ Run anyway.
# Ubuntu/Debian — CA Signer / OSH Client (.deb · amd64)
sudo apt install ./CA-0.1.0-amd64.deb # CA Signer (Operator Console)
sudo apt install ./OSH-0.1.0-amd64.deb # OSH Client
# iOS (OSH Approver)
1. Install TestFlight from the App Store.
2. Open the TestFlight link above ▸ Install OSH.
3. Open OSH ▸ scan the enrollment QR from the Gateway ▸ approve with Face ID.
using osh — enroll once, then connect
# 1) First time on a gateway: point osh at it, then enroll this device (an admin approves it once).
export OSH_GATEWAY=https://your-gateway:8443 # add to ~/.bashrc → skip --gateway every time
osh enroll --force # registers this device · an admin approves it in the App Signer
osh status # optional: expect status:ok, ca_connected:true
# 2) Log in — ONE command. The login user must MATCH an access rule (e.g. root — not just any name):
osh root@10.0.0.5 # short for: osh connect root@10.0.0.5
# • osh asks the Gateway for a certificate for root@10.0.0.5
# • your iPhone buzzes → review who / where / what → Approve with Face ID
# • the CA (YubiKey) signs a short-lived cert → you land in the SSH session ✅
# (session recorded to ~/.osh/sessions/ · cert expires in minutes · nothing static left behind)
# Rejected? 401 = device not enrolled on THIS gateway → re-run osh enroll --force
# 403 = device not approved yet, or the login user doesn't match a rule
🔐CA Signer requires a YubiKey (hardware-only, fail-closed). Pull the YubiKey and signing stops — exactly by zero-trust design.