KohakuTerrarium

KohakuTerrarium is a general-purpose AI agent framework and batteries-included app for building, running, and composing self-contained agents and multi-agent te

What is KohakuTerrarium?

KohakuTerrarium is a general-purpose AI agent framework and batteries-included app for building, running, and composing self-contained agents and multi-agent teams, with built-in tools, sub-agents, persistent sessions, TUI, and web UI.

Overview of KohakuTerrarium

What it is

KohakuTerrarium is a general-purpose AI agent framework and batteries-included app for building, running, and composing self-contained agents and multi-agent teams. It provides a substrate that includes a controller loop, tool dispatch, triggers, sub-agents, sessions, persistence, and multi-agent wiring, so that new agent shapes can be created with a config file and custom modules rather than a full reimplementation. The core abstraction is the creature, a standalone agent with its own controller, tools, sub-agents, triggers, memory, and I/O, hosted by a Terrarium engine. A Studio layer provides catalog, identity, session management, and web/desktop/API surfaces. Everything is Python, and agents are objects that can be awaited with typed results.

Key features

  • Agent-level abstraction: the six-module creature model is the first-class concept; a new agent shape requires a config and possibly a few custom modules.
  • A real Python API: Agent.build, typed TurnResult with timeouts that cancel, streaming typed events, @kt.tool to turn any function into an agent tool, direct LLM-instance injection, strict-by-default errors.
  • Built-in session persistence and resume: the engine mints and owns session files; resume hours later with kt resume or Terrarium.resume; SessionReader replays finished runs offline.
  • Searchable session history: every event is indexed; kt search and the search_memory tool allow lookup of past work.
  • Non-blocking context compaction: long-running agents keep working while context compacts in the background.
  • Comprehensive built-in tools and sub-agents: file, shell, web, JSON, notebook, search, editing, planning, review, research, plus graph-editor tools on privileged nodes.
  • MCP support: connect stdio/streamable-HTTP MCP servers per-agent or globally; four meta-tools keep the prompt small regardless of server count.
  • Package system and marketplace: kt install @name resolves through TerrariumMarket; kohakuterrarium.packages.ensure is the idempotent script-side primitive.
  • Composition algebra: >>, &, |, *, .iterate operators for stitching agents into pipelines.
  • Multiple runtime surfaces: CLI, TUI, web dashboard, and native desktop app out of the box.
  • Optional four-layer authentication: host token, admin password, and multi-user accounts; opt in per layer; default is everything off.

Use cases

KohakuTerrarium is suited for building new agent shapes without rebuilding the underlying substrate, for using strong out-of-the-box agents that can be customized, for driving agents from Python code in batch jobs, bots, or pipelines, and for scenarios where requirements are still evolving. It is less suitable if an existing agent product already fits stable needs, if the mental model does not map onto controller/tools/triggers/sub-agents/channels, or if sub-50 ms per-operation latency is required.

Getting started

bashpip install kohakuterrariumkt login codexkt install @kt-biomekt run @kt-biome/creatures/swe --mode cli

License and pricing

The license is not stated in the provided metadata or README. The project is listed as open source with pricing type open_source.

Based on the project's public README and repository metadata.

Add this badge to your README

Featured on YunoDB Badge styles & help

Maintain this project? Show that it is featured on YunoDB.

Markdown[![Featured on YunoDB](https://yunodb.com/badge/kohaku-labkohakuterrarium.svg)](https://yunodb.com/tools/kohaku-labkohakuterrarium?utm_source=github&utm_medium=badge)
HTML<a href="https://yunodb.com/tools/kohaku-labkohakuterrarium?utm_source=github&utm_medium=badge"><img src="https://yunodb.com/badge/kohaku-labkohakuterrarium.svg" alt="Featured on YunoDB" height="20"></a>