Environment variables

All environment variables used to configure Agent Vault

Server configuration

Variable	Default	Description
PORT	14321	Server listen port. Respected by most PaaS platforms (Fly.io, Cloud Run, Heroku). The --port flag takes precedence when set.
AGENT_VAULT_MASTER_PASSWORD	(unset)	Derives a KEK (Key Encryption Key) via Argon2id that wraps the data encryption key (DEK). If omitted, the DEK is stored unwrapped (passwordless mode). Read at startup, then immediately unset from the process.
AGENT_VAULT_ADDR	(auto)	Externally-reachable base URL. Used for generating links in emails, invites, and discovery responses. Falls back to https://<FLY_APP_NAME>.fly.dev on Fly.io, then http://{host}:{port}.
FLY_APP_NAME	(set by Fly.io)	When AGENT_VAULT_ADDR is unset and this variable is present, the base URL is automatically derived as https://<FLY_APP_NAME>.fly.dev. Set automatically by the Fly.io platform — you should not need to set this manually.
AGENT_VAULT_NETWORK_MODE	public	Proxy network restriction mode. public blocks connections to private/reserved IP ranges (RFC-1918, link-local, cloud metadata). private allows all outbound connections including private ranges — use this for local/private deployments where the proxy needs to reach internal services.
AGENT_VAULT_TRUSTED_PROXIES	(unset)	Comma-separated CIDR ranges of trusted reverse proxies (e.g. 10.0.0.0/8,172.16.0.0/12). When set, X-Forwarded-For is only trusted if the direct connection comes from a listed proxy. Used for rate limiting and audit logging behind a load balancer.
AGENT_VAULT_LOG_LEVEL	info	Log level for the server. info (default) keeps startup banners and warnings only. debug adds one structured line per proxied request (ingress path, method, host, path, matched service, injected credential key names, upstream status, duration). Credential values are never logged. The --log-level flag takes precedence when set.
AGENT_VAULT_RATELIMIT_PROFILE	default	Rate-limit profile: default, strict (≈0.5× the defaults), loose (≈2×), or off (disable all limits). Affects every tier — anonymous auth, token-redeem, proxy, authenticated CRUD, global in-flight. Owners can override per-tier in Manage Instance → Settings → Rate Limiting unless AGENT_VAULT_RATELIMIT_LOCK=true.
AGENT_VAULT_RATELIMIT_LOCK	false	When true, the rate-limit UI in Manage Instance is read-only and UI overrides are ignored. Use on PaaS deployments (Fly.io, Cloud Run) when the operator wants limits pinned to env vars.
AGENT_VAULT_RATELIMIT_<TIER>_<KNOB>	—	Fine-grained per-tier overrides. TIER is one of AUTH (unauthenticated endpoints), PROXY (proxy + MITM), AUTHED (everything behind requireAuth), GLOBAL (server-wide backstop). KNOB is one of RATE (tokens/sec), BURST (bucket depth), WINDOW (duration like 5m), MAX (sliding-window event cap), CONCURRENCY (semaphore slots). Env-set knobs always take precedence over UI overrides.
AGENT_VAULT_LOGS_MAX_AGE_HOURS	168	Retention for the per-vault request log (surfaced in Vault → Logs). Rows older than this many hours are trimmed by a background job every 15 minutes. Only secret-free metadata is stored (method, host, path, status, latency, matched service, credential key names) — never bodies or query strings.
AGENT_VAULT_LOGS_MAX_ROWS_PER_VAULT	10000	Per-vault row cap for the request log. Whichever limit (age or rows) hits first wins, so heavy-traffic vaults retain a shorter window than the time-based TTL alone would suggest. Set to 0 to disable the row cap.
AGENT_VAULT_LOGS_RETENTION_LOCK	false	When true, any owner-UI overrides for log retention are ignored and env values (or defaults) are pinned. Use when you want retention limits controlled only by the operator.
AGENT_VAULT_SANDBOX	process	Default sandbox mode for agent-vault vault run. process forks the child with HTTPS_PROXY envvars (cooperative). container launches it inside a Docker container with iptables-locked egress (non-cooperative; see Container sandbox). The --sandbox flag overrides this.

Master password resolution order:

1. AGENT_VAULT_MASTER_PASSWORD environment variable
2. --password-stdin flag
3. Interactive prompt

Never put AGENT_VAULT_MASTER_PASSWORD in Dockerfiles, committed .env files, or shell history. Use secret management features of your deployment platform (e.g., fly secrets set, Docker secrets, or your CI/CD provider’s secret store).

Installer

Read by install.sh only — not by the server or the CLI binary.

Variable	Default	Description
AGENT_VAULT_NO_TELEMETRY	(unset)	When set to any non-empty value, skips the anonymous install/upgrade beacon that reports OS, architecture, and version. Must be placed in front of sh, not curl: curl -fsSL https://get.agent-vault.dev | AGENT_VAULT_NO_TELEMETRY=1 sh.

Email SMTP configuration

Configure SMTP to enable Agent Vault to send emails for verification codes, vault invites, and notifications.

Variable	Default	Description
AGENT_VAULT_SMTP_HOST	(unset)	SMTP server hostname. If unset, email notifications are disabled.
AGENT_VAULT_SMTP_PORT	587	SMTP port. Use 465 for implicit TLS, 587 for STARTTLS.
AGENT_VAULT_SMTP_USERNAME	(unset)	SMTP authentication username.
AGENT_VAULT_SMTP_PASSWORD	(unset)	SMTP authentication password.
AGENT_VAULT_SMTP_FROM	(unset)	Sender email address. Required if SMTP is enabled.
AGENT_VAULT_SMTP_FROM_NAME	Agent Vault	Display name used in the From header of outgoing emails.
AGENT_VAULT_SMTP_TLS_MODE	opportunistic	TLS behavior for non-465 ports: opportunistic (try STARTTLS, fall back to plain), required (STARTTLS must succeed), none (skip STARTTLS). Port 465 always uses implicit TLS.
AGENT_VAULT_SMTP_TLS_SKIP_VERIFY	false	Skip TLS certificate verification. Set to true or 1 to enable. Useful for self-signed certificates in development.

To verify SMTP is working, run agent-vault email test. It sends a test email to the owner’s address. See the Configure Email SMTP guide for step-by-step setup instructions for popular providers like SendGrid, AWS SES, Resend, and more.

OAuth configuration

When both variables for a provider are set, the corresponding “Continue with …” button appears on login and registration pages. If either is unset, the provider is disabled.

Variable	Default	Description
AGENT_VAULT_OAUTH_GOOGLE_CLIENT_ID	(unset)	Google OAuth 2.0 Client ID. Obtain from Google Cloud Console.
AGENT_VAULT_OAUTH_GOOGLE_CLIENT_SECRET	(unset)	Google OAuth 2.0 Client Secret.

The callback URL configured in Google Cloud Console must be {AGENT_VAULT_ADDR}/v1/auth/oauth/google/callback.

See the Configure Google SSO guide for step-by-step setup instructions.

Agent runtime variables

These variables are set automatically by agent-vault vault run on the agent’s environment. You do not need to set them manually.

Variable	Description
AGENT_VAULT_ADDR	Server base URL (e.g., http://127.0.0.1:14321)
AGENT_VAULT_SESSION_TOKEN	Bearer token for authenticating with the proxy, scoped to the vault
AGENT_VAULT_VAULT	Name of the vault the session is scoped to

Agents use these to discover available services (GET {AGENT_VAULT_ADDR}/discover) and route authenticated requests through the proxy ({AGENT_VAULT_ADDR}/proxy/{host}/{path}).