Give every bot a spall of your vault.
spall /spɔːl/ n. — a flake struck off a stone. Obsidian is the classic stone for knapping.
A self-hosted REST API and MCP server for Obsidian vaults. Every bot, script and agent gets its own token, scoped to the folders it needs and the permissions you grant. Everything else is a 404.
$ docker pull ghcr.io/ikaros-labs/spall 01 the problem
Other vault APIs hand out one key. It opens everything.
That's fine for one trusted script. It isn't fine for a Telegram bot, a dashboard on the wall and three AI agents, all holding a token that can read your journal.
A typical vault API
1 key → the whole vault
Spall
1 key per bot → 1 flake each
02 playground
Strike a flake. Watch what it can reach.
A sample vault and four accounts. Pick a file or folder and change its grant, or edit the YAML: the tree, the config and the API response update together. The deepest matching key wins.
accounts
Edit it: valid changes apply at once, like the server's hot reload. If the new file is invalid, the old config keeps serving.
vaultagent reads 4 of 13 files
selected
Projects/acme-contract/terms.md
$ spall explain agent "Projects/acme-contract/terms.md" Projects/acme-contract/terms.md → none (key: Projects/acme-contract) vault path: Projects/acme-contract/terms.md
Grant on exactly this path
Try a request as agent
GET /v1/notes/Projects/acme-contract/terms.md Accept: application/json Authorization: Bearer spl_… (agent)
{
"error": {
"code": "not_found",
"message": "Not found",
"request_id": "1504c2e1-021e-489d-a67e-94401fe8c16c"
}
}Runs entirely in this page, on Spall's own access rules (the @ikaros-labs/spall/access module from npm); the responses are simulated. The deepest key wins, no key means none, dotfiles are always denied, and anything an account can't read answers 404, never 403.
03 use cases
Struck from a real vault.
These accounts come from the author's own setup. Each one is a few lines of YAML.
Reading-list Telegram bot
Saves articles with POST /v1/notes and sends one random note each morning with ?sample=1&kind=note.
reading-bot:
root: Reading List
access:
.: edit E-ink dashboard
Polls exactly one note. Sends If-None-Match and gets a 304 when nothing changed.
eink:
access:
Dashboards/eink.md: read AI agents
Can read and patch a few project folders. The journal and the contract folder don't exist, as far as the agent can tell.
agent:
access:
Projects: edit
Projects/acme-contract: none Grafana dashboard
Prometheus scrapes vault stats: notes created and modified over time, counted only inside the account's scope.
grafana:
access:
.: read
Journal: none 04 what's in it
A small server that knows markdown.
Grants on the folder tree
Each account maps paths to levels: none, read, append, edit, full. The deepest matching key wins; key order doesn't matter.
Projects: edit
Projects/acme-contract: none Obsidian doesn't need to run
Reads and writes plain .md files on disk, kept current by a file watcher. Works on any folder of markdown.
vault:
path: /vault Writes that won't clobber
Read raw or as JSON. Create, or PATCH frontmatter or a single section; writes are serialised per note and guarded by If-Match. Deletes go to the trash, and every write goes to the audit log, if enabled.
{ "ops": [{ "op": "append",
"target": { "heading": ["Highlights"] },
"content": "- a new quote" }] } Bases without Obsidian
Evaluate a .base file's views, or send an ad-hoc query, and get rows back as JSON, filtered to the account's scope.
POST /v1/bases/Reading%20List.base/query BM25 search, related notes
Ranked full-text search with English and Russian stemming, related notes, and vault stats with Prometheus metrics.
GET /v1/search?q=knapping Ask why, from the CLI
Validate the config, mint and revoke tokens, and see exactly which key decided an access.
$ spall explain agent "Journal/2026-11.md"
Journal/2026-11.md → none (no matching key)
vault path: Journal/2026-11.md Paths checked a segment at a time
Dotfiles are always denied. Case, Unicode and trailing dots are normalised. Symlinks are refused by default; when enabled, access is re-checked on the target. This closes the traversal tricks that hit other vault servers.
GET /v1/notes/.obsidian/app.json → 404 One YAML file, hot-reloaded
Edit and save, or send SIGHUP. An invalid file is rejected and the last good config keeps serving; server and vault settings need a restart. The config must live outside the vault.
accounts → root, access, tokens Multi-arch Docker image
linux/amd64 and linux/arm64, built from main after tests pass. Bind it to a tailnet IP and you're done.
ghcr.io/ikaros-labs/spall 05 quickstart
Running in three files.
Compose, a config, a token. Then curl.
services:
spall:
image: ghcr.io/ikaros-labs/spall:latest
user: "1000:1000" # owner of the vault files
volumes:
- ~/vault:/vault
- ./config:/config
- ./data:/data
ports:
- "127.0.0.1:8787:8787"
restart: unless-stopped version: 1
server:
host: 0.0.0.0
port: 8787
vault:
path: /vault
audit:
path: /data/audit.jsonl
accounts:
reading-bot:
root: Reading List
access:
.: edit $ mkdir -p data # yours, not root's
$ docker compose run --rm spall \
token create reading-bot --name tg
spl_… # shown once
$ docker compose up -d
$ curl -H "Authorization: Bearer $TOKEN" \
"localhost:8787/v1/folders?sample=1"
$ curl -H "Authorization: Bearer $TOKEN" \
localhost:8787/v1/notes/Journal
# 404: paths are relative to reading-bot's root,
# so Journal/ can't be reached 06 for agents
MCP and a CLI, scoped like everything else.
Each agent sees only the tools and folders its token allows. A read-only token gets no write tools at all.
$ claude mcp add --transport http spall \
http://<host>:8787/mcp \
--header "Authorization: Bearer spl_…" {
"mcpServers": {
"spall": {
"command": "npx",
"args": ["-y", "@ikaros-labs/spall", "mcp"],
"env": {
"SPALL_URL": "http://<host>:8787",
"SPALL_TOKEN": "spl_…"
}
}
}
} Agents with a shell can use the CLI instead: npm i -g @ikaros-labs/spall, then spall search, spall read, spall edit. More clients (Codex, Cursor, Hermes) in the README.
07 alternatives
How it compares, honestly.
Spall does one thing the others don't: per-token folder scoping. It also gives up a few things they do well.
| Feature | Spallself-hosted server | Obsidian Local REST APIcommunity plugin | Vault MCP serversMCPVault, obsidian-mcp, … |
|---|---|---|---|
| Access per token | Per account, each with its own tokens, scoped to folders and levels | One API key for the whole vault | Mostly whole-vault; some have deny-lists for one client |
| Needs Obsidian running | No, reads files on disk | Yes, runs inside the desktop app | Usually no |
| Interface | REST, MCP and a CLI | REST, plus MCP and live events | MCP only |
| Native MCP for agents | Yes: /mcp on the server, or spall mcp over stdio; tools follow the token's grants | Yes | Yes |
| Bases queries | Yes, headless | No | No |
| Search | BM25, English + Russian | Fuzzy, plus JsonLogic on frontmatter | Full-text, varies |
| Drives the app itself | No; commands, active file and plugins are out of reach | Yes | No |
Pick Local REST API if you want to control the running Obsidian app — open notes, run commands, talk to other plugins — and one trusted client is fine.
Pick a local MCP server if a single agent on your own laptop is the only client and whole-vault access is fine. There's no server to run.