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
SettingINFISICAL_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. |