walkindb

Python client for walkindb — the database for agents.

A single HTTP call provisions a private SQLite database with a 10-minute TTL. No signup, no API key, no credit card.

Install

pip install walkindb

Zero runtime dependencies — the client uses only the Python standard library, so it installs cleanly inside any agent sandbox.

Use

from walkindb import Client

db = Client()
db.execute("CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT)")
db.execute("INSERT INTO notes(body) VALUES('hello')")
result = db.execute("SELECT * FROM notes")
print(result.columns)       # ['id', 'body']
print(result.rows)          # [[1, 'hello']]
print(result.rows_affected) # 0 for SELECT, N for INSERT/UPDATE/DELETE

# The session token lives on the Client instance and is reused on subsequent
# calls, so you keep reaching the same walk-in database until its 10-minute
# TTL expires. `db.session` holds the token; `db.expires_at` is the unix
# timestamp at which the instance will be deleted.
print(db.session, db.expires_at)

If you want a fresh walk-in:

db.reset_session()
db.execute("SELECT 1")  # provisions a new instance

Errors

Non-2xx responses raise WalkinDBError with status and error attributes. Notable codes:

• 400 — invalid JSON, missing sql, forbidden keyword, or SQL syntax error
• 404 — session token unknown, tampered, or expired (walkindb returns 404, not 401, on all session failures to prevent enumeration)
• 408 — query exceeded the 2-second wall-clock timeout
• 413 — request body exceeded the 8 KB cap
• 429 — rate limit exceeded (60 req/min, 10 new instance creations/min per IP)
• 507 — instance storage quota exceeded (10 MB per walk-in)

from walkindb import Client, WalkinDBError

db = Client()
try:
    db.execute("SELECT * FROM does_not_exist")
except WalkinDBError as e:
    print(f"error {e.status}: {e.error}")

Smoke test

python -m walkindb

Provisions a fresh walk-in, runs SELECT 1, and prints the session token.

What walkindb is not

• Not a durable database. Data is deleted after ~10 minutes.
• Not for PII or regulated data. See the AUP.
• Not a Postgres or MySQL replacement.

Apache 2.0. Server source at github.com/walkindb/walkindb. Landing page and full docs at walkindb.com.