Skip to content

Configuration

Vein is configured with a single TOML file, vein.toml by default (override with --config). Generate a starter file with vein init, or copy vein.example.toml.

crates.io and npm work with defaults; add an [upstream] section only when you want Vein to fetch uncached RubyGems.

[server]
port = 8346 # default
[storage]
path = "./cache" # default
[server]
host = "0.0.0.0"
port = 8346
workers = 4 # Rama worker threads (default: CPU count)
[storage]
path = "./cache" # local filesystem storage for cached artifacts
[database]
url = "postgres://user:pass@db.internal/vein" # or set VEIN_DATABASE_URL
max_connections = 10 # default
[database.reliability.retry]
enabled = true # default: true
max_attempts = 5 # including the initial request, default: 5
initial_backoff_ms = 500 # default: 500
max_backoff_secs = 30 # default: 30
backoff_strategy = "exponential" # "exponential" | "fibonacci" | "constant"
[logging]
level = "info" # debug, info, warn, error
json = false # true for JSON-formatted logs
[hotcache]
# Six-field cron: "sec min hour day month weekday"
refresh_schedule = "0 0 * * * *" # every hour; "" disables automatic refresh
[hotcache.reliability.retry]
enabled = true
max_attempts = 3
initial_backoff_ms = 1000
max_backoff_secs = 2
backoff_strategy = "constant"
# Optional - RubyGems only. crates.io and npm use fixed upstreams.
# By default Vein runs in cache-only mode for RubyGems.
[upstream]
url = "https://rubygems.org"
fallback_urls = ["https://gems.coop"] # tried in order if primary is unreachable
timeout_secs = 30
connection_pool_size = 128
[upstream.reliability.retry]
enabled = true
max_attempts = 3
initial_backoff_ms = 100
max_backoff_secs = 2
backoff_strategy = "exponential"
# Supply chain protection - see /quarantine/
[delay_policy]
enabled = false
default_delay_days = 3
skip_weekends = true
business_hours_only = true
release_hour_utc = 9
[[delay_policy.packages]]
name = "rails*"
pattern = true
delay_days = 7
[[delay_policy.packages]]
registry = "crate" # "gem", "crate", or "npm"; every registry when left out
names = ["serde", "tokio"] # exact names under the same delay, no pattern matching
delay_days = 0
[[delay_policy.pinned]]
name = "rails"
version = "8.0.1"
reason = "Security patch - verified safe"

See Architecture for what the database and storage layers are each responsible for, and Deployment for Podman/systemd/Blackship examples that wire this file in.