A tunnel is for the folders you're not ready to import — but don't want to lose track of either. Forty gigabytes of archives where you'll only ever need three files. A design folder whose contents can't meaningfully become text notes.
A tunnel maps the folder into your vault as a table of contents: file names, paths, sizes, dates — and nothing else.
"Tunnels share file names and paths — never file contents." — the promise, exactly as the app states it
Setting one up
In the Ingest rail, click Create Tunnel, pick the folder, name the map, and create it. The tunnel appears in your vault tree as a special folder whose entries are grayed placeholders — a visual reminder that these files live on your disk, not in Trunkbase. Selecting one says it plainly: its contents have never been read.
What you can do with mapped files
- Find them. Tunnel entries show up in search by name, tag, and annotation — "do I have the Q3 contract anywhere?" finally has an answer, even for files you never imported.
- Annotate them. Add tags and notes to entries ("final version, sent to legal") without ever ingesting the file.
- Ingest them — one at a time, when you choose. Every entry has an Ingest button. That is the one and only moment Trunkbase reads the file's contents. The source stays where it is.
- Refresh the map. Tunnels don't watch continuously — refresh when you want an update, and Trunkbase reports honestly: "+12 new · 3 missing · 1 restored." Vanished files are marked Missing, never deleted, and your annotations survive.
The ladder, one more time
Ingest = bring this file in now. Watch = keep bringing files in automatically. Tunnel = just map what's there; I'll decide later. Three levels of commitment — mix them freely.
Under the hood
A tunnel is a portable, human-readable record (<name>.tunnel.yml) in your vault: root path, options, and entries with filesystem metadata only. The enumeration path is content-blind by construction — stat() only, zero open() calls — and a dedicated zero-content-read test suite in CI keeps it that way permanently. Entry names, tags, and annotations index as their own row-kind in the same search store, so tunnel entries surface in hybrid search; over MCP, a connected AI can discover files across the slices of disk you chose — without ever being granted the disk itself.