Environment Variables
One canonical prefix, two accepted fallbacks
The canonical prefix is VAGARIS_. Two earlier prefixes are still honoured on every read, in this order: the CLI looks for VAGARIS_<NAME> first, then VAGRIS_<NAME>, then PAPERCLIP_<NAME>. Setting the canonical spelling overrides a stale older value without deleting it, and an empty string counts as set. Existing installs that use an older spelling keep working; new configuration should use VAGARIS_.
The tables below name the suffix; prefix it with VAGARIS_ (or, for an existing setup, VAGRIS_ or PAPERCLIP_). Values shown as defaults are what the CLI uses when no spelling is set.
The instance signing secret follows the same rule under its own name: set VAGARIS_AGENT_JWT_SECRET. vagaris onboard writes it, together with the legacy PAPERCLIP_AGENT_JWT_SECRET line carrying the same value so an older binary restored by vagaris rollback still starts; an install that only has the legacy line keeps working, and vagaris doctor --repair adds the canonical one.
Locating state
| Suffix | Default | Read by |
|---|---|---|
HOME | ~/.vagris (or ~/.paperclip when it already holds instances/) | Every command — the CLI home |
INSTANCE_ID | default | Instance selection |
CONFIG | derived | Path to the instance config file |
CONTEXT | derived | Path to the context file |
--data-dir sets HOME (and derives INSTANCE_ID, CONFIG, CONTEXT) for one command.
Talking to a server
| Suffix | Default | Read by |
|---|---|---|
API_URL | inferred from config (http://localhost:<port>) | Client commands — API base |
API_KEY | none | Client commands — bearer token |
COMPANY_ID | none | Company-scoped commands |
SERVER_HOST | localhost | API base inference when API_URL is unset |
SERVER_PORT | config server.port, else 3100 | API base inference |
AGENT_ID | none | MCP server default agent |
RUN_ID | none | MCP server run attribution |
MCP_TOOL_MODE | full | MCP server: full, propose or allowlist |
MCP_TOOL_ALLOWLIST | none | MCP server: comma-separated tool names when mode is allowlist |
Instance and deployment settings
These seed vagaris onboard quickstart defaults and are printed by vagaris env. A plain onboard --yes forces trusted-local loopback and reports which of these it ignored.
| Suffix | Purpose |
|---|---|
DEPLOYMENT_MODE | local_trusted or authenticated |
DEPLOYMENT_EXPOSURE | private or public (authenticated mode only) |
BIND | loopback, lan, tailnet, custom |
BIND_HOST | Host for custom bind |
TAILNET_BIND_HOST | Tailscale address to bind when tailnet cannot be detected |
PUBLIC_URL | Public base URL; also used to print bootstrap invite links |
AUTH_PUBLIC_BASE_URL | Public base URL for auth (same role as PUBLIC_URL) |
AUTH_BASE_URL_MODE | auto or explicit |
AUTH_STORE | Auth store selection |
ALLOWED_HOSTNAMES | Comma-separated hostnames allowed in private mode (also vagaris allowed-hostname) |
AGENT_JWT_SECRET | Secret for agent tokens; generated into the instance .env when absent |
AGENT_JWT_TTL_SECONDS, AGENT_JWT_ISSUER, AGENT_JWT_AUDIENCE | Agent token parameters printed by vagaris env |
OPEN_ON_LISTEN | Open the browser when the server starts (onboard sets it to true when it starts the server) |
UI_DEV_MIDDLEWARE | Serve the UI through the dev middleware when starting from a source checkout |
Storage, secrets and backups
| Suffix | Purpose |
|---|---|
STORAGE_PROVIDER | local_disk or s3 |
STORAGE_LOCAL_DIR | Local-disk base directory |
STORAGE_S3_BUCKET, STORAGE_S3_REGION, STORAGE_S3_ENDPOINT, STORAGE_S3_PREFIX, STORAGE_S3_FORCE_PATH_STYLE | S3 settings |
SECRETS_PROVIDER | Secrets provider |
SECRETS_STRICT_MODE | Require secret references for sensitive values |
SECRETS_MASTER_KEY | Inline master key (32 bytes) |
SECRETS_MASTER_KEY_FILE | Path to the master key file |
SECRETS_AWS_REGION, SECRETS_AWS_KMS_KEY_ID, SECRETS_AWS_DEPLOYMENT_ID | AWS Secrets Manager settings |
DB_BACKUP_ENABLED, DB_BACKUP_INTERVAL_MINUTES, DB_BACKUP_RETENTION_DAYS, DB_BACKUP_DIR | Scheduled backup settings |
Governed execution
| Suffix | Purpose |
|---|---|
NATIVE_GOVERNOR | Selects the native governance chain used for governed spawns |
GOVERNOR_DIR | Directory of the governance chain scripts |
WORKTREES_DIR | Base directory for worktree:* dev instances |
WORKTREE_START_POINT | Default start point for worktree:make |
VAGRIS_SESSION_ENVELOPE is set by vagaris dev --agent|--native for the executor, not read from your environment. It keeps the VAGRIS_ spelling because that is the name the CLI emits and agent frontends read today.
Telemetry
| Variable | Effect |
|---|---|
VAGARIS_TELEMETRY_DISABLED=1 (older: VAGRIS_, PAPERCLIP_) | Disable telemetry |
VAGARIS_TELEMETRY_ENDPOINT (older: VAGRIS_, PAPERCLIP_) | Override the endpoint |
DO_NOT_TRACK=1 | Disable telemetry (standard convention) |
Telemetry is also off automatically in a CI environment and when the config has telemetry.enabled: false.
Unprefixed variables
| Variable | Purpose |
|---|---|
DATABASE_URL | External PostgreSQL; switches quickstart to postgres mode and is preferred by db:backup and auth bootstrap-ceo |
PORT, HOST, SERVE_UI | Server listen settings read at onboarding |
BETTER_AUTH_URL, BETTER_AUTH_BASE_URL | Alternative public base URL sources |
ANTHROPIC_API_KEY, OPENAI_API_KEY | Provider keys for adapters and executors (Model Providers) |
Server-side variables (what the server process reads, including the agent-runtime variables it injects into agent processes) are on Deploy → Environment Variables.