IndieK local API

The HTTP backend of the IndieK Desktop App (FOSS). It opens local archive folders (typically git repositories) in place, verifies them with the indiek library, and exposes their current state and the archive write operations to the IndieK web UI (custom-graph-explorer).

web UI (browser) ──HTTP──► indiek_api (this repo, 127.0.0.1 only) ──► indiek library ──► archive folder on disk
                                                                       (PyPI: indiek)        (git repo, edited in place)

The server always binds to 127.0.0.1: it signs archive writes with your key, so it must never be reachable from the network.

1. Prerequisites

fastAPI/ is its own git repository.

2. Setup

cd fastAPI
uv sync                 # creates .venv/ and installs runtime + dev dependencies from uv.lock

Dependency changes: uv add <pkg> / uv add --dev <pkg> / uv remove <pkg> (updates pyproject.toml and uv.lock; commit both). Never edit uv.lock by hand.

3. Daily commands

Before committing: uv run ruff check . && uv run ruff format --check . && uv run pytest.

To launch the UI with NextJS already built:

export INDIEK_API_ENV_FILE=".env" && INDIEK_API_STATIC_DIR="/Users/adrianradillo/prog/indiek/webUI/custom-graph-explorer/out" && uv run python -m indiek_api

The server prints IndieK Desktop: open http://127.0.0.1:<port>/api/session?token=… and opens it: that single-use link logs the browser in (section 7, "Access control"). Restarting the server invalidates the session: use the new link.

The server does not auto-reload: restart it after code changes.

4. Configuration

All settings are environment variables, read in indiek_api/settings.py.

Typical setups:

• Your key: put IK_AUTHOR_PRIVATE_KEY=… in fastAPI/.env (git-ignored; never commit it).
• Experiments without touching your real registry: INDIEK_API_REGISTRY=/tmp/ik-registry.json INDIEK_API_PORT=8765 uv run python -m indiek_api.
• Browser testing with a stable URL: add INDIEK_API_PORT=8765 INDIEK_API_TOKEN=<16+ chars> and open http://127.0.0.1:8765/api/session?token=<the token> once per browser.

Launched by the desktop shell (DESKTOP:REPO-SPLIT-3)

The Tauri shell starts the server as a child process with two flags (both usable without Tauri):

Try it: uv run python -m indiek_api --handshake --exit-on-stdin-eof (Ctrl-D stops it).

Embedding the API as a library (DESKTOP:REUSE-SEAMS)

create_app(settings=None, *, workspaces=None, signer=None) accepts any object matching the protocols of indiek_api/providers.py: WorkspaceProvider (list, register, remove, service; default WorkspaceRegistry) and Signer (author, author_or_none; default KeyProvider). The /api/identity/* routes are mounted only when the signer is also a KeyManager (status, store, backup, read_backup), as KeyProvider is.

5. Working with the frontend

• Frontend development: run this server as usual and npm run dev in webUI/custom-graph-explorer. Next proxies /api/* to INDIEK_API_URL (default http://127.0.0.1:8000), so the browser sees one origin — no CORS setting needed. Start this server with INDIEK_API_PORT=8000 INDIEK_API_TOKEN=<16+ chars>, then open http://localhost:3000/api/session?token=<the token> once: the cookie lands on localhost:3000 and the proxy forwards it.
• Desktop build (one process): build the UI, then point this server at it:

  (cd ../webUI/custom-graph-explorer && npm run build)
  INDIEK_API_STATIC_DIR="$(cd ../webUI/custom-graph-explorer/out && pwd)" uv run python -m indiek_api
  

  /api/* and /health are the API; every other path is a file from out/.
• Changing the API contract: the frontend mirrors it by hand in webUI/custom-graph-explorer/src/lib/types.ts and src/lib/api.ts. Update both sides (and their tests) together.

6. Code layout

indiek_api/
  __main__.py          entry point: `python -m indiek_api` → uvicorn on 127.0.0.1:<port>
  app.py               FastAPI app factory, all routes, static-files mount, CORS; main() = launcher
  security.py          access control: loopback Host, token (Bearer/cookie), write header, CSP
  identity.py          KeyProvider: the default signer (env key, else OS-keychain key via indiek.keys)
  providers.py         reuse seams: WorkspaceProvider, Signer, KeyManager protocols for create_app
  schemas.py           Pydantic request/response models (the wire contract)
  archive_service.py   ArchiveService: verified, cached, write-serialised access to ONE archive
  workspaces.py        registry of archive folders (workspace = pointer to a folder)
  errors.py            domain errors and their mapping to {"detail", "code"} responses
  settings.py          environment/dotenv configuration
tests/
  conftest.py          hermetic fixtures (see section 9)
  test_api.py          HTTP contract of every route
  test_archive_service.py   projection, caching, integrity, write serialisation
  test_cli_parity.py   results match the `ik` CLI (resource types, edge supersedes, timestamps, events)
  test_security.py     access control, launch link, CSP, launcher
  test_identity.py     signing identity routes (in-memory keychain, never the real one)
  test_write_lock.py   indiek's cross-process write lock seen through the API
  test_desktop_seams.py  injected providers, --handshake, --exit-on-stdin-eof (real subprocess)
  fixtures/demo_archive/    a real archive built with the `ik` CLI README walkthrough
CHANGELOG.md, pyproject.toml, uv.lock, .python-version

How a request flows: app.py route → looks up the workspace in workspaces.py → gets the folder's ArchiveService → which uses the indiek library → result serialised with a schemas.py model. Errors raised anywhere are domain errors from errors.py, turned into JSON by the exception handlers.

ArchiveService behaviour worth knowing:

• The archive is re-verified (chain, signatures, blobs) whenever its event logs change on disk, whoever changed them: this API, the ik CLI or a git pull. Otherwise the cached projection is reused.
• A blob altered on disk without any log change is only caught at the next full verification (after the next log change).
• Writes are serialised by a lock inside this process only; it does not guard against the ik CLI appending to the same archive at the same instant.

7. Routes

All archive routes live under /api/workspaces/{workspace_id}. Item references accept a UUID or an e{n} alias; tag references a UUID or an m{n} alias. Full request/response schemas: http://127.0.0.1:<port>/docs.

Access control (DESKTOP:LOCALHOST-TOKEN)

Design, threats and owner decisions: project_management/Design.md, cybersecurity section.

• Only loopback Host headers are served (127.0.0.1, localhost, [::1], any port): defeats DNS rebinding. Applies to every path.
• Every /api/* route needs the per-launch token: Authorization: Bearer <token> (for the future Tauri shell) or the session cookie ik_session_<port> (HttpOnly, SameSite=Strict). GET /api/session?token=<launch token> sets that cookie and redirects to /; the launch token works once (unless fixed with INDIEK_API_TOKEN). /health and the UI files are open.
• POST/PUT/PATCH/DELETE on /api/* also need X-IndieK-Request: 1: a cross-origin page would need a CORS preflight, which is never granted, so other pages cannot write.
• Every response carries a strict Content-Security-Policy: script-src lists the SHA-256 of each inline script of INDIEK_API_STATIC_DIR's HTML, computed at startup (restart after npm run build); no 'unsafe-inline'/'unsafe-eval' for scripts. Blob responses get a sandboxed policy (default-src 'none'; …; sandbox), plus X-Content-Type-Options: nosniff.

Errors

Every error is {"detail": <message>, "code": <stable slug>}; clients branch on code.

8. Recipe: adding a route

1. Contract: add request/response models to schemas.py.
2. Test first: add the HTTP test to tests/test_api.py (and to test_cli_parity.py if the CLI has an equivalent command, to prove identical results).
3. Logic: implement it as an ArchiveService method (with a unit test in test_archive_service.py) — routes stay thin.
4. Route: add it in app.py, mapping inputs to the service and the result to the schema.
5. Errors: raise existing domain errors; if a new failure kind is needed, add it in errors.py with its own stable code.
6. Frontend: mirror the types/function in webUI/custom-graph-explorer/src/lib/.
7. Docs: this README's route table and CHANGELOG.md; bump version in pyproject.toml for releases.

For the library side (indiek), learn the API from the indiek README; treat the CLI as stable.

9. Testing

Tests are hermetic: nothing reads a dotenv file, your real registry or your real archives.

Main fixtures in tests/conftest.py:

Helpers: open_index(root) (open, verify and index an archive exactly as the CLI does), build_sample_archive, tamper_last_signature (to test 409 archive_integrity).

10. Conventions

• Python 3.10+ style with strict type hints everywhere; PEP 8 via ruff (line length 100).
• uv only.
• Keep routes thin; logic lives in ArchiveService; every error has a stable code.
• Never bind to anything but 127.0.0.1; never log or return secrets (the launch URL printed at startup is the one deliberate exception: it is single-use).
• Record significant changes in CHANGELOG.md.

11. Troubleshooting

12. Support IndieK

IndieK is free and open-source software. If it's useful to you, you can support its development:

• GitHub Sponsors, for developers with a GitHub account (0% platform fees)
• Ko-fi, one-time or monthly, no account needed

All donations strictly fund the open-source core of IndieK and its public infrastructure.