One runner home defines one logical BaudBound installation. Back up the complete runner home together with its external secret key before upgrades or machine migration. Do not edit the SQLite database manually.
BAUDBOUND_HOME overrides the entire runner home. Without it, BaudBound uses:
| Platform | Default location |
|---|---|
| Windows | %LOCALAPPDATA%\BaudBound\runner |
Linux with XDG_DATA_HOME |
$XDG_DATA_HOME/BaudBound/runner |
| Other supported Linux setup | $HOME/.local/share/BaudBound/runner |
The desktop Doctor view and CLI status output show resolved paths. The recommended Linux background service runs under the same user account and therefore uses the same runner home as that user's CLI.
Never run two services against the same runner home. Although SQLite coordinates database writes, duplicated listeners can compete for ports, serial devices, files, and trigger events.
| Path | Responsibility |
|---|---|
config.toml |
Machine-specific runner, listener, target, and serial configuration |
runner.sqlite3 |
Durable runner state |
runner.sqlite3-wal and runner.sqlite3-shm |
SQLite write-ahead logging files that may exist while the database is open |
scripts/ |
Validated copies of imported .bbs packages, retaining their imported filenames |
SQLite stores:
The database does not make encrypted secret values independently recoverable. Their encryption key is stored in the operating-system credential vault for desktop use or supplied through BAUDBOUND_SECRET_KEY for headless use.
Stop every BaudBound process that uses the runner home before copying it. This closes listener resources and allows SQLite to checkpoint its WAL state.
For the desktop application, stop the background runner and choose Quit BaudBound from the tray menu. Confirm that the process has exited.
For a headless service, use the service manager's stop command and verify that status is inactive. See Linux Background Service.
Replace PATH with a destination outside the runner home:
$source = Join-Path $env:LOCALAPPDATA "BaudBound\runner"
$destination = "PATH"
Copy-Item -LiteralPath $source -Destination $destination -Recurse
When BAUDBOUND_HOME is set, use that value as $source instead.
Replace PATH with a protected backup destination:
cp -a "$HOME/.local/share/BaudBound/runner" "PATH"
When BAUDBOUND_HOME or XDG_DATA_HOME is set, copy the resolved directory reported by BaudBound instead.
Desktop installations rely on the operating-system credential vault. Include the platform's supported credential-vault backup or machine-migration procedure. Copying runner files alone does not copy that key.
Headless installations must back up the exact BAUDBOUND_SECRET_KEY through the operator's secret-management system. Do not place the plaintext key inside the same unencrypted archive as publicly accessible backups.
Confirm that the copy contains config.toml, runner.sqlite3, and scripts/. Compare directory sizes and record the runner version used to create it. Protect the backup because it contains package behavior, logs, variable values, and encrypted secrets.
Restart the original runner only after verification.
BAUDBOUND_SECRET_KEY.If the restored database schema is newer than the installed runner supports, stop and install the matching or newer release. Do not reduce the schema version manually.
Copying only runner.sqlite3 can omit active WAL content and installed package files. Copying only scripts/ loses approvals, state, runs, and encrypted values. Mixing files from different backup times can make recorded hashes and package contents disagree.
Direct SQL edits bypass validation and can violate foreign keys, encryption requirements, package identity, variable versions, or approval invariants. There is no supported recovery procedure that begins by changing rows with a SQLite editor.
Stop the runner, free space on the volume containing the runner home, and confirm that the account can create files there. Restore from backup if the database or package copy was interrupted. Do not repeatedly restart a service that cannot write durable state.
Confirm that the account running BaudBound owns or can read and write the complete runner home. On Linux, inspect every parent directory as well as the files. Avoid making the directory world-writable.
Stop all runner processes and preserve a copy of the failed directory for diagnosis. Restore the latest known-good complete backup to a separate location. Do not run repair tools against the only copy.
The database records and scripts/ files likely came from different points in time or were modified. Restore them from one complete backup. Re-importing an authoritative package revision is safer than editing stored hash data.
The runner does not have the original encryption key. Restore the credential-vault entry or headless key backup. If the key is permanently lost, encrypted values cannot be recovered. Remove and set each secret again from its authoritative source.
The backup was opened by a newer BaudBound release. Install a compatible version. Downgrading a live runner home is unsupported unless release notes provide an explicit migration path.
Uninstalling the application does not necessarily remove the runner home. This protects scripts and state during reinstall.
Deleting the runner home permanently removes installed packages, approvals, run history, persistent and global values, and encrypted secret records. Stop BaudBound, create and verify a backup, and confirm the resolved path before deletion.