Vygrant is a tool designed to manage OAuth2 tokens for legacy and CLI applications that lack modern authentication support. It acts as a local daemon and provides a CLI interface for securely handling token management.
Key features of Vygrant include:
Daemon + CLI functionality: Manage and refresh tokens through a local Unix socket.
Secure storage: Tokens are stored securely in memory, with optional persistence using the OS keyring or pass.
Auto-refresh and notifications: Background token refresh with support for notifications on Linux, macOS, and Windows.
Configuration flexibility: Set up accounts and options through a TOML configuration file.
Vygrant is ideal for developers and users maintaining legacy applications who need to integrate modern OAuth2 authentication without rewriting their application. It simplifies the process of managing tokens, ensuring secure storage and seamless refresh cycles.
Installation can be done via winget or other package managers depending on your system.
README
vygrant
OAuth2 Authentication Daemon for Legacy Applications
vygrant provides a local CLI and background daemon for managing OAuth2 tokens on legacy applications that lack modern authentication support.
Features
Daemon + CLI: Manage and refresh tokens through a local Unix socket.
Secure token handling: Tokens are stored securely in memory and optionally persisted.
Auto-refresh & notifications: Optional background token refresh with notification support on Linux/macOS/Windows.
Installation
Arch Linux
You can install vygrant from the AUR using an AUR helper like yay or paru:
yay -S vygrant
# or
paru -S vygrant
Else you can install it manually using git and makepkg:
git clone https://aur.archlinux.org/vygrant.git
cd vygrant
makepkg -si
Manual
git clone https://github.com/vybraan/vygrant.git
cd vygrant
go build -ldflags "-s -w"
Getting Started
1. Initialize Configuration
Create a default configuration file:
vygrant init
This generates a config at ~/.config/vybr/vygrant.toml. Open and edit the file to register your OAuth2 accounts:
https_listen: Port for HTTPS callbacks (default 8080).
http_listen: Port for HTTP callbacks (default disabled). Use this with redirect_uri = "http://localhost:" if your browser blocks the self-signed HTTPS callback.
persist_tokens: Whether to persist refresh tokens (default true). When enabled, vygrant prefers the OS keyring; access tokens stay in memory.
token_event_cmd: Optional shell command to run whenever tokens change (set/delete/restore). VYGRANT_ACCOUNT and are exported.
If a legacy ~/.vybr/vygrant/tokens.json exists and the keyring is available, vygrant migrates refresh tokens to the keyring on first run and renames the old file to tokens.json.bak.
If the keyring is unavailable but a legacy tokens.json exists, vygrant uses that file store with a warning (legacy compatibility).
If the keyring is unavailable and no legacy file exists, tokens are memory‑only and will be lost on daemon restart.
If the keyring is unavailable and pass is installed, vygrant uses pass as the refresh-token store (access tokens remain in memory).
Exporting and restoring tokens (advanced)
You can export the current token state and re-import it later:
The dump contains secrets; store it encrypted (e.g., age, gpg). When token_event_cmd is set, you can automate this export on changes.
You may use Thunderbird's OAuth2 client ID/secret for Microsoft accounts, but it's recommended to create your own credentials.
2. Start the Daemon
Ensure the config exists, then run:
vygrant server
The daemon will listen for OAuth2 callbacks and manage the tokens.
Trusting the local certificate (one-time)
Vygrant generates a local CA and a localhost certificate on first run. To avoid browser warnings for HTTPS callbacks, import and trust the CA certificate once:
Use the built-in command: vygrant trust (add --system for system trust where supported).
CA certificate path: ~/.vybr/vygrant/certs/vygrant_ca.pem
To remove trust later, run: vygrant untrust (add --system for system trust).
If you reinstall on another machine, a new CA is generated and should be trusted again.
3. Authenticate via CLI
Use the CLI to initiate authentication in your browser:
vygrant token refresh myapp
After approval in the browser, you'll see a friendly success page. You can then close the tab and vygrant handles everything in the background.
CLI Commands Overview
vygrant accounts - list all configured accounts.
vygrant status - display authentication status (valid, expired, missing).
vygrant info - show daemon config details (socket path, ports, etc.).
account example@hotmail.com
host smtp-mail.outlook.com
port 587
from example@hotmail.com
user example@hotmail.com
passwordeval "vygrant token get myapp"
auth on
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
tls_starttls
Alternatives
vygrant is very simple. You may also consider these
programs as alternatives: