Getting Started with Vouch

Start using Vouch in under 5 minutes

Vouch replaces static developer secrets (SSH keys, AWS access keys, GitHub PATs) with short-lived credentials derived from a FIDO2/WebAuthn hardware key assertion. This guide walks you through installing the CLI, enrolling your YubiKey, and performing your first login.

Prerequisites

• A YubiKey 5 series (or any compatible FIDO2 security key)
• A Vouch server instance, such as https://us.vouch.sh

Organization ownership: The first person to log into Vouch from a Google Workspace domain automatically becomes the organization owner. The owner can configure integrations, manage team members, and connect services like GitHub and AWS for the rest of the team.

Step 1 – Install the CLI

macOS

Install with Homebrew:

brew install vouch-sh/tap/vouch

After installing, start the Vouch background service:

brew services start vouch

Debian / Ubuntu

# Import GPG key
curl -fsSL https://packages.vouch.sh/gpg/vouch.asc \
  | gpg --dearmor \
  | sudo tee /usr/share/keyrings/vouch-archive-keyring.gpg > /dev/null

# Add repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/vouch-archive-keyring.gpg] https://packages.vouch.sh/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/vouch.list > /dev/null

# Install
sudo apt-get update && sudo apt-get install -y vouch

Fedora / RHEL

sudo tee /etc/yum.repos.d/vouch.repo << 'EOF'
[vouch]
name=Vouch
baseurl=https://packages.vouch.sh/rpm/$basearch/
gpgcheck=1
gpgkey=https://packages.vouch.sh/gpg/vouch.asc
enabled=1
EOF

sudo dnf install -y vouch

Windows

Install with winget:

winget install SmokeTurner.Vouch

Note: Windows support is limited. The SSH agent and SSH integration are not available on Windows. Only basic authentication and credential exchange commands are supported: enroll, login, credential aws, and credential github.

Verify the installation

After installing, confirm the CLI is available:

vouch --version

Step 2 – Enroll your YubiKey

Enrollment registers your YubiKey with the Vouch server and links it to your identity. You only need to do this once per key.

vouch enroll --server https://us.vouch.sh

This command will:

1. Display a URL and a one-time code in your terminal (using the RFC 8628 Device Authorization Grant flow).
2. Open the URL in your browser (or you can navigate to it manually) and enter the one-time code.
3. Ask you to verify your identity through your organization’s SSO provider.
4. Prompt you to register your YubiKey as a FIDO2 credential.
5. Set a PIN on the YubiKey if one has not been configured already.
6. Save the server configuration locally so future commands know where to authenticate.

Once enrollment completes, the CLI prints a confirmation and you are ready to log in.

You can manage your enrolled security keys at any time from the Vouch dashboard:

Step 3 – Daily login

Each workday begins with a single vouch login. This authenticates you with your YubiKey and provisions short-lived credentials that last for 8 hours.

vouch login
Enter PIN: ****
Touch your YubiKey...
Authenticated for 8 hours

That is it. After login, every integration – SSH, AWS, Git – uses the session credentials automatically. When the 8-hour window expires, run vouch login again.

Step 4 – Use your first credential

With an active session, your tools work without extra wrappers. Try the integration your administrator has already configured:

# SSH just works
ssh user@server

# AWS credentials are available through the configured profile
aws sts get-caller-identity --profile vouch

# Git prompts Vouch's credential helper when needed
git ls-remote https://github.com/example/private-repo.git

Vouch provides credentials on demand to each tool through the lightweight integrations configured by your organization.

What just started working?

One YubiKey tap gives you credentials that cascade across your entire toolchain:

These tools read your AWS config, SSH config, Git credential helper, or Docker config – no additional wrapper commands are needed after setup.

Step 5 – Choose your next integration

Before a tool can use Vouch, your organization needs to configure the matching integration. Choose the guide that matches the credential you want to replace next.

Step 6 – Onboard your team

Once you have Vouch working for yourself, bring the rest of your team onboard.

Team enrollment

Each team member installs the CLI and enrolls with the same Vouch server. As long as they authenticate with the same Google Workspace domain, they automatically join your organization:

# Each team member runs:
brew install vouch-sh/tap/vouch
brew services start vouch
vouch enroll --server https://us.vouch.sh

No invite codes or admin approval are needed for enrollment. The first person to enroll from a domain becomes the organization owner; everyone else joins as a member.

Manual user management

For small teams (under 15 people), manual management works well. As organization owner, you can view and manage team members through the admin dashboard:

When someone leaves, remove them manually to revoke their access.

When to adopt SCIM

As your team grows, consider setting up SCIM provisioning to automate user lifecycle management. SCIM connects your identity provider (Google Workspace, Okta, Azure AD) to Vouch so that:

• New hires are provisioned automatically when added to your IdP.
• Departing employees are de-provisioned instantly when their IdP account is deactivated.
• You never forget to revoke someone’s access.

SCIM is recommended for teams of 15+ people, but can be set up at any team size.

What happens when you login

When you run vouch login, the following takes place behind the scenes:

1. FIDO2 assertion – The CLI asks your YubiKey to sign a challenge from the Vouch server. This proves possession of the enrolled key and requires both your PIN and a physical touch.
2. Identity verification – The server validates the signed assertion against the public key stored during enrollment.
3. Credential issuance – On success, the server issues a session token and an SSH certificate signed by the Vouch CA, valid for 8 hours.
4. On-demand credentials – AWS, Git, Docker, Cargo, and other credentials are obtained on-demand by their respective credential helpers when you use those tools. Each helper exchanges your active session for a short-lived, service-specific credential.
5. Local caching – The CLI stores the session and SSH certificate in memory (via the Vouch agent) so subsequent commands can use them without additional YubiKey interaction.

Because every credential is short-lived and bound to a hardware key, there are no long-lived secrets on disk that can be stolen or leaked.

Related guides

• AWS Integration – Federate into AWS with OIDC for temporary STS credentials.
• SSH Certificates – Connect to servers using short-lived SSH certificates.
• GitHub Integration – Access private repositories with short-lived tokens.
• Security Model – How Vouch protects credentials at every layer.
• FAQ – Common questions about supported hardware, session behavior, and platform support.