Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SamBleed/opencode-obsidian/llms.txt

Use this file to discover all available pages before exploring further.

Bunker OS was designed from the start around a single non-negotiable constraint: your data never leaves your machine unless you explicitly choose to send it somewhere. The vault is a plain folder of Markdown files. The BM25 search index is a JSON file on disk. The n8n automation engine runs on local Docker. The OpenCode agent state is stored in a local SQLite database. There are no background sync services, no telemetry, no call-home behavior, and no account required to use the core system.

​
What Local-First Means in Practice

Local-first is not just a marketing claim — it is a set of concrete architectural decisions that shape every component of the system.

Plain Markdown files

The entire wiki is Markdown files in a folder. You can read them in any text editor, version them with git, diff them, and search them with grep. There is no proprietary database, no binary format, no lock-in.

Zero-dependency retrieval

The BM25 search engine is pure Python stdlib — no numpy, no ollama, no external packages. The index is a JSON file you can inspect directly. It runs completely offline.

Docker-local automation

n8n runs on your machine via Docker Compose. Workflows are JSON files stored in the repo. No n8n Cloud account is required. The n8n UI is available at localhost:5678.

No API keys required for core

BM25 retrieval, vault management, wiki querying, ingestion, linting, and all bash scripts run without any API key. Optional integrations remain strictly optional.

​
Where Every Piece of Data Lives

Every component in Bunker OS has a known, inspectable, local storage location.
ComponentStorageLocation
Wiki pagesPlain .md fileswiki/ in the repo root
Raw sourcesImmutable files.raw/ in the repo root
BM25 indexJSON file on diskscripts/bm25_index.json
n8n workflowsJSON filesautomation/n8n-lab/workflows/
n8n runtime dataPostgreSQL on Docker (recommended) or SQLiteDocker volume
n8n secrets.env file (gitignored)automation/n8n-lab/.env
OpenCode stateSQLite database~/.local/share/opencode/
Evidence indexJSON manifestGenerated by bin/evidence-index.sh
The wiki/ directory and the automation/n8n-lab/.env file are both listed in .gitignore. Your personal knowledge base and your secrets never appear in any git commit or get pushed to any remote repository.

​
The Safety Model

Five safety properties are enforced at the infrastructure level, not just by convention: 1. Script path resolution via BUNKER_HOME All shell scripts in bin/ resolve the vault path through the BUNKER_HOME environment variable or the repository root. There are no hardcoded absolute paths. You can move the vault to any location and scripts will follow. 
# Override vault path for scripts
export BUNKER_HOME=/path/to/your/vault
./bin/wiki-integrity.sh
2. External-effect scripts default to dry-run Scripts that have external effects (modifying files, committing to git, sending webhooks) default to dry-run mode. You must pass --apply to execute real changes. This prevents accidental data modification. 
./bin/wiki-sync.sh            # Dry run — shows what would change
./bin/wiki-sync.sh --apply    # Applies changes
3. Ingest server bound to loopback The HTTP ingest server binds to 127.0.0.1:9090 by default, not 0.0.0.0. It is only reachable from the local machine, never from the network. 4. Evidence artifacts are indexed, not modified The evidence-index skill and bin/evidence-index.sh create a manifest of evidence artifacts with SHA256 checksums. The originals are never touched. The index is a derived artifact; the originals remain bit-for-bit identical to what was captured. 5. n8n secrets managed via .env (gitignored) + n8n credential vault API keys and external service credentials are stored in two places exclusively: the automation/n8n-lab/.env file (gitignored, never committed) and the n8n credential vault (stored in the Docker volume, encrypted at rest). No credential ever appears in a script, skill, or wiki page.

​
Syncing Across Devices

Because the vault is a plain folder of files, you have full choice of sync mechanism. No proprietary sync service is required.
MethodNotes
Obsidian SyncEnd-to-end encrypted, designed for Obsidian vaults
SyncthingPeer-to-peer, open source, no cloud intermediary
iCloud DriveWorks on macOS/iOS; subject to iCloud’s terms
Dropbox / Google DriveSimple but files pass through cloud servers
gitFull version history; requires a private remote repository
If you use git to sync the wiki, make sure wiki/ is removed from .gitignore in your private fork. The default .gitignore excludes wiki/ to prevent accidental publication of personal knowledge. Never push your wiki to a public repository.

​
Optional Cloud Integrations

Bunker OS has several optional integrations that require internet access or API keys. None of them are required for the core workflow. They extend capability without becoming a dependency.
IntegrationPurposeRequired for
OpenRouter APIAI triage in the AOC v4 Enterprise pipelineAOC v4 only
Exa search APIWeb search for the autoresearch skillAutoresearch only
GitHub APIIssue creation from AOC v4AOC v4 only
Slack webhookAlert notificationsUltimate Alerter only
Telegram botAlert notificationsUltimate Alerter only
Discord webhookAlert notificationsUltimate Alerter only
All of these credentials are managed exclusively through the n8n credential vault and the automation/n8n-lab/.env file. No API key is ever embedded in a script, a skill, or a wiki page. The secret-scanning suite in the test runner checks for leaked credentials on every make test run.
Fully offline capabilities (no internet access required): BM25 retrieval, vault management, wiki ingestion from local files, wiki querying, linting, all bash scripts, n8n workflow execution (for webhooks you trigger yourself), evidence indexing.Requires internet access: Exa-powered autoresearch (external web search), OpenRouter-powered AI triage in AOC v4, notification delivery to Slack/Telegram/Discord, and GitHub issue creation.

​
n8n Secrets Management

n8n secrets follow a two-layer model that keeps credentials out of the codebase: 
# Layer 1: .env file (gitignored, configures Docker environment)
# automation/n8n-lab/.env
OPENROUTER_API_KEY=sk-or-...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
GITHUB_TOKEN=ghp_...

# Layer 2: n8n credential vault (stored in Docker volume, encrypted at rest)
# Credentials are referenced by name in workflows, never by raw value
The .env file sets environment variables consumed by Docker Compose. Credentials that need to be used inside n8n workflows are stored in the n8n credential vault through the n8n UI. Workflow JSON files reference credentials by name, so they can be committed to the repo without exposing secrets.

​
Verifying Your Local Setup

Run the full health check to confirm all local components are operational: 
# Full local definition-of-done check
./bin/bunker-check.sh

# Specific checks
docker ps --filter name=n8n          # Confirm n8n is running
python3 scripts/retrieve.py status   # Confirm BM25 index exists
./bin/wiki-integrity.sh              # Vault integrity scan
make test                            # 430 tests across 5 suites

Architecture

The 10-layer pipeline and how all components connect.

Vault Structure

Where every file type lives in the repository.

n8n Automation

The local async nervous system: Docker setup and workflow management.

Quickstart

Get Bunker OS running on your machine in minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us