Runtime configuration management for the ov CLI. MUST be invoked before any work involving: ov settings commands, runtime configuration, engine selection, bind address, storage paths, or secret backend configuration.
Manage ov's runtime configuration stored in ~/.config/ov/settings.yml. Controls engine selection, networking, storage paths, secret backend, and agent forwarding.
| Action | Command | Description |
|---|---|---|
| Get a setting | ov settings get <key> | Show current value |
| Set a setting | ov settings set <key> <value> | Update a setting |
| List all | ov settings list | Show all settings with values |
| Reset to default | ov settings reset <key> | Remove override, use default |
| Config path | ov settings path |
| Print path to settings.yml |
| Migrate secrets | ov settings migrate-secrets [--dry-run] | Move plaintext credentials to keyring |
| Key | Default | Env Var | Description |
|---|---|---|---|
engine.build | docker | OV_ENGINE_BUILD | Build engine (docker/podman) |
engine.run | docker | OV_ENGINE_RUN | Run engine (docker/podman) |
run_mode | quadlet | OV_RUN_MODE | Deployment mode (quadlet/direct) |
bind_address | 127.0.0.1 | OV_BIND_ADDRESS | Default bind address for ports |
encrypted_storage_path | ~/.local/share/ov/encrypted | OV_ENCRYPTED_STORAGE_PATH | Base path for gocryptfs volumes |
volumes_path | ~/.local/share/ov/volumes | OV_VOLUMES_PATH | Base path for bind-mounted volumes |
secret_backend | auto | OV_SECRET_BACKEND | Credential backend (auto/keyring/kdbx/config) |
keyring_collection_label | (empty) | OV_KEYRING_COLLECTION_LABEL | Preferred Secret Service collection label. Empty = iterate naturally (default alias → listing order). Set to pin ov to a specific collection in multi-database setups (e.g. KeePassXC with multiple open databases). See /ov:enc for the full iteration order. |
forward_gpg_agent | true | OV_FORWARD_GPG_AGENT | Forward GPG agent into containers |
forward_ssh_agent | true | OV_FORWARD_SSH_AGENT | Forward SSH agent into containers |
secrets.kdbx_path | (none) | OV_KDBX_PATH | Path to KeePass .kdbx database |
secrets.kdbx_cache | true | OV_KDBX_CACHE | Cache kdbx password in kernel keyring |
secrets.kdbx_cache_timeout | 3600 | OV_KDBX_CACHE_TIMEOUT | Kernel keyring cache TTL (seconds) |
# Switch to podman for both build and run
ov settings set engine.build podman
ov settings set engine.run podman
# Check current engine
ov settings get engine.build
# Change volume storage to NAS
ov settings set volumes_path /mnt/nas/ov-volumes
# Change encrypted storage location
ov settings set encrypted_storage_path /mnt/encrypted/ov
# Force KeePass backend
ov settings set secret_backend kdbx
# Migrate plaintext secrets from settings.yml to keyring
ov settings migrate-secrets
# Preview migration without changes
ov settings migrate-secrets --dry-run
Settings resolve in this order: environment variable > settings.yml > default value.
/ov:config -- deployment configuration (uses settings)/ov:secrets -- credential management/ov:doctor -- diagnose settings and secret storage health/ov:enc -- encrypted volume paths