kith
A scalable server framework for real-time, stateful multiplayer worlds.
A C23 core owns the performance-critical systems: transport, the reactor, spatial indexing, the world stream fabric, and the simulation. Game logic extends the core in Python. Simulation models that need more than Python speed ship as C shared libraries against the same ABI. The core also runs independently: it installs headers and CMake targets, and examples/minimal boots a server with no Python.
The world is divided into cells that publish state once; gateways subscribe to cells and compose a per-player view. The fabric carries that stream. The same game code runs as a single embedded process or as a distributed cluster; the topology is a constructor argument.
kith fits real-time, stateful worlds under high concurrency: movement, presence, spatial queries, world state streamed to every connected client. A turn-based or request/response game gains little from it; state moves on a simulation cadence.
The framework runs on Linux only; the reactor is io_uring. It ships without accounts, authentication, matchmaking, or billing; those services belong to the game.
Capabilities
- Five-plane fabric: Sim, Fabric, Gateway, Coord, Control, with the data-flow contracts between planes enforced by CI.
- Pluggable components within planes: sim models, database queries, wire types, control routes, and delivery presets register behind their plane's contract.
- Switchable topologies: embedded single-process, distributed multi-instance, one build.
- Deterministic simulation with replay files and state-hash coverage.
- Free-threaded Python: handlers dispatch on a worker pool off the reactor; runs on standard and free-threaded Python 3.14 and 3.15 interpreters.
- Additive C ABI: opaque types, size-versioned structs, an ABI-diff gate.
- Hardened builds by default: PIE, RELRO, stack canaries, CFI, NX.
- Agentic testing: headless clients drive setup, act, assert, diagnose.
- One observability contract: structured logging, metrics, tracing.
Quickstart: run the release
Tagged releases ship a binary wheel, the sdist, and SHA256 checksums on the releases page. The wheel bundles the compiled core; boot an embedded server:
uv venv --python 3.14 .venv
source .venv/bin/activate
uv pip install --python .venv kith_fw-1.1.0-py3-none-manylinux_2_38_x86_64.whl
The PyPI distribution is kith-fw; the module you import is kith.
from kith import Server
with Server(topology="embedded") as server:
print(f"kith: gateway={server.listen_port}")
server.serve() # blocks; Ctrl-C stops it cleanly
The getting started guide continues from that boot: handlers, control routes, persistence, the two-instance cluster.
The released wheel also ships a visual example with ambient actors and a graphical client. Start it with one command:
pip install "kith-fw[visual]"
kith-visual play crowd-in # bots converge on your cell; watch the HUD
Quickstart: build from source
git clone https://github.com/pianosuki/kith kith && cd kith
./scripts/setup.sh # preflight, git config, uv sync, hooks
source .venv/bin/activate
cmake --preset release && cmake --build build/release
python -m examples.free_movement.server # prints: free_movement: gateway=… control=…
In a second terminal, drive the running server over its control plane:
curl -X POST http://127.0.0.1:<control>/spawn # {"actor_id": 1}
curl http://127.0.0.1:<control>/query_state # the actor's live state
./scripts/verify.sh is the same gate CI runs: lint, commits, build,
free-threaded. From a verified tree, CONTRIBUTING.md is the
contributor workflow.
C consumers
From a built tree, install the headers and libraries:
cmake --install build/release --prefix /opt/kith
A downstream CMake project configures with the prefix on its search path
(-DCMAKE_PREFIX_PATH=/opt/kith) and links the imported targets. kith::server
is the composition root a game links against; every plane library also has an
imported target:
find_package(kith 1.0.0 REQUIRED)
target_link_libraries(my_game PRIVATE kith::server)
This accepts compatible 1.x releases from 1.0.0 onward. Projects using APIs
introduced in 1.1 should request 1.1.0 instead, and so on.
Hand-written Makefiles and autotools consume the pkg-config entry point:
PKG_CONFIG_PATH=/opt/kith/lib/pkgconfig pkg-config --cflags --libs kith
tests/consumer/ is a minimal downstream project that exercises both channels
in CI.
Requirements
- Linux, x86-64, glibc 2.38 or newer.
import kithraises a load error on any other platform. - Python 3.14 and 3.15, standard or free-threaded builds. The package minimum remains 3.14; later minor versions require compatibility validation.
- Release wheel: native dependencies outside the manylinux policy are bundled
with the framework. Local wheels and source installs use the build host's
liburing,libpqandlibhiredisABI; install their development packages before building. See the release guide. - Source path: Clang 22+ (or GCC 14+), clang-format-23 (the pinned formatter:
uv tool install clang-format==23.1.5, then symlink~/.local/bin/clang-formatasclang-format-23), CMake 4.4+, Ninja 1.13+,uv,pre-commit.
Stability
Releases follow Semantic Versioning from 1.0.0. The public C ABI evolves additively: public types stay opaque, parameter structs carry size and ABI-version fields, and an ABI-diff gate guards every header change (ADR-0008). The Python API is the ctypes binding of that ABI, generated from the same headers, with no separate version line: a change that breaks the C ABI breaks Python with it, and both use the project version.
Deprecations preserve the existing interface; removals require a major release.
The decision records under docs/architecture/adr/ are frozen at 1.0.0 and
evolve only by supersession or explicit amendment, not by external contribution.
Documentation
- API reference, by symbol: the Doxygen reference rendered from the public headers.
- Guides, by task: getting started, Python extensions, C simulation models, scaling gates, agentic headless clients, the wire protocol, the publish choreography, operations, replay format.
- Architecture, by contract: planes, layers, topologies, tracing, performance budgets, event schema, and the decision records.
Contributing
CONTRIBUTING.md is the workflow; AGENTS.md is the coding standard and review checklist. CODE_OF_CONDUCT.md governs participation; SECURITY.md takes private vulnerability reports. General issues and questions are answered best-effort by the single maintainer, with no response-time guarantee; vulnerability reports carry their own channel and expectations in SECURITY.md.
License
Apache License, Version 2.0. See LICENSE for the full text.
Metadata
Release files for kith-fw 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kith_fw-1.1.0.tar.gz | 640.9 kB | With provenance | Details for kith_fw-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kith_fw-1.1.0-py3-none-manylinux_2_38_x86_64.whl | Python 3 | none | Linux glibc 2.38+ x86-64 | Details for kith_fw-1.1.0-py3-none-manylinux_2_38_x86_64.whl |
Total release size: 3.8 MB
Release files / kith_fw-1.1.0.tar.gz
| Download URL | kith_fw-1.1.0.tar.gz |
|---|---|
| Size | 640.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c61e1cc5d4405896efa88328161e8c35ab3d36623c06cfa0d1913e841c63e5a
|
|
BLAKE2b-256 checksum How to use checksums |
dd55d75a5f86b4e46ab4b74f0fb7e65cdc230b8f3f2b918805bac72cb14b2adc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / kith_fw-1.1.0-py3-none-manylinux_2_38_x86_64.whl
| Download URL | kith_fw-1.1.0-py3-none-manylinux_2_38_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Linux glibc 2.38+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
e0f57982f5a7083197042d1c26cc4c42307b2e119c066887c00665beaf27c116
|
|
BLAKE2b-256 checksum How to use checksums |
9ff8891e5facc5abc424e94812d01d19255104debec128ba2611a2fc6557e8c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logSecurity for kith-fw 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kith_fw-1.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.