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
open sourceheadlessplain markdownamd64 + arm64
reading-bot Reading List/ · edit eink Dashboards/eink.md · read agent Projects/ · edit your vault — the journal stays on the core

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

API_KEY→/ (everything)full
same key, in a bot→Journal/full
same key, in an agent→Projects/acme-contract/full

Spall

1 key per bot → 1 flake each

reading-bot→Reading List/edit
eink→Dashboards/eink.mdread
agent→Projects/ − acme-contract/edit

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

grantedparent only404 to this account

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)
404 Not Foundsame answer as a path that doesn’t exist
{
  "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.

scope

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
headless

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
notes

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

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
search

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
explain

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
safety

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
config

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
ship

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.

01docker-compose.yml
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
02config/spall.yaml
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
03token, then curl
$ 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.

01Claude Code (HTTP)
$ claude mcp add --transport http spall \
    http://<host>:8787/mcp \
    --header "Authorization: Bearer spl_…"
02Claude Desktop, or any stdio client
{
  "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.