Environment variables

Configuration for deploying an instance of Agent Vault.

Server configuration

Variable	Required	Description
PORT	Optional (defaults to 14321)	The TCP port the server listens on. Overridden by --port.
DATABASE_URL	Optional (defaults to SQLite)	PostgreSQL connection URL for production deployments. When set, Agent Vault uses Postgres instead of the built-in SQLite database. All instances must share the same URL. Supports sslmode (e.g. ?sslmode=require). Example: postgres://user:password@host:5432/agentvault. Overridden by --database-url.
AGENT_VAULT_MASTER_PASSWORD	Recommended (passwordless mode if unset)	The master password used to derive the KEK that wraps the data encryption key. Source via your platform’s secret store (e.g., fly secrets set, Docker secrets); falls back to --password-stdin or an interactive prompt.
AGENT_VAULT_ADDR	Optional (auto-derived)	The externally-reachable base URL of the server (e.g., https://vault.example.com). Used for invite links, discovery responses, and MITM cert SANs. Falls back to https://<FLY_APP_NAME>.fly.dev on Fly.io, then http://{host}:{port}.
FLY_APP_NAME	Set by Fly.io	The Fly.io app name. Used to derive AGENT_VAULT_ADDR when unset.
AGENT_VAULT_ALLOW_PRIVATE_RANGES	Optional (defaults to false)	Whether the proxy may dial private/reserved IP ranges (RFC-1918, loopback, link-local, IPv6 ULA, CGN). Cloud metadata endpoints stay blocked either way.
AGENT_VAULT_NETWORK_ALLOWLIST	Optional	Comma-separated CIDRs or bare IPs the proxy may dial when AGENT_VAULT_ALLOW_PRIVATE_RANGES=false (e.g., 10.163.0.0/16,192.168.1.1).
AGENT_VAULT_TRUSTED_PROXIES	Optional	Comma-separated CIDRs of reverse proxies whose X-Forwarded-For headers are honored (e.g., 10.0.0.0/8,172.16.0.0/12).
AGENT_VAULT_LOG_LEVEL	Optional (defaults to info)	Log verbosity. One of: info, debug. debug adds one structured line per proxied request (no credential values). Overridden by --log-level.
AGENT_VAULT_RATELIMIT_PROFILE	Optional (defaults to default)	Rate-limit preset. One of: default, strict (≈0.5× the defaults), loose (≈2×), off.
AGENT_VAULT_RATELIMIT_LOCK	Optional (defaults to false)	Whether to make the rate-limit UI read-only and ignore UI overrides.
AGENT_VAULT_RATELIMIT_<TIER>_<KNOB>	Optional	Per-tier override. TIER is one of: AUTH, PROXY, AUTHED, GLOBAL. KNOB is one of: RATE (tokens/sec), BURST, WINDOW (e.g., 5m), MAX, CONCURRENCY. Always takes precedence over UI overrides.
AGENT_VAULT_LOGS_MAX_AGE_HOURS	Optional (defaults to 168)	Maximum age, in hours, of rows retained in the per-vault request log.
AGENT_VAULT_LOGS_MAX_ROWS_PER_VAULT	Optional (defaults to 10000)	Maximum number of rows retained per vault in the request log. Set to 0 to disable the row cap.
AGENT_VAULT_LOGS_RETENTION_LOCK	Optional (defaults to false)	Whether to ignore owner-UI overrides for log retention and pin to env values.
AGENT_VAULT_MAX_RESPONSE_BYTES	Optional (defaults to 0 = unlimited)	Maximum response body bytes the MITM proxy streams back to agents. Responses are streamed with a small buffer so unlimited is safe. When set and exceeded, the proxy returns 502 or aborts the connection. Overridden by --max-response-bytes.
AGENT_VAULT_MAX_REQUEST_BYTES	Optional (defaults to 1073741824 = 1 GiB)	Maximum request body bytes the MITM proxy forwards to upstreams. Requests exceeding this receive HTTP 413. Overridden by --max-request-bytes.
AGENT_VAULT_ISOLATION	Optional (defaults to host)	Default isolation mode for agent-vault vault run. One of: host, container (see Container isolation). Overridden by --isolation.
DB_MAX_OPEN_CONNS	Optional (defaults to 25)	Maximum number of open Postgres connections per instance. Only applies when DATABASE_URL is set. See connection pooling.
DB_MAX_IDLE_CONNS	Optional (defaults to 10)	Maximum number of idle Postgres connections kept in the pool per instance. Only applies when DATABASE_URL is set. See connection pooling.
DB_CONN_MAX_LIFETIME	Optional (defaults to 5m)	Maximum lifetime of a Postgres connection before it is closed and replaced. Go duration string (e.g. 5m, 1h). Only applies when DATABASE_URL is set. See connection pooling.

Email SMTP configuration

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

Variable	Required	Description
AGENT_VAULT_SMTP_HOST	Conditional (required to enable email)	The SMTP server hostname. If unset, email is disabled.
AGENT_VAULT_SMTP_PORT	Optional (defaults to 587)	The SMTP port. 465 for implicit TLS, 587 for STARTTLS.
AGENT_VAULT_SMTP_USERNAME	Conditional (if the SMTP server requires auth)	The SMTP authentication username.
AGENT_VAULT_SMTP_PASSWORD	Conditional (if the SMTP server requires auth)	The SMTP authentication password.
AGENT_VAULT_SMTP_FROM	Conditional (required if SMTP is enabled)	The sender email address.
AGENT_VAULT_SMTP_FROM_NAME	Optional (defaults to Agent Vault)	The display name used in the From header of outgoing emails.
AGENT_VAULT_SMTP_TLS_MODE	Optional (defaults to opportunistic)	TLS behavior on non-465 ports. One of: opportunistic, required, none. Port 465 always uses implicit TLS.
AGENT_VAULT_SMTP_TLS_SKIP_VERIFY	Optional (defaults to false)	Whether to skip TLS certificate verification. 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.

Infisical credential store

Setting INFISICAL_URL enables Infisical-backed vaults: Agent Vault polls Infisical and caches the encrypted snapshot locally. Local mutations are rejected. See Credential stores.

Supply env vars for one auth method. Detection picks the first complete group in priority order: Universal → Kubernetes → AWS IAM → GCP IAM → GCP ID Token → LDAP.

GCP IAM and GCP ID Token share INFISICAL_GCP_AUTH_IDENTITY_ID; setting INFISICAL_GCP_IAM_SERVICE_ACCOUNT_KEY_FILE_PATH alongside selects IAM, otherwise ID Token (which pulls a JWT from the GCP metadata server).

Variable	Required	Description
INFISICAL_URL	Required to enable	Base URL of the Infisical instance (e.g., https://app.infisical.com).
INFISICAL_UNIVERSAL_AUTH_CLIENT_ID	Conditional (Universal Auth)	Universal Auth machine identity client ID.
INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET	Conditional (Universal Auth)	Universal Auth machine identity client secret.
INFISICAL_KUBERNETES_IDENTITY_ID	Conditional (Kubernetes Auth)	Machine identity ID for Kubernetes-mounted service-account tokens.
INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH	Optional (Kubernetes Auth)	Override path to the projected token (default: SDK default).
INFISICAL_AWS_IAM_AUTH_IDENTITY_ID	Conditional (AWS IAM Auth)	Machine identity ID for AWS IAM auth.
INFISICAL_GCP_AUTH_IDENTITY_ID	Conditional (GCP IAM or GCP ID Token)	Machine identity ID; shared by both GCP flows.
INFISICAL_GCP_IAM_SERVICE_ACCOUNT_KEY_FILE_PATH	Conditional (GCP IAM only)	Path to the GCP service-account JSON key. Its presence selects GCP IAM over GCP ID Token.
INFISICAL_LDAP_AUTH_IDENTITY_ID	Conditional (LDAP Auth)	Machine identity ID for LDAP auth.
INFISICAL_LDAP_AUTH_USERNAME	Conditional (LDAP Auth)	LDAP bind username.
INFISICAL_LDAP_AUTH_PASSWORD	Conditional (LDAP Auth)	LDAP bind password.

The Infisical machine identity should have read-only access. Agent Vault never writes back, and a read-only identity caps blast radius if the broker is compromised.

Telemetry

Agent Vault collects anonymous usage telemetry to help improve the product. No credential values, request payloads, or secret data are ever included. Events capture command invocations and feature usage with the authenticated user’s email for company attribution.

Variable	Required	Description
AGENT_VAULT_TELEMETRY	Optional (defaults to true)	Set to false to disable anonymous usage telemetry. Also overridable with --telemetry=false on the CLI.