Configuration

The main configuration file is:

1/etc/vaulthalla/config.yaml

Most operators should use CLI setup commands for lifecycle changes and edit config.yaml only for settings that are intentionally file-based.

Service Endpoints

Common sections:

1websocket_server:2  enabled: true3  host: 127.0.0.14  port: 369695 6http_preview_server:7  enabled: true8  host: 127.0.0.19  port: 36970

The web service itself is managed by vaulthalla-web.service and normally listens on localhost for Nginx proxying.

The S3-compatible gateway is a separate runtime service and is disabled by default:

1s3_gateway:2  enabled: false3  host: 0.0.0.04  port: 390005  require_sigv4: true6  allow_path_style: true7  allow_virtual_hosted_style: true8  multipart:9    min_part_size_mb: 510    abort_after_days: 711  synthetic_local_request_cost_usd:12    list: "0.00000001"13    head: "0.00000001"14    get: "0.00000001"15    put: "0.00000001"16    delete: "0.00000001"17    copy: "0.00000001"18    downloaded_gb: "0.00000000"19    uploaded_gb: "0.00000000"

See S3 Gateway Setup before enabling it on a network interface.

require_sigv4 should stay enabled outside development. When it is disabled, the gateway accepts a development-only auth context only if dev.enabled is true or the configured host is loopback. Production listeners should use real gateway credentials with explicit scope and normal Vaulthalla RBAC.

Clients can use the direct listener, or the managed Nginx dedicated S3 hostname:

1aws --endpoint-url http://127.0.0.1:39000 s3api list-buckets2aws configure set s3.addressing_style path3aws --endpoint-url https://s3.vaulthalla.example.com s3api list-buckets

The public S3 hostname is path-style reverse-proxy mode. SigV4 signs ordinary S3 paths such as /bucket/key; Nginx preserves the signed URI and marks the request as path-style-only so the router does not infer a bucket from the public host. s3_gateway.multipart.part_dir is no longer a valid setting; multipart parts use a Vaulthalla-owned hidden backing path with opaque per-upload directories.

synthetic_local_request_cost_usd is used only for S3 gateway credentials with local/cache budget enforcement enabled. It gives pure local buckets, metadata hits, cache hits, and sync-deferred gateway writes/deletes a nominal gateway-local cost for gateway_credential budgets without touching provider/vault/global upstream budgets.

Database

The database section controls PostgreSQL connection shape:

1database:2  host: localhost3  port: 54324  name: vaulthalla5  user: vaulthalla6  pool_size: 10

Use these setup commands rather than editing secrets directly:

1sudo vh setup db2sudo vh setup remote-db --host <host> --user <user> --database <name> --password-file <path>3vh secret set db-password /path/to/password-file

Authentication

Authentication settings include access-token and refresh-token lifetimes:

1auth:2  access_token_expiry_minutes: 153  refresh_token_expiry_days: 30

Changing token lifetimes affects web and API sessions. Use short access tokens and rotate secrets deliberately.

Sharing settings control whether share features and public links are enabled:

1sharing:2  enabled: true3  enable_public_links: true

Use Sharing for operational guidance.

Pricing And Storage Rates

Pricing configuration controls whether price-budget checks can estimate provider costs:

1pricing:2  enabled: true3 4storage_rates_api:5  remote_refresh_enabled: false6  fail_open: true

Remote refresh is opt-in. If you enforce price budgets, review catalog freshness policy and verification requirements in Price Budgets.

S3 gateway per-key budgets use the same price-budget service and pricing catalogs. Remote-backed gateway operations evaluate global, provider, vault, gateway credential, and gateway credential/vault policies before upstream-costing work. Local-only gateway buckets do not consume remote provider price budgets.

Sync Audit Retention

Sync event audit settings control how long sync event details are retained:

1sync:2  event_audit_retention_days: 303  event_audit_max_entries: 10000

Short retention reduces database growth but can remove useful sync troubleshooting context.

Stats Snapshots

Stats snapshot settings control dashboard trend collection:

1stats_snapshots:2  enabled: true3  runtime_interval_seconds: 604  vault_interval_seconds: 3005  retention_days: 30

Dashboard backup/recovery readiness indicators should be treated as policy/status signals, not proof that backup work has run.

Cache And Preview Settings

Cache and thumbnail settings affect web preview behavior and local cache size:

1caching:2  max_size_mb: 1024

If previews fail but downloads work, check preview service health, file type support, and cache capacity.

Operator Email

Operator email sections configure provider and recipients:

1email:2  enabled: true3  provider: resend4  from: "Vaulthalla <[email protected]>"5  base_url: "https://vault.example.com"6 7operator_emails:8  enabled: true

See Operator Emails.

Development Settings

Development settings are not production controls:

1dev:2  enabled: false

Do not enable development behavior on production hosts unless a maintainer-specific procedure requires it.