rosec — Configuration Reference
Config file: $XDG_CONFIG_HOME/rosec/config.toml (default: ~/.config/rosec/config.toml)
[service]
Controls vault caching and deduplication behaviour.
| Key | Type | Default | Description |
|---|---|---|---|
dedup_strategy | string | "newest" | How to resolve duplicate items across providers. See Deduplication. |
dedup_time_fallback | string | "created" | Timestamp field used when dedup_strategy = "newest". "created" or "none". |
refresh_interval_secs | integer | 60 | How often (seconds) to re-sync each provider. Set to 0 to disable periodic refresh. |
ssh_fuse | bool | true | Mount the SSH FUSE filesystem at $XDG_RUNTIME_DIR/rosec/ssh/. Set to false to disable. See ssh-agent.md. |
totp_fuse | bool | true | Mount the TOTP FUSE filesystem at $XDG_RUNTIME_DIR/rosec/totp/. Set to false to disable. |
Deduplication
When multiple providers return an item with the same label or attributes, rosec
picks one winner according to dedup_strategy:
| Value | Behaviour |
|---|---|
"newest" | Keep the item with the most recent modification time. Falls back to dedup_time_fallback if modification time is unavailable. |
"priority" | Keep the item from the provider listed first in config.toml. |
"none" | Expose all copies; clients see duplicates. |
[autolock]
Controls when the daemon locks providers automatically. These are global
defaults — individual providers can override any field via
[provider.autolock] (see below).
The defaults mirror KWallet/GNOME Keyring behaviour: providers stay unlocked for the session duration and lock only on logout.
| Key | Type | Default | Description |
|---|---|---|---|
on_logout | bool | true | Lock when the user session ends (logind SessionRemoved). |
on_session_lock | bool | false | Lock when the screen is locked (logind Lock signal). |
idle_timeout_minutes | integer or omitted | (none) | Lock after this many minutes of D-Bus inactivity. Omit or set to 0 to disable. |
max_unlocked_minutes | integer or omitted | (none) | Hard upper limit on how long a provider stays unlocked. Omit or set to 0 to disable. |
Note:
PrepareForSleep(suspend/hibernate) always locks all providers regardless of config — this is not configurable.
[prompt]
Controls the unlock prompt shown when a secret is requested and the vault is locked.
| Key | Type | Default | Description |
|---|---|---|---|
backend | string | "builtin" | "builtin" uses the bundled rosec-prompt GUI. Any other value is treated as a path to an external prompter binary. |
args | array of strings | [] | Arguments passed to an external prompter. Supports template placeholders. |
External prompter
When backend is a binary path, rosec spawns it as a subprocess, passes the
prompt request via stdin as JSON, and reads the response from stdout.
Template placeholders in args:
| Placeholder | Value |
|---|---|
{{title}} | Prompt window title |
{{message}} | Human-readable description |
{{hint}} | Short context hint (e.g. provider name) |
{{backend}} | Provider ID (template variable name kept for back-compat with custom prompters) |
Example:
[prompt]
backend = "/usr/bin/my-prompter"
args = [
"--title={{title}}",
"--message={{message}}",
"--hint=Backend: {{backend}}",
]
[prompt.theme]
Theming for the built-in rosec-prompt GUI. All color values accept #RRGGBBAA
or #RRGGBB hex format (alpha defaults to ff if omitted).
| Field | Short alias(es) | Default | Description |
|---|---|---|---|
background | bg | #1e1e2eff | Window background |
foreground | fg | #cdd6f4ff | Primary text |
label_color | lc | #a6adc8ff | Secondary / hint text |
accent_color | ac | #7aa2f7ff | Accent color (focus rings, highlights) |
input_background | ibg | #181825ff | Password field background |
input_text | it | #cdd6f4ff | Password field text |
border_color | bd, bdr | #89b4faff | Window border |
border_width | bw | 2 | Border width in pixels |
font_family | font | "monospace" | Font family name |
font_size | size | 14 | Font size in pixels |
confirm_background | ybg | (accent) | Unlock button background (empty = use accent) |
confirm_text | yt | (foreground) | Unlock button text (empty = use foreground) |
cancel_background | nbg | (accent) | Cancel button background (empty = use accent) |
cancel_text | nt | (foreground) | Cancel button text (empty = use foreground) |
Example (Catppuccin Mocha palette):
[prompt.theme]
bg = "#1e1e2ecc"
fg = "#cdd6f4ff"
lc = "#a6adc8ff"
ac = "#7aa2f7ff"
ibg = "#181825ff"
it = "#cdd6f4ff"
bd = "#89b4faff"
bw = 2
font = "monospace"
size = 14
[[provider]]
Each [[provider]] section registers one secrets source. Multiple providers can
be listed; items are deduplicated across them (see Deduplication).
| Key | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique identifier for this provider. Used in D-Bus paths and CLI commands. |
kind | string | yes | Provider type. Currently: "local", "bitwarden", "bitwarden-sm", "gnome-keyring", "keepassxc-file". |
path | string | sometimes | Path to the on-disk file backing this provider. Required for local (vault file) and keepassxc-file (kdbx file). ~/ is expanded to $HOME. |
collection | string | no | Stamp a collection attribute onto every item from this provider. Useful for grouping in multi-provider setups. |
return_attr | array of strings | no | Ordered list of glob patterns selecting which sensitive attribute to return via GetSecret. First match wins. Default: ["password", "number", "private_key", "notes"]. |
match_attr | array of strings | no | Glob patterns controlling which attributes participate in SearchItems filtering. Reserved for future use. |
tls_mode | string | no | TLS certificate verification for plugin HTTP requests. "bundled" (default): Mozilla root certs only. "system": use the OS trust store (for self-signed / private CA certs). |
tls_mode_probe | string | no | TLS certificate verification for readiness probes. Inherits from tls_mode if not set. "disabled": skip TLS verification. "system": OS trust store. "bundled": Mozilla root certs. |
offline_cache | bool | no | Enable encrypted offline cache export/restore for providers that declare the OfflineCache capability. Default: true. |
unlock_timeout_secs | integer | no | Maximum seconds to wait for this provider's unlock (readiness probes + authentication) during the parallel multi-provider unlock flow. If exceeded, the attempt is cancelled without blocking other providers. Default: 30. |
[provider.autolock] — Per-provider autolock overrides
Each provider can have its own [provider.autolock] sub-table. Fields not
specified inherit from the global [autolock] section. This lets you, for
example, keep a work provider locked more aggressively while leaving your
personal provider unlocked for the session.
| Key | Type | Default | Description |
|---|---|---|---|
on_logout | bool | (inherit) | Override the global on_logout for this provider. |
on_session_lock | bool | (inherit) | Override the global on_session_lock for this provider. |
idle_timeout_minutes | integer | (inherit) | Override the global idle timeout. 0 explicitly disables. |
max_unlocked_minutes | integer | (inherit) | Override the global max-unlocked timeout. 0 explicitly disables. |
Example:
[[provider]]
id = "work"
kind = "bitwarden"
[provider.options]
email = "work@example.com"
[provider.autolock]
idle_timeout_minutes = 5
on_session_lock = true
[provider.options] — Local vault (kind = "local")
| Key | Required | Description |
|---|---|---|
path | no | Vault file path. Defaults to ~/.local/share/rosec/providers/<id>.vault. May also be set as the top-level path field on [[provider]]. |
See providers/local.md.
[provider.options] — Bitwarden Personal Vault (kind = "bitwarden")
| Key | Required | Description |
|---|---|---|
email | yes | Bitwarden account email address. |
base_url | no | Server URL. Omit for official US cloud (https://vault.bitwarden.com). Set to your Vaultwarden instance for self-hosted. |
[provider.options] — Bitwarden Secrets Manager (kind = "bitwarden-sm")
Available when the bitwarden-sm feature is compiled in.
| Key | Required | Description |
|---|---|---|
access_token | yes | Machine account access token from the SM web vault. |
organization_id | yes | Organization UUID. |
server_url | no | SM API base URL. Omit for official cloud. |
[provider.options] — GNOME Keyring (kind = "gnome-keyring")
Read-only access to existing ~/.local/share/keyrings/*.keyring files. No required options; the plugin scans the standard keyring directory at unlock time.
[provider.options] — KeePassXC file (kind = "keepassxc-file") — experimental
Reads a KeePassXC .kdbx (KDBX 4) directly from disk. Read-only. See providers/keepassxc-file.md for a full setup guide including TOTP and SSH key conventions.
| Key | Required | Description |
|---|---|---|
path | yes | Absolute or ~/-prefixed path to the .kdbx database. |
key_file | no | Path to a key file used as a second factor. When set, master password becomes optional (KeePassXC permits key-file-only authentication). |
Legacy [[vault]] and [[backend]] sections
Earlier rosec releases used [[vault]] for local encrypted vaults and [[backend]] for remote sources. These names are no longer recognised — the only section the daemon parses is [[provider]]. If you have an old configuration, replace [[backend]] with [[provider]], [[vault]] with [[provider]] kind = "local", and rename type = to kind = .
Full example
[service]
dedup_strategy = "newest"
dedup_time_fallback = "created"
refresh_interval_secs = 60
ssh_fuse = true
totp_fuse = true
# Global defaults — providers stay unlocked for the session, lock on logout.
[autolock]
on_logout = true
on_session_lock = false
# idle_timeout_minutes = 15 # uncomment to enable
# max_unlocked_minutes = 240 # uncomment to enable
[prompt]
backend = "builtin"
[prompt.theme]
bg = "#1e1e2ecc"
fg = "#cdd6f4ff"
lc = "#a6adc8ff"
ac = "#7aa2f7ff"
ibg = "#181825ff"
it = "#cdd6f4ff"
bd = "#89b4faff"
bw = 2
font = "monospace"
size = 14
# Local encrypted vault — fully writable, offline-only.
[[provider]]
id = "local"
kind = "local"
path = "~/.local/share/rosec/vaults/local.vault"
# Personal Bitwarden vault — uses global autolock defaults.
[[provider]]
id = "personal"
kind = "bitwarden"
[provider.options]
email = "user@example.com"
# base_url = "https://your-vaultwarden.example.com"
# Work Secrets Manager org (bitwarden-sm feature required).
# Stricter autolock: 5-minute idle, lock on screen lock.
[[provider]]
id = "work-sm"
kind = "bitwarden-sm"
collection = "work"
[provider.options]
access_token = "0.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.secret:key"
organization_id = "00000000-0000-0000-0000-000000000000"
[provider.autolock]
idle_timeout_minutes = 5
on_session_lock = true
# KeePassXC kdbx (read-only, experimental).
[[provider]]
id = "kp-personal"
kind = "keepassxc-file"
path = "~/Passwords.kdbx"
[provider.options]
# key_file = "~/Passwords.keyx"