KernelLocal quickstart
1. Prerequisites
| Tool | Why | Check |
|---|---|---|
| git | source control | git --version |
| uv | Python + dependency management | uv --version (Homebrew: brew install uv) |
| Docker Desktop / OrbStack / Colima | PostgreSQL container, production rehearsals | docker info |
| Python 3.13 | runtime (3.12 minimum) | installed automatically by uv |
Provider CLIs (Codex, Claude Code, Gemini CLI) are optional and only needed to run real agent sessions; they keep their own authentication.
2. Bootstrap
make setup
This installs dependencies, starts PostgreSQL on 127.0.0.1:5434 (port 5432 is left alone for
any local server you already run), creates .env from .env.example, applies migrations and
installs Playwright's Chromium for browser tests.
3. Run
make dev # http://127.0.0.1:8000
curl -s http://127.0.0.1:8000/health/ready | jq
make worker # the background job worker
make daemon # the host daemon, once this machine is enrolled (docs/daemon.md)
To run a coding agent on this machine, enrol it: the daemon guide, and see what
Kernel runs it as — the runtimes guide covers every one
(Codex, Claude Code, Gemini,
your own generic CLI) and how to enable it in an org.
kernel runtime doctor answers whether this machine can run one, before any enrolment.
To register a session an orchestrator drives itself, see
external agents.
Every kernel command is in the CLI guide.
4. Test
make test # unit + property + PostgreSQL integration tests
make verify # everything `make test` does + lint, types, coverage, browser, security, packaging
make verify-full # verify + multi-browser, live providers, performance, backup and prod rehearsals
make verify takes about twenty minutes, and roughly eighteen of those are gate C, which
prints one dot per test and nothing else. It is working; leave it. That figure is worth knowing
because for most of M4 the same script took thirty-five and spent a quarter of an hour in silence
in the middle — one test read a Server-Sent Events stream to the end of its 900-second lifetime —
and everyone who ran it concluded it had hung and killed it, so nobody ran it end to end between M2
and M4's gate (KI-028, since fixed). If it ever goes quiet like that again, PYTHONFAULTHANDLER=1 uv run pytest … and then kill -ABRT <pid> prints every thread's Python stack and names the frame;
it needs no root and it is a great deal faster than guessing.
The PostgreSQL-backed suites migrate one template database per pytest session and clone it per
test. Each session derives its own template from its process id (kernel_test_p<pid>_template)
and drops it when it ends, so two runs started side by side never drop each other's mid-run.
Set KERNEL_TEST_TEMPLATE_DB to pin a name instead, for example
KERNEL_TEST_TEMPLATE_DB=kernel_test_e2e_template uv run pytest tests/e2e --browser chromium;
it must match kernel_test\w*_template (the harness drops and recreates it), and anything else
is refused. A pinned template is left in place between runs; a derived one whose session was
killed is dropped by the next session.
A bare uv run pytest does not collect the browser suite: tests/e2e runs only when its path is
given (make test-e2e) or -m e2e / -m critical selects it, because Playwright's sync driver and
the pytest-asyncio fixtures cannot share one pytest session.
Configuration
All settings are KERNEL_* environment variables (see .env.example). kernel db current shows the
applied migration revision; kernel db upgrade applies pending ones. The app never migrates on its
own in production.
KERNEL_AUDIT_CSV_MAX_CONCURRENCY is counted per process, not per installation: N uvicorn workers
admit N times the limit of concurrently streaming audit exports. Each worker also holds a
connection pool of its own, sized by KERNEL_DB_POOL_SIZE and KERNEL_DB_MAX_OVERFLOW (10 and 20
by default), so the installation opens up to N x (KERNEL_DB_POOL_SIZE + KERNEL_DB_MAX_OVERFLOW)
connections. Size PostgreSQL's max_connections for that total plus headroom -- four workers at the
defaults reach 120, which a stock PostgreSQL refuses at 100 -- and lower the two pool settings rather
than the export limit, which bounds streaming exports rather than connections (KI-007).
Using a different PostgreSQL
Point KERNEL_DATABASE_URL (and KERNEL_TEST_DATABASE_URL for tests) at any PostgreSQL 16+ whose
user may create databases; the test harness creates and drops kernel_test_* databases.