Quickstart

What you will build

A minimal, working actor — generated, verified, and running locally with PostgreSQL and Redis. No domain code yet; this proves the path end to end.

Prerequisites

Tool	Version
Python	3.11, 3.12, or 3.13
copier	9.4.0 or newer
Docker	20.10+ (for PostgreSQL and Redis)
PostgreSQL	14+ (provided by the generated compose file)
Redis	6+ (provided by the generated compose file)

Install copier with pip install copier, pipx install copier, or uv tool install copier.

1. Generate the actor

copier copy https://github.com/allcare/kaboum my-first-actor --defaults --trust

With --defaults, you answer exactly two questions:

• project_name — lowercase, digits, and underscores; starts with a letter; at most 31 characters (for example myfirst).
• domain_module — your actor’s domain directory, for example tasks. Reserved names are rejected: mesh, agent, api, core, kaoohi, shared, integrations, middleware, models, storage.

Everything else — agent framework, Python version, marketplace metadata — sensible defaults apply. You now have a complete project in my-first-actor/.

2. Install it

cd my-first-actor
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Activate the virtual environment and keep it activated: the Makefile calls python directly, so make targets fail with “python: No such file or directory” if the environment is not on your path.

3. Verify the config

The actor’s src/kaoohi/config.json is derived from your settings and pyproject metadata — never hand-edit it. One target emits it and checks it:

make kaoohi-config

This runs the emitter, then a freshness check. On a fresh render the file does not exist yet, so python -m src.kaoohi.config_emitter --check alone fails until the first emit — prefer make kaoohi-config, which does both.

4. Run the quality gates

ruff check .
pytest -q

Both must pass before you change anything. The unit suite needs no database — on the template at verification time it ran 281 tests in under a minute.

5. Run it locally

Start PostgreSQL and Redis, then the actor:

docker compose up -d postgres redis
make run

make run starts uvicorn on port 8080. Check liveness:

curl http://localhost:8080/health

You should get a 200 with the actor’s status and version. /ready and /metrics are there too, and POST /agent/invoke is the chat endpoint. Point your browser at http://localhost:8080/docs for the full interactive API.

Note: the app requires PostgreSQL to start; Redis and auth failures degrade to warnings instead of crashing.

What’s next

• ](en/track-a/setup-and-generate/): add real domain code — models, a client, tools, migrations — at the seven extension points.
• ](en/publishing/): build the image, push it to a registry, and register the actor on Kaoohi.

---

Last verified: 2026-10-13, against kaboum commit fbee633.

Steps actually run: rendered with copier copy <kaboum checkout> quickstart-verify --vcs-ref=HEAD --data project_name=kquick --data domain_module=quickdemo --defaults --trust (local path, same template content); pip install -e ".[dev]" in a fresh venv (clean); make kaoohi-config (emit + check pass, venv activated); ruff check . (clean); pytest -q (281 passed, 6 skipped, no Docker needed). Two findings folded into the steps above: the Makefile needs the venv activated, and the emitter --check fails before the first emit. The GitHub-URL form in step 1 matches the template’s documented flow (generate from a git ref so copier update works later); the URL render itself was not re-run in this verification.