Totenschloss
Repository hosted on Twig: https://twig.silenlocatelli.ch/stranded/totenschloss
A chat server over the Deadlock data lake. Ask questions in plain English and get answers
from read-only DuckDB queries against the DuckLake catalog at data.deadlock-api.com.
Every lookup behind a reply is one click away under its "See the data" link.
Stack: Zig server (std.http), DuckDB via its C API (in-memory, one database per request),
vanilla JavaScript and CSS frontend embedded into the binary. The build links DuckDB and
libstdc++ statically, so the result is one self-contained binary; only the system libc is
dynamic, which DuckDB needs to load its ducklake and httpfs extensions.
Run locally
mise install # Zig 0.14.1, plus DuckDB 2.0.0 via the postinstall hook
mise run run # PORT defaults to 8080
mise.toml pins the toolchain. The postinstall hook runs scripts/fetch-duckdb.sh, which
downloads the DuckDB static archives and the libstdc++ archive into vendor/duckdb/ (skipped if
already present); nothing has to be installed system-wide. Tasks: build, test, run,
fetch-duckdb, docker.
Builds target the baseline x86-64 CPU by default, so a binary built on a new machine still runs
on an older host. Override with -Dcpu=native only for a binary that stays on this machine.
Open http://localhost:8080. Without an API key the chat is disabled, but /sql still works:
/sql SELECT hero_id, count(*) AS games FROM lake.match_player_latest
WHERE match_id BETWEEN 105000000 AND 105100000 GROUP BY ALL ORDER BY games DESC
/tables # list lake tables and columns
Tests: mise run test.
Configuration
Local values go in .env (git-ignored); mise loads it for every task. The full list of variables,
with defaults and what each one is for, is in docs/DEPLOY.md.
Login and invites
Set ADMIN_PASSWORD (and optionally ADMIN_USERNAME, default admin) to turn on login. Without it
the site stays open to anyone, which is fine for a local trial.
The admin signs in with those environment values. Admins can open Invites, create a single-use
invite, and share the resulting /signup?invite=… link. The recipient picks a username and a password
and is signed in. Accounts and invites are stored in storage/auth.json; passwords are PBKDF2 hashes
with a random salt, and invite codes are stored only as SHA-256 hashes. Sessions are in memory, so a
restart signs everyone out but keeps the accounts.
Security
User text is never spliced into SQL. Anything that reaches DuckDB goes through these layers:
- Parser check.
json_serialize_sqlturns the query into an AST. It must be exactly oneSELECT(or set operation).sql_guard.zigrejects anything else. - Table and function rules. Base tables must come from
lake. Table functions (read_csv,glob, URL literals inFROM, ...) are rejected, andgetenvand similar scalar functions are denied by name. - Statement kind. DuckDB's own prepared-statement type must be
SELECT. - Session lockdown. The catalog is attached
READ_ONLY. Local filesystem access is disabled, and configuration is locked (lock_configuration) before any query runs. Remote reads stay on because the lake's data files are HTTPS. - Limits. One private in-memory DuckDB per request, 1 GB memory cap, 30 s query timeout,
45 s per answer, 200 rows returned to the UI (50 to the model), at most 4 concurrent chats.
lake.match_playeris hundreds of GB, so scans of it must filterstart_timeormatch_id(or be a metadata aggregate such ascount(*)); other shapes are rejected before DuckDB starts downloading data files.
The model only sees the schema and results it asks for. The API key is read once at startup and never sent to the browser.
Web requests must also pass the login check when ADMIN_PASSWORD is set. Sessions use a random
256-bit token in an HttpOnly, SameSite=Lax cookie; state-changing requests reject cross-site
origins. Password checks use PBKDF2's deliberate cost, so brute-force attempts are expensive.
Deploy
See docs/DEPLOY.md for once and Docker deployment, and for configuring login and invites.
Docker (summary)
docker build -t totenschloss .
docker run --rm -p 8080:80 --env-file .env -v totenschloss-data:/storage totenschloss
The image meets the once requirements:
- serves HTTP on port 80 (
PORT=80) GET /upreturns200 ok- persistent data in
/storage(the volume is included in backups) - no
SECRET_KEY_BASE, SMTP or hostname configuration needed; passINFERENCE_API_KEY(orANTHROPIC_API_KEY) andADMIN_PASSWORDthrough--env-file;.envis never copied into the image
Layout
.twig.toml Twig view configuration (tabs, presentation, scripts)
src/main.zig entry point and startup
src/server.zig HTTP routes, admission control, chat and auth endpoints
src/auth.zig accounts, invites, password hashing and sessions
src/chat.zig agent loop: model <-> describe_tables / run_sql tools
src/llm.zig Anthropic Messages API client (tool use)
src/session.zig per-request DuckDB session: attach, lockdown, timeout, results
src/sql_guard.zig AST-based query guard and its tests
src/duckdb.zig DuckDB C API wrapper
src/web/ index.html, app.js, style.css (embedded at build time)