Python Admin SDK

Get Started · Examples · Docs · Discord

Welcome to Instant's Python Admin SDK.

Quickstart

uv add instantdb
# or
pip install instantdb

Requires Python 3.10+.

app_id and admin_token can be passed explicitly or read from INSTANT_APP_ID / INSTANT_APP_ADMIN_TOKEN environment variables.

from instantdb import Instant, id

db = Instant(
    app_id="YOUR_APP_ID",
    admin_token="YOUR_ADMIN_TOKEN",
)

# Transact (InstaML)
goal_id = id()
db.transact(db.tx.goals[goal_id].update({"title": "Get fit"}))

# Query (InstaQL)
result = db.query({"goals": {"todos": {}}})

# Auth: magic codes, tokens, user management
token = db.auth.create_token(email="alyssa@example.com")

# Impersonate for permission-scoped queries
scoped = db.as_user(guest=True)
scoped_result = scoped.query({"goals": {}})

The async client (AsyncInstant) ships the same surface plus subscribe_query (live SSE subscriptions) and streams (durable bidirectional byte streams). Use it from FastAPI handlers, agents, or anywhere you're already running an event loop:

import asyncio
from instantdb import AsyncInstant

adb = AsyncInstant()

async def main():
    async with adb.subscribe_query({"goals": {}}) as sub:
        async for payload in sub:
            process(payload)

asyncio.run(main())

Head on over to the Python Docs for more usage docs!

Development

cd client/packages/python
uv sync
make check   # ruff + mypy strict + pytest
make fmt

Editing the SDK source

Only edit src/instantdb/_async/. The sync client at src/instantdb/_sync/ is generated from the async tree via unasync and is committed to the repo. After any change to _async/, regenerate:

make unasync

This runs scripts/run_unasync.py (preprocesses + applies replacement rules) then ruff (import sort + format). Commit the generated _sync/ tree alongside your async change.

Some modules under _async/ are intentionally async-only — they're listed in the ASYNC_ONLY set in scripts/run_unasync.py and each one explains its rationale in its own docstring (typically: relies on asyncio coordination primitives that don't survive unasync's token-rewrite).

Adding a new file under _async/:

• HTTP-shaped surface (request/response, no background tasks): just drop it in and re-run make unasync — it'll be picked up automatically.
• Async-only surface (background tasks, asyncio coordination): drop it in, add its path to ASYNC_ONLY in scripts/run_unasync.py, and note the why in the module's docstring so the next person doesn't have to figure it out.

If you add a method or import that should exist only on the async client (inside a file that is unasynced), wrap it in marker comments and re-run make unasync:

# UNASYNC_REMOVE_START
def new_async_only_method(self): ...
# UNASYNC_REMOVE_END

Full mechanics — replacement rules, preprocessing details, what to avoid — live in the docstring of scripts/run_unasync.py.

Testing changes

We test in three layers, fastest to most realistic:

1. Unit tests (make check) — validation, header construction, error parsing, and pure-logic helpers (buffer-discard math, dispatch precedence, etc.). No network. This is the fast inner loop.
2. Sandbox integration tests — exercise the SDK against a real Instant server and assert on outcomes. Similar to how we test the JS admin SDK.
3. End-to-end branch test — scaffold a real consumer project that pulls the SDK from your branch, then run a script the way a user would.

Sandbox (integration)

The sandbox at client/sandbox/admin-sdk-python/ is the integration layer.

cd ../../sandbox/admin-sdk-python
cp .env.example .env   # fill in INSTANT_APP_ID + INSTANT_APP_ADMIN_TOKEN
uv sync
# uncomment a tester call inside main() in src/main.py
uv run --env-file .env python -m src.main

Two entry points: src/main.py for the async client (everything, including subscribe + streams) and src/main_sync.py for the sync client (auth, query, transact, storage, rooms, webhooks). Tester calls are commented out at rest — uncomment the one you want, run it, re-comment before committing.

Defaults to http://localhost:8888; set INSTANT_API_URI in .env to point elsewhere.

End-to-end (a real project on your branch)

To exercise a change the way a user would — scaffold a project, install the SDK, run a script — point a fresh create-instant-app project at your branch:

1. Push your branch to GitHub (e.g. my-feature).

2. Scaffold a project with the per-branch build of create-instant-app (the @branch-<your-branch> tag is published automatically per branch):

   cd /tmp
   pnpx create-instant-app@branch-my-feature --python my-app
   cd my-app
   

3. The scaffold pulls instantdb from PyPI by default, which won't have your branch's changes. Point it at your branch by adding a [tool.uv.sources] entry to the scaffolded pyproject.toml:

   [tool.uv.sources]
   instantdb = { git = "https://github.com/instantdb/instant.git", branch = "my-feature", subdirectory = "client/packages/python" }
   

4. Sync and run (the scaffolder already wrote a working .env):

   uv sync   # clones the repo, builds the SDK from your branch, installs it
   uv run --env-file .env python main.py
   

If you already have the monorepo checked out and are iterating on the SDK, use a local editable path instead so source edits show up without re-syncing from git:

[tool.uv.sources]
instantdb = { path = "/absolute/path/to/client/packages/python", editable = true }

Questions?

If you have any questions, feel free to drop us a line on our Discord