Epithet is an SSH certificate authority that replaces static authorized_keys with short-lived certificates (2-10 minutes) and authentication over OIDC. It creates on-demand SSH agents for each outbound connection, enabling real-time policy enforcement with standard OpenSSH.
Very small right now, but we have a mailing list!
Install with Homebrew on Apple Silicon or Intel Macs:
brew install epithet-ssh/tap/epithetPackages are available for FreeBSD 15 on amd64. Run the following as root to install the repository signing key and configure the signed package repository:
install -d -m 0755 /usr/local/etc/pkg/keys /usr/local/etc/pkg/repos
fetch -o /usr/local/etc/pkg/keys/epithet.pub https://pkg.epithet.dev/keys/epithet.pub
chmod 0644 /usr/local/etc/pkg/keys/epithet.pub
cat > /usr/local/etc/pkg/repos/Epithet.conf <<'EOF'
Epithet: {
url: "https://pkg.epithet.dev/${ABI}/latest",
signature_type: "pubkey",
pubkey: "/usr/local/etc/pkg/keys/epithet.pub",
enabled: yes
}
EOF
pkg update -r Epithet
pkg install -r Epithet epithetKeep the literal ${ABI} in the repository URL. The package includes server
rc.d scripts, disabled by default; installation does not start a server.
Packages are available for x86_64. Import and trust the repository signing key:
curl -fsS --proto '=https' https://pkg.epithet.dev/keys/epithet-arch.asc | sudo pacman-key --add -
sudo pacman-key --lsign-key EDF8AFF765FBCD24AE3E2D0B1146870201C33C51Add the following to /etc/pacman.conf, keeping the literal $arch:
[epithet]
SigLevel = Required
Server = https://pkg.epithet.dev/arch/$archThen update the system and install Epithet:
sudo pacman -Syu epithetgit clone https://github.com/epithet-ssh/epithet.git
cd epithet
makeAdd the resulting epithet binary to your PATH.
1. Install Epithet.
2. Start the agent:
epithet agent --ca https://your-ca.example.com/The agent discovers its OIDC issuer and client ID from the CA's Link header on the root response — nothing to configure locally.
3. Tag the hosts this profile should handle, then include the generated config (~/.ssh/config):
Host *.example.com
Tag epithet
Include ~/.epithet/run/*/ssh-config.conf # must come after Tag lines4. SSH as normal:
ssh server.example.comFirst connection authenticates through your browser (~2-5 seconds). In an SSH session, Epithet automatically uses the OIDC device flow instead. Subsequent connections reuse the refreshed token.
To scope the agent to a shell or another command, pass that command to the agent. It starts only after the broker is ready, and the agent exits when the command exits:
epithet agent zshThe child uses the same generated ~/.ssh/config setup shown above. Use
--login-method browser or --login-method device to override automatic
login-method selection.
When you run ssh server.example.com, OpenSSH's Match tagged triggers epithet match for hosts you've tagged in your own ssh config. epithet match asks the broker for a certificate. The broker authenticates in-process via OIDC, requests a signed certificate from the CA (which checks policy in real time), and spins up a per-connection SSH agent with the short-lived certificate. See architecture for detailed sequence diagrams.
Components:
- Agent (
epithet agent): Daemon managing OIDC authentication state and certificate lifecycle. Creates per-connection SSH agents. - CA (
epithet ca): Authenticates users, reads facts, evaluates Writ, and signs SSH certificates. - Directory / Inventory (
epithet directory,epithet inventory): Independently replaceable user and host fact services. Backends own storage, mutation invariants, and audit. - Control (
epithet control): Control plan, handles administration, SCIM provisioning, and host enrollment.
- Directory and SCIM groups - identities, current group names, and database upgrades
- Fact Provider API - Implement a custom directory or inventory
- Destination-bound Principals - Interoperable principal derivation protocol
Requires OpenSSH 9.4+ on the client (for Tag/Match tagged; see below).
Apache 2.0