Configuration

The instance config

vagaris onboard writes one JSON file per instance. vagaris configure edits it section by section:

vagaris configure
vagaris configure --section server

Sections and what they hold:

Section	Keys
database	mode (embedded-postgres or postgres), connectionString, embeddedPostgresDataDir, embeddedPostgresPort (default 54329), backup (enabled, intervalMinutes, retentionDays, dir)
logging	mode (file), logDir
server	deploymentMode (local_trusted or authenticated), exposure (private or public), bind (loopback, lan, tailnet, custom), customBindHost, host, port (default 3100), allowedHostnames, serveUi
auth	baseUrlMode (auto or explicit), publicBaseUrl, disableSignUp
storage	provider (local_disk or s3), localDisk.baseDir, s3 (bucket, region, endpoint, prefix, forcePathStyle)
secrets	provider, strictMode, localEncrypted.keyFilePath
llm	provider (claude or openai) and apiKey — optional
telemetry	enabled

--section accepts llm, database, logging, server, storage, secrets. Without it, configure asks which section to edit and loops until you are done. If the file is invalid, configure loads defaults so you can repair it; onboard on an existing install keeps the file untouched and only ensures the generated secrets exist.

How the config file is found

For every command, in order:

1. --config <path>
2. VAGARIS_CONFIG (older spellings VAGRIS_CONFIG, PAPERCLIP_CONFIG are also read)
3. The nearest .vagris/config.json (or a pre-existing .paperclip/config.json) walking up from the current directory — this is what makes a repository-local instance work
4. <home>/instances/<instance>/config.json

<home> is VAGARIS_HOME if set, otherwise ~/.vagris (or ~/.paperclip when that already contains instances/). <instance> is VAGARIS_INSTANCE_ID, default default, or --instance <id> on vagaris run.

--data-dir <path> sets the home for the duration of the command and, on commands that accept --config/--context, derives those paths from it too — unless you passed them explicitly.

The .env beside the config

<instance>/.env is generated (mode 0600) and loaded before every command runs, without overriding variables already in your environment. It holds VAGARIS_AGENT_JWT_SECRET (plus a legacy PAPERCLIP_AGENT_JWT_SECRET line with the same value, for an older binary restored by vagaris rollback), created by onboard or repaired by doctor, and any deployment values configure writes. vagaris env prints the deployment variables the current config implies, marking each as set, default or missing and where it came from (environment, config, file, default).

Context profiles

~/.vagris/context.json (or VAGARIS_CONTEXT, or the nearest .vagris/context.json walking up) holds named profiles with apiBase, companyId, apiKeyEnvVarName and an optional link (organization, project, repository, branch). Managed by vagaris context set|show|list|use|link; see First Session.

Credential stores

File	Written by	Contents
~/.vagris/auth.json	vagaris auth login	Per-API-base credential metadata; tokens live in the OS keychain
~/.vagris/node-identity.json	vagaris node enroll	Machine fingerprint and Ed25519 key pair (mode 0600)
~/.vagris/update-history.json	vagaris update / vagaris rollback	previousVersion, lastUpdatedAt, lastUpdatedTo

Instance directories

Under <home>/instances/<instance>/:

Directory	Contents	Retention
db/	Embedded PostgreSQL data	Managed by PostgreSQL; usage reported
logs/	Server logs	Pruned by age (7 days) and size (100 MB)
data/storage/	Uploaded assets referenced by the database	Reported against a cap, never pruned
data/backups/	Database backups from the scheduler and vagaris db:backup	Pruned by age and size (500 MB)
secrets/master.key	Local encryption key for secrets	Kept
telemetry/	One small state file	Kept

Take a one-off backup with:

vagaris db:backup --dir ./backups --retention-days 14 --filename-prefix vagaris --json

db:backup uses DATABASE_URL if set, otherwise the config's connection string or the embedded database, and prunes the output directory to the retention window.

Routines

vagaris routines disable-all --company-id <company-id> pauses every non-archived routine for a company in the configured local instance — useful before a migration or a restore.

Precedence summary

Flag → environment variable (VAGARIS_*, then VAGRIS_*, then PAPERCLIP_*) → context profile → config file → built-in default. Environment Variables lists every variable the CLI reads.