# VaultLink documentation

> Set up the VaultLink companion for an Obsidian vault, add the Chromium side panel, reach it from other devices with Tailscale Serve, run native Obsidian, and understand supported files and limits.

Project page: https://dbaney.com/projects/vaultlink/

## Set up the companion

You need Node.js 22.12 or newer on the macOS or Linux computer that holds your vault.

1. Download `vaultlink-<version>-companion.zip` from the [latest release](https://github.com/baney75/vaultlink/releases/latest) and extract the whole zip into a folder.
2. In that folder, run:

   ```sh
   node setup.mjs
   ```

3. Enter the path to your vault. Press Enter at the Tailscale question if you only need this computer.
4. Open the printed address and enter the pairing token.
5. Open a note, add a line, save and reopen it to confirm the change.

Keep the terminal open while you use VaultLink; **Ctrl+C** stops it. The pairing token is a password for the vault. It is stored in a private file under `~/.vaultlink`.

## Add the Chromium side panel

1. Extract `vaultlink-<version>-chromium.zip` into its own folder.
2. Open `chrome://extensions` (or `edge://extensions`), turn on **Developer mode** and choose **Load unpacked**.
3. Select the extracted folder, click the VaultLink icon and connect with the same address and token.

Chromium 116 or newer with a working Side Panel API is required. Firefox and Safari packages are not included.

## Open it on another device

Install and sign in to Tailscale on the vault computer and the other device, and restrict your tailnet rules to the devices allowed to reach the vault. On the vault computer, while the companion runs:

```sh
tailscale serve --bg --https=8443 http://127.0.0.1:27124
tailscale serve status
```

Restart `node setup.mjs` and enter the private `https://…ts.net:8443` address. Open that address on the other device and enter the token. Use Tailscale **Serve**, not Funnel. Remove the route with `tailscale serve --https=8443 off`.

## Run native Obsidian

The native option runs LinuxServer's Obsidian container on a Linux host with Docker Compose and Tailscale, on a different HTTPS address with its own desktop password. Follow `native/README.md` in the repository. Plugin compatibility depends on the Linux environment.

## Supported files

| File | Tools |
| --- | --- |
| Markdown | Source editor, preview, split view, wiki links, local images, outline, conflict handling |
| Text, JSON, CSV | Source editing with revision checks |
| PDF | Viewing, text and highlight overlays, rotation, page removal, a new PDF copy |
| Images | Crop, rotate, flip, resize and export a new PNG or JPEG copy |
| Obsidian Canvas | View and edit supported text nodes |
| Audio and video | Playback when the browser supports the codec |

PDF tools do not securely redact content. Dataview, Bases, Excalidraw and plugin views are not rendered in the workspace.

## Safety

- The companion listens on loopback only and requires the token for every request.
- Note bytes are backed up outside the vault before replacement.
- Hidden folders, including `.obsidian`, are not served.
- Close other editors before changing the same note; VaultLink detects saved changes and offers conflict recovery.

## Build from source

```sh
npm ci
npm run check
npm run demo
```

The demo creates a synthetic vault and prints a sample token for `http://127.0.0.1:27124`. `npm run package` builds both release zips and `release/SHA256SUMS`.