# Frequently Asked Questions > Common questions about Vouch — supported hardware, session behavior, platform support, and cost. Source: https://vouch.sh/docs/faq/ Last updated: 2026-09-03 --- ## Hardware keys ### Which YubiKeys are supported? Any **FIDO2-compatible** security key works with Vouch. Recommended models: - **YubiKey 5 series** (5 NFC, 5C, 5C NFC, 5Ci, 5C Nano, 5 Nano) -- Recommended. Supports FIDO2, USB-A or USB-C. - **YubiKey 5 FIPS series** -- Same as above, with FIPS 140-2 validation. - **YubiKey Bio** -- Supports FIDO2 with fingerprint biometrics instead of PIN. - **Security Key by Yubico** (NFC or C NFC) -- Budget option. Supports FIDO2 but lacks other YubiKey features (PIV, OpenPGP). Other FIDO2-compliant keys (e.g., Google Titan, Feitian, SoloKeys) may work but have not been tested. The key must support the `hmac-secret` extension and resident credentials. ### What happens if I lose my YubiKey? 1. **Report it immediately** to your organization administrator so they can remove the key from your account. 2. Your active session (if any) continues until it expires (up to 8 hours), but no new sessions can be created with the lost key. 3. If you have a backup key already enrolled, use it to log in while you replace the lost one. It also unlocks re-enrollment: registering a replacement key asks for a tap from a key that is already on file. 4. If the lost key was your only key, re-enrollment is blocked until your administrator removes it from your account — enrolling requires a tap from an already-registered key whenever one is on file. Once the lost key is removed, run `vouch enroll` to register the replacement. ### Can I enroll multiple YubiKeys? Yes. Run `vouch enroll` with each key. Enrolling an additional key asks for a WebAuthn assertion with a key that is already registered, so have your existing key ready to tap. A backup key is recommended in case one is lost or damaged — all enrolled keys can be used interchangeably for `vouch login`. ### Can I restrict which YubiKey models are accepted? Yes. The Vouch server supports AAGUID-based policies that control which authenticator models are accepted during enrollment and login. Set the `VOUCH_ALLOWED_AAGUIDS` environment variable on the server: - **`fips-only`** — Only FIPS-certified YubiKey models are accepted. - **`yubikey-5`** — Any YubiKey 5 series model is accepted. - **Comma-separated UUIDs** — An explicit allowlist of authenticator AAGUIDs (e.g., `cb69481e-8ff7-4039-93ec-0a2729a154a8,ee882879-721c-4913-9775-3dfcce97072a`). - **Unset or empty** — No model restriction; any key that passes attestation verification is accepted (default). Independent of the model policy, every registration requires a full attestation certificate chain; self-attestation is rejected. The server validates the chain against pinned [Yubico root CA certificates](https://developers.yubico.com/PKI/), cryptographically proving the key is a genuine Yubico device, and reads the key model (AAGUID) from the verified certificate rather than from client-supplied data. Platform authenticators and software-based keys cannot chain to the Yubico roots and are rejected. ### Can I use the same YubiKey across multiple Vouch organizations? Yes. A single YubiKey can hold multiple FIDO2 credentials. Enroll the key with each organization's Vouch server and it will work with all of them. --- ## Sessions and credentials ### How long does a session last? Sessions last **8 hours** from the time you run `vouch login`. After 8 hours, the session expires and you need to log in again. There is no way to extend a session -- you must re-authenticate with your YubiKey. ### How long do AWS credentials last? AWS STS credentials obtained through Vouch are valid for up to **1 hour**. The Vouch agent caches them, and when they expire, a new set is fetched automatically (as long as your session is active). You do not need to take any action. ### What happens when my session expires mid-task? - **SSH connections** already established continue to work. New connections will fail. - **AWS commands** fail with a credential error. Run `vouch login` and retry. - **Git operations** fail if they require authentication. Run `vouch login` and retry. - **Long-running processes** (e.g., `terraform apply`, `cdk deploy`) that started with valid credentials will continue until they need to refresh credentials. If a refresh fails mid-operation, the process may fail partially. ### Are credentials written to disk? No. All credentials are held in the Vouch agent's process memory. The session token, SSH certificate, and cached STS credentials are never written to a file. If the agent process stops, all credentials are lost. ### Does Vouch work with `aws-vault`? Vouch replaces the need for `aws-vault`. Both tools solve the same problem (avoiding static AWS credentials), but they work differently. You should use one or the other, not both. If you are currently using `aws-vault`, see the [Migration Guide](/docs/migration/) for switching to Vouch. --- ## Platform support ### Does Vouch work on Windows? Windows support is limited. The following commands work on Windows: - `vouch enroll` - `vouch login` - `vouch credential aws` - `vouch credential github` The SSH agent and SSH certificate integration are **not available** on Windows. The background agent service is also not available -- credentials are obtained directly by each command invocation. ### Does Vouch work on Linux? Yes. Vouch supports Debian/Ubuntu (APT) and Fedora/RHEL (DNF). The agent runs as a systemd user service. See [Getting Started](/docs/getting-started/) for installation instructions. ### Does Vouch work in WSL? WSL (Windows Subsystem for Linux) works the same as native Linux. Install the Linux version of the CLI and use USB passthrough for YubiKey access. ### Does Vouch work in containers? Vouch is designed for developer workstations, not containers. For containers in CI/CD pipelines, use the pipeline's native credential mechanism (e.g., GitHub Actions OIDC, IAM roles for ECS tasks). See [CI/CD Integration](/docs/cicd/) for human approval gates. --- ## AWS ### Does Vouch use AWS STS? Is there a cost? Yes, Vouch calls [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) to obtain temporary credentials. **AWS STS is free** -- there is no charge for STS API calls. ### What appears in CloudTrail? Every API call made with Vouch credentials appears in CloudTrail with the assumed role session name set to the developer's email address: ``` arn:aws:sts::123456789012:assumed-role/VouchDeveloper/alice@example.com ``` This provides full per-user attribution for AWS API activity. ### Can I use Vouch with multiple AWS accounts? Yes. See [Multi-Account AWS Strategy](/docs/aws-multi-account/) for deployment patterns using CloudFormation StackSets or Terraform modules. ### Does Vouch support AWS GovCloud? Vouch supports standard and China partitions. GovCloud support depends on the integration -- check the specific integration documentation page for cross-partition details. The CLI validates that your configured region's partition matches the role ARN before calling STS, so a mismatch fails early with a clear error. --- ## Identity and access ### Which identity providers does Vouch support? Vouch authenticates users through your organization's OIDC or SAML 2.0 identity provider. It has been tested with **Google Workspace** and **Microsoft Entra ID** (see [SAML](/docs/saml/)). For automated user provisioning (SCIM), Vouch works with Google Workspace, Okta, Azure AD (Entra ID), and OneLogin. ### What happens when someone leaves the company? Deactivate them in your identity provider ([SCIM](/docs/scim/) revokes their Vouch sessions automatically; without SCIM, an admin removes them from the dashboard) and outstanding short-lived credentials expire on their own. The full sequence and expiry timeline is in [When someone leaves](/docs/rollout/#when-someone-leaves). ### Can I restrict which team members can assume specific AWS roles? Yes. Use IAM trust policy conditions to restrict role assumption by email address or domain. See [Restricting access](/docs/aws/#tips-for-restricting-access) in the AWS documentation. --- ## Security ### Is Vouch open source? Yes. Vouch is fully open source under the Apache-2.0 / MIT dual license. ### What data does the Vouch server store? The server stores enrolled FIDO2 public keys, user metadata (email, organization membership), and audit logs. It does not store AWS credentials, SSH private keys, GitHub tokens, or any other secrets. See [Security](/docs/security/) for details. ### What happens if the Vouch server is compromised? An attacker with server access could issue sessions for any enrolled user, which could be used to broker credentials from external services (AWS, GitHub, etc.). However, the server does not store any credentials itself -- there is no credential vault to extract. See the [threat model](/docs/security/#threat-model) for the full analysis. ### Are credentials encrypted in transit? Yes. All communication between the CLI and server uses TLS 1.3, with TLS 1.2 accepted using AEAD ciphers only. See [Security](/docs/security/#encryption) for details. --- ## Updating Vouch ### How do I update the Vouch CLI? Update using the same package manager you used to install: - **macOS:** `brew upgrade vouch-sh/tap/vouch && brew services restart vouch` - **Debian/Ubuntu:** `sudo apt update && sudo apt upgrade vouch` - **Fedora/RHEL:** `sudo dnf upgrade vouch` - **Windows:** `winget upgrade SmokeTurner.Vouch` After upgrading, restart the agent so the new version takes effect. Check your version with `vouch --version`. ### Do I need to re-enroll after updating? No. Enrollment is stored on the server and on your YubiKey. Updating the CLI does not affect your enrollment or active sessions. --- ## Network configuration ### Does Vouch work behind a corporate proxy? Vouch respects the standard `HTTPS_PROXY` and `NO_PROXY` environment variables. If your network requires an HTTPS proxy, set these before running Vouch commands: ```bash export HTTPS_PROXY=http://proxy.corp.example.com:8080 export NO_PROXY=localhost,127.0.0.1 ``` The Vouch agent inherits proxy settings from the environment it was started in. If you change proxy settings, restart the agent. ### Does Vouch work over a VPN? Yes. Vouch connects to the Vouch server over HTTPS (port 443). As long as your VPN allows outbound HTTPS traffic to `us.vouch.sh`, Vouch works normally. If your VPN uses split tunneling, ensure the Vouch server is routable. If you experience connection timeouts after connecting to a VPN, restart the Vouch agent. ### What firewall rules does Vouch need? Vouch requires outbound HTTPS (port 443) to the Vouch server (`us.vouch.sh`). No inbound ports are required. If your firewall performs TLS inspection, ensure it does not interfere with the FIDO2 WebAuthn flow during enrollment and login. --- ## Diagnostics ### What does `vouch doctor` check? `vouch doctor` checks the agent, your session, and every integration's configuration (SSH, AWS, Git, Docker, Cargo, EKS, SSM), reporting **OK**, **WARNING**, or **ERROR** with a fix for each. Run it as a first step when something is not working. The full check list is in the [CLI reference](/docs/cli-reference/#diagnostics). --- ## Troubleshooting ### "Error: agent not running" Start the Vouch agent: - **macOS:** `brew services start vouch` - **Linux:** `systemctl --user start vouch` ### "Error: no active session" Run `vouch login` and authenticate with your YubiKey. ### "Error: credential_process returned error" Check that your Vouch session is active and the agent is running (`vouch status`). Run `vouch login` to re-authenticate. ### Where can I get help? - **Documentation:** [vouch.sh/docs](/docs/) - **GitHub Issues:** [github.com/vouch-sh/vouch/issues](https://github.com/vouch-sh/vouch/issues) - **Security issues:** Email security@vouch.sh