self-host

ghostbrain already runs entirely on your machine — "self-hosting" here really means building the indexer from source instead of using the signed binary, plus a few extras: managing updates, backing up the vault, and understanding the licenses.

system requirements

typical idle resource use after backfill: under 1% cpu, 250–500 mb resident memory. the local model is mmaped; you'll see the page-cache usage in top but it isn't pinned.

building from source

two repos:

• ghost-brain — the obsidian plugin (typescript, mit-licensed).
• ghost-brain/indexer — the local indexer + extraction model bindings (rust, fair-source license; see below).

plugin

git clone https://github.com/nikrich/ghost-brain
cd ghost-brain
npm install
npm run build

# drop the dist/ folder into your vault
cp -r dist/ "~/your-vault/.obsidian/plugins/ghostbrain"

indexer

cd ghost-brain/indexer
cargo build --release

# run it directly; the plugin will find it on its socket
./target/release/ghostbrain serve --vault ~/your-vault

the first build downloads the 1.8 gb model artefact. it's pinned by sha-256 in indexer/models.lock. you can mirror the artefact to your own object store and pass GHOSTBRAIN_MODEL_URL to fetch it from there in a locked-down environment.

updating

three update channels:

set the channel in settings → ghostbrain → updates, or by env: GHOSTBRAIN_CHANNEL=beta. the plugin checks once a day on launch and prompts you; it never updates silently.

disk & storage

ghostbrain stores three things:

• markdown notes — in your obsidian vault. backup with your normal vault backup.
• indexer state — under vault/.ghostbrain/. small, mostly text. include in vault backup.
• the model — under ~/.ghostbrain/models/. ~1.8 gb. you can exclude from backup; it'll be re-downloaded.

backup

# tar.gz the vault + .ghostbrain/ (skips the model)
ghostbrain export ~/Backups/ghostbrain-$(date +%F).tar.gz

restoring is "untar and point obsidian at it." tokens are not exported — you'll reconnect each app on restore. this is on purpose.

encrypting at rest

ghostbrain doesn't encrypt the vault itself — that's your filesystem's job. use filevault, bitlocker, or luks. if you want per-vault encryption inside an unencrypted volume, obsidian has plugins for that (e.g. age-encrypt); they work fine with ghostbrain.

licenses

two different ones, on purpose:

running on an airgapped machine

1. on a connected machine, run ghostbrain bundle --output offline.tar. this packages the binary, the model, and a pinned dependency mirror.
2. transfer offline.tar to the airgapped machine.
3. ghostbrain bundle --install offline.tar.
4. connect connectors that don't require oauth (linear api key, github pat, notion integration token). gmail/slack/calendar/drive require a one-time browser exchange and won't work on an airgapped host.

troubleshooting

ghostbrain doctor covers most issues. common failure modes: