Skip to content

Local development

Local development mode runs zeroth-core as a single process against SQLite, with no external services required. Use it for hacking on graphs, running tutorials, or exercising the examples shipped with the repository.

Use case

  • Exploring the runtime for the first time
  • Running the Getting Started tutorial
  • Iterating on graph authoring without spinning up Postgres or Redis
  • Smoke-testing changes against the local checkout before pushing

Prerequisites

  • Python 3.12+
  • uv installed
  • (Optional) LLM API keys exported in the shell or a .env file

Install

The documentation site tracks main, so a repository checkout is the recommended way to run the current service and console:

git clone https://github.com/rrrozhd/zeroth.git
cd zeroth
uv sync

For library use, the latest published package is available from PyPI, but it can lag the current docs:

pip install zeroth-core

Run

# From the uv-managed checkout
uv run zeroth-core serve

The service binds 0.0.0.0:8000 by default and stores state in a local SQLite database (./zeroth.db). zeroth-core serve applies migrations on boot for both SQLite and Postgres, so no manual Alembic step is required.

A fresh database has no deployment to serve yet. Seed a runnable demo deployment (contracts + published single-agent graph) once:

uv run zeroth-core seed-demo

It prints the exact export ZEROTH_SERVICE_API_KEYS_JSON=... and curl commands for your first run.

Verify

curl -f http://localhost:8000/health/ready
# -> {"status":"healthy", "checks": {...}}

Open the interactive API explorer at http://localhost:8000/docs to poke at the REST surface. See the HTTP API Reference for the full contract.

Default storage

Local dev uses the SQLite backend. Override with env vars:

export ZEROTH_DATABASE__BACKEND=sqlite
export ZEROTH_DATABASE__SQLITE_PATH=./zeroth.db

See Configuration Reference — database for every knob the database section exposes.

Common gotchas

  • Port 8000 in use: set PORT=8001 (or another free port) before launching. The PORT env var is also honored.
  • Missing LLM keys: agent nodes fail fast if their provider key is missing. Put OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. in a .env file next to your working directory.
  • Stale SQLite file: delete ./zeroth.db to reset local state between tutorials. No migration rollback is needed.
  • Python version: the runtime requires 3.12. uv python install 3.12 if your system default is older.

Next steps