# walkindb > The database for agents. A single HTTP call provisions a private SQL database with a 10-minute TTL. No signup, no API key, no credit card. The first managed database designed for machines instead of humans. walkindb exists because LLM agents can't sign up for things. Every other managed database (Upstash, Turso, Supabase, Neon, etc.) assumes a human with a credit card on the other end. walkindb assumes a machine that needs a scratch space for the next ten minutes and then disappears. There are three live endpoints against the same database: ``` POST https://api.walkindb.com/sql SQL {"sql": "SELECT 1", "args": []} POST https://api.walkindb.com/kv key-value ["SET", "k", "v", "EX", "300"] POST https://api.walkindb.com/doc/x documents {"name": "ada"} ``` All three share one walk-in: a key written through `/kv` and a document stored through `/doc` are both rows readable through `/sql`. On the first request (no `X-Walkin-Session` header), walkindb provisions a private SQLite file, returns a session token in the `X-Walkin-Session` response header, and runs the query. Subsequent requests with the same token reach the same database. Ten minutes after creation, the file is deleted automatically. That deletion is the feature, not the bug. ## Core facts - **Storage engine**: SQLite, one file per instance, 10 MB cap. - **TTL**: 10 minutes per instance, non-negotiable. There is no paid tier. If you need persistence, use a different database. - **Auth**: none. No signup, no API key, no credit card. - **License**: Apache 2.0. Self-hosting is supported. - **Cost**: free. - **Built for**: LLM agents (Claude, GPT, etc.) that need ephemeral SQL state, prototyping, learning, throwaway notebooks. - **Not for**: PII, regulated data, anything you can't afford to lose, durable storage of any kind. See the AUP. ## Quickstart ```bash # First request — no session header, a fresh instance is provisioned. curl -X POST https://api.walkindb.com/sql \ -H "content-type: application/json" \ -d '{"sql":"CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT); INSERT INTO notes(body) VALUES(\"hello\")"}' # Response includes: # X-Walkin-Session: wkn_ # X-Walkin-TTL: # Subsequent requests reuse the token. curl -X POST https://api.walkindb.com/sql \ -H "X-Walkin-Session: wkn_" \ -H "content-type: application/json" \ -d '{"sql":"SELECT * FROM notes"}' ``` ## Key-value interface (POST /kv) `/kv` implements Redis **string and hash command semantics** over HTTP. It is **not** a RESP wire endpoint: `redis-py`, `ioredis` and `node-redis` open a raw TCP socket, so they cannot reach an HTTP path and will not work against it. A raw TCP port is not available. Send a JSON array. The session header works exactly as it does for `/sql`, and omitting it provisions a new walk-in. ``` curl -X POST https://api.walkindb.com/kv \ -H "content-type: application/json" \ -d '["SET","session:42","ready","EX","300"]' # -> {"result":"OK"} curl -X POST https://api.walkindb.com/kv \ -H "X-Walkin-Session: wkn_..." \ -d '["HGETALL","user:1"]' # -> {"result":{"name":"ada","role":"admin"}} ``` Supported commands (everything else returns `unknown command`): - **Strings**: SET (EX/PX/NX/XX/KEEPTTL), GET, GETDEL, APPEND, STRLEN, INCR, INCRBY, DECR, DECRBY, GETRANGE, MSET, MGET - **Hashes**: HSET, HSETNX, HGET, HMGET, HDEL, HGETALL, HEXISTS, HKEYS, HVALS, HLEN, HINCRBY - **Keyspace**: DEL, EXISTS, TYPE, EXPIRE, PEXPIRE, PERSIST, TTL, PTTL - **Connection**: PING, ECHO Two deliberate divergences from Redis: 1. **TTL is clamped to the instance deadline.** `EXPIRE k 3600` inside a 10-minute walk-in stores the walk-in's deadline, so `TTL` may return less than you asked for. Nothing can outlive the instance. 2. **Values are UTF-8 strings.** Redis strings are binary-safe; over JSON they are not. Base64 arbitrary bytes yourself. Errors use Redis wording: `WRONGTYPE Operation against a key holding the wrong kind of value`, `value is not an integer or out of range`. State lives in two ordinary tables, `_wk_kv` and `_wk_kv_h`, inside your own database — so `SELECT k, v FROM _wk_kv` over `/sql` returns what you wrote through `/kv`. Do not create your own tables with those names. Redis is a registered trademark of Redis Ltd. Valkey is a trademark of LF Projects, LLC. walkindb is not affiliated with, endorsed by, or sponsored by either. ## Document interface (POST /doc) `/doc` stores JSON documents in the same walk-in and queries them by path. Indexes are created automatically the first time you query a path, so `find` is an index lookup and you never manage an index. ``` POST /doc/{collection} body: the document -> {"id":"..."} POST /doc/{collection}/find {"where":{...},"limit":50} -> {"docs":[...],"count":n} POST /doc/{collection}/get {"id":"..."} -> {"doc":{...}} POST /doc/{collection}/delete {"id":"..."} -> {"deleted":true} ``` ``` curl -X POST https://api.walkindb.com/doc/notes \ -H "content-type: application/json" \ -d '{"name":"ada","meta":{"rank":"admiral"}}' # -> {"id":"01a043fe-a12a-72aa-96b0-568704bd6284"} curl -X POST https://api.walkindb.com/doc/notes/find \ -H "X-Walkin-Session: wkn_..." \ -d '{"where":{"$.meta.rank":"admiral"}}' # -> {"count":1,"docs":[{"id":"01a0...","name":"ada",...}]} ``` Paths look like `$.field`, `$.a.b` or `$.items[0]`. Conditions are equality only and are ANDed — no ranges, no OR, no sorting beyond insertion order (ids are UUIDv7, so they sort chronologically). Use `/sql` for anything richer; it is the same database. Limits: 64 KB per document, collection names must match `[A-Za-z0-9_-]{1,64}`, find returns 50 by default and 200 maximum, and index growth is capped at 8 per walk-in. Documents live in the table `_wk_doc` inside your own walk-in, so `/sql` can read them. Do not create your own table with that name. A flat document is interchangeable with a `/kv` hash; a nested one is not, because hashes are flat. ## Pages an LLM should care about **Start here:** - [Landing page](https://walkindb.com/) — what walkindb is, in human terms. - [**Full docs flattened into one file** (`llms-full.txt`)](https://walkindb.com/llms-full.txt) — every docs section concatenated as Markdown, designed to be fetched once and pasted into a model context. This is the highest-leverage single URL for an LLM to fetch. **Docs:** - [Docs home](https://walkindb.com/docs/) — overview, limits, TOC - [Quickstart](https://walkindb.com/docs/quickstart/) — curl, Python, JS in 60 seconds - [REST API reference](https://walkindb.com/docs/api/) — every endpoint, header, response shape - [Error codes](https://walkindb.com/docs/api/errors/) — every status code walkindb can return - [OpenAPI 3.1 spec (served by the API itself)](https://api.walkindb.com/openapi.json) — machine-readable - [Python SDK](https://walkindb.com/docs/sdk/python/) — Client / Result / WalkinDBError reference - [JavaScript / TypeScript SDK](https://walkindb.com/docs/sdk/js/) — same API for JS - [MCP server](https://walkindb.com/docs/mcp/) — `npx walkindb-mcp` gives Claude Code / Claude Desktop / Cursor / Zed / Continue a `walkindb_execute` tool - [Agent patterns](https://walkindb.com/docs/examples/) — when to use walkindb, code recipes - [Security model](https://walkindb.com/docs/security/) — defense-in-depth, rollout state **Blog:** - [How walkindb holds 100 000 concurrent walk-ins on a single €6 VPS](https://walkindb.com/docs/blog/scaling/) — share-nothing architecture, no connection pool, Landlock + seccomp, with measured numbers from the actual box - [v0.1 release notes](https://walkindb.com/docs/blog/v0-1-release-notes/) — what shipped in the first public release, SECURITY.md rollout state, full benchmark tables **Legal:** - [Acceptable Use Policy](https://walkindb.com/legal/aup/) — what is forbidden. CSAM, PII, scraping, DDoS, malware staging, etc. - [Terms of Service](https://walkindb.com/legal/terms/) — as-is service, €100 liability cap, Portuguese law, courts of Lisbon. - [Privacy Notice](https://walkindb.com/legal/privacy/) — what we log: timestamp, IP, instance ID, status, byte length, user agent. Never the SQL itself, never the result rows. Logs are kept 7 days. - [DMCA / takedown procedure](https://walkindb.com/legal/dmca/) — how to file a copyright complaint about content allegedly stored in a walk-in instance. ## Open-source repository The walkindb server is published at under the Apache License 2.0. The repository contains: - `cmd/walkindb/main.go` — entry point. - `internal/router/` — HTTP surface (`POST /sql`, `GET /healthz`). - `internal/executor/` — SQLite execution with a 2 s wall-clock timeout and a 10 MB page-count cap. - `internal/session/` — HMAC-signed session tokens (`X-Walkin-Session`). - `internal/instance/` — per-instance directory provisioning under `/var/walkindb/instances/`. - `SECURITY.md` — full defense-in-depth model. - `ARCHITECTURE.md` — single-binary, single-VPS architecture. - `legal/*.md` — markdown source for the public legal documents. ## Contact - General: - Abuse: - Security vulnerabilities: - DMCA: - Privacy / GDPR: