A framework for agents, released as nightlies under a custom licence

A licence identifier that resolves to nothing

The package metadata declares `license = "LicenseRef-KohakuTerrarium-1.0"` with a comment explaining that the SPDX LicenseRef form is required by Briefcase 0.3.21 and later, and points at a LICENSE file for the terms. That is a custom licence, not an OSI identifier, and the repository's own licence field resolves to nothing a tool can classify. For a package meant to be embedded in other agents and products, that is the first thing to read, because there is no standard grant or reciprocity clause you can assume. Version 2.1.4 in the manifest and a Development Status of Beta alongside it describe a project with a real surface and an unsettled one.

Release tags are dates, not versions

The release history is three consecutive tags named nightly-20261002, nightly-20261001 and nightly-20260930, each published in the morning of that day, with the newest one dated the day this article was written. That is a nightly channel rather than a version history: useful for catching a change the moment it lands, awkward for pinning, since there is no semantic version to write into a lockfile beyond the manifest's own 2.1.4. Anyone reproducing a deployment later needs the date of the nightly they ran rather than a tag like 1.4.0, and the changelog trail has to come from the commit history instead.

A creature is six modules, and a terrarium is the graph around them

The argument for the framework is stated plainly: several agent products each reimplement the same substrate, a controller loop, tool dispatch, triggers, sub-agents, sessions, persistence and multi-agent wiring, and every new agent shape costs a ground-up reimplementation. KohakuTerrarium puts that substrate in one place. The unit is the creature, a standalone agent built from six modules: a controller as the reasoning loop, input, output, tools, triggers and sub-agents. Above that sits the Terrarium, a graph runtime owning channels, lifecycle, output wiring, hot-plug and the topology and session bookkeeping that follows a graph change. A Studio layer handles catalog, identity, active sessions, persistence and the management surfaces, and an optional Laboratory transport layer can split host and engine across machines over a WebSocket hop without changing the other two. The framework also draws a line about where it sits: most tooling lives below the agent layer or jumps straight to multi-agent orchestration, with a thin idea of what a single agent is. LangChain, LangGraph and Dify appear in the application row of its own comparison, DSPy as a utility, smolagents as the one other framework it names, and CrewAI and AutoGen in the multi-agent row.

Four lines of Python is the whole library surface

The library path is deliberately short:

from kohakuterrarium import Agent

agent = await Agent.build("@kt-biome/creatures/swe")
await agent.start()
result = await agent.run("Explain what this codebase does.")  # -> TurnResult
print(result.text, result.usage)

An agent is an object you await, built from a package reference rather than assembled by hand, and a turn returns a typed result carrying text and token usage. The Python API section makes three promises worth checking in your own code: timeouts on turns that actually cancel rather than leaking a task, streaming typed events, and strict-by-default errors instead of silent fallbacks. Any function becomes a tool through a decorator, and an LLM instance can be injected directly when you want to control the model yourself.

Sessions the engine owns, and history you can search

Session handling is delegated to the engine rather than to your code: it mints and owns the session files, either through a session argument or a Terrarium configured with a session directory, and a run can be picked up hours later with `kt resume` or `Terrarium.resume`, with `kt resume --last` for the most recent one. A `SessionReader` replays a finished run offline, which matters when you want to inspect what an agent did without spending a model call. Every event is indexed, so `kt search` and the `search_memory` tool can look up past work from the command line or from inside the agent, and context compaction runs in the background so a long run keeps working while its context shrinks. The built-in toolset is broad rather than minimal: file, shell, web, JSON, notebook, search, editing, planning, review and research tools, plus graph-editor tools exposed only on privileged nodes, which is the mechanism behind the optional authentication layers.

The dependency pins are shaped by an Android build

The dependency list explains itself in comments, and the reasons are not aesthetic. pydantic is held below 2.13 and pydantic-core below 2.42 to match the Android wheel the project ships, and jiter, rpds-py, safetensors, tokenizers and primp are declared as direct dependencies even though they arrive transitively, so the Android build emits a wheel URL reference for each of them, all of them being Rust or PyO3 packages with no Chaquopy wheel. libcst takes a deliberately wide pin because PyPI serves 1.x on the desktop and Chaquopy serves 0.3.23 on Android while the codegen API stays stable across both. If you are not shipping to Android, you are paying for someone else's build matrix in your lockfile.

Four auth layers, all off, plus MCP and a package market

Authentication is opt-in per layer and the default is everything off: a host token, an admin password and multi-user accounts. The point is that an agent runtime reachable from a network is dangerous by default and this one says so. On integration, MCP servers attach per agent or globally over stdio or streamable HTTP, with four meta-tools so the prompt does not grow with the number of servers. Packages resolve through a marketplace, `kt install @name`, with an idempotent script-side primitive for ensuring a package is present, and composition uses operators for sequencing, conjunction, branching, fan-out and iteration. Runtime surfaces come out of the box: CLI, TUI, web dashboard and a native desktop app.

Where KohakuTerrarium is the wrong tool

The project answers this itself, in a section called boundaries, and the honesty is worth more than the feature list. It says you do not want this if an existing agent product already covers stable requirements, because the value here is rebuilding the substrate for a shape that product does not have. It says the same if the model in your head does not map onto controller, tools, triggers, sub-agents and channels, since a framework whose vocabulary does not fit is pure overhead. And it rules itself out if you need sub-50 ms per-operation latency. The documentation is trilingual, with English, Traditional Chinese and Simplified Chinese readmes, and the repository carries docs, examples split into agent apps, code, deployment, plugins and terrariums, an extensions directory and a docker directory. On top of that sits the licence question and the nightly release channel, which together mean a decision to adopt is also a decision to track someone else's release cadence.

Editorial conclusion

KohakuTerrarium fits a team that keeps needing new agent shapes and does not want to rebuild a controller loop, tool dispatch, triggers, sessions and sub-agent wiring each time, and that is comfortable maintaining a framework dependency. It does not fit a team whose needs are stable enough for an existing agent product, nor one that needs sub-50 ms operations. Verify three things before adopting it: what the custom KohakuTerrarium-1.0 licence actually permits, since no tool can classify it; which nightly build you pinned, because the tags carry dates rather than versions; and which Python version you standardise on, given 3.12 is what CI validates.

Frequently asked questions

Official sources

1. Issues
2. Kohaku-Lab/KohakuTerrarium on GitHub
3. Project website
4. README
5. Releases