{"id":49046963,"url":"https://github.com/kohaku-lab/kohakuterrarium","last_synced_at":"2026-05-26T08:04:36.142Z","repository":{"id":347348511,"uuid":"1131778810","full_name":"Kohaku-Lab/KohakuTerrarium","owner":"Kohaku-Lab","description":"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.","archived":false,"fork":false,"pushed_at":"2026-05-17T19:01:11.000Z","size":47944,"stargazers_count":328,"open_issues_count":2,"forks_count":41,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-17T21:29:26.549Z","etag":null,"topics":["agent","agentic-framework","llm"],"latest_commit_sha":null,"homepage":"https://terrarium.kohaku-lab.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kohaku-Lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-10T17:18:16.000Z","updated_at":"2026-05-17T19:01:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kohaku-Lab/KohakuTerrarium","commit_stats":null,"previous_names":["kohakublueleaf/kohakuterrarium"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Kohaku-Lab/KohakuTerrarium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2FKohakuTerrarium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2FKohakuTerrarium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2FKohakuTerrarium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2FKohakuTerrarium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kohaku-Lab","download_url":"https://codeload.github.com/Kohaku-Lab/KohakuTerrarium/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2FKohakuTerrarium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic-framework","llm"],"created_at":"2026-04-19T18:01:56.009Z","updated_at":"2026-05-23T19:01:18.280Z","avatar_url":"https://github.com/Kohaku-Lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/banner.png\" alt=\"KohakuTerrarium\" width=\"800\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe machine for building agents — so you stop rebuilding the machine every time you want a new one.\u003c/strong\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue\" alt=\"Python 3.10+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-KohakuTerrarium--1.0-green\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-1.4.0-orange\" alt=\"Version\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eEnglish\u003c/strong\u003e \u0026nbsp;·\u0026nbsp; \u003ca href=\"README.zh.md\"\u003e繁體中文\u003c/a\u003e \u0026nbsp;·\u0026nbsp; \u003ca href=\"README.zh-CN.md\"\u003e简体中文\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://terrarium.kohaku-lab.org\"\u003e\u003cstrong\u003eDocumentation\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## See it run (60 seconds)\n\n```bash\npip install kohakuterrarium                                         # install\nkt login codex                                                      # authenticate\nkt install https://github.com/Kohaku-Lab/kt-biome.git            # get OOTB creatures\nkt run @kt-biome/creatures/swe --mode cli                        # run one\n```\n\nYou get an interactive shell with a full coding agent — file tools, shell access, web search, sub-agents, resumable sessions. `Ctrl+D` exits; `kt resume --last` picks back up.\n\nWant more hand-holding? [Getting Started](docs/en/guides/getting-started.md). Want to build your own? [First Creature](docs/en/tutorials/first-creature.md).\n\n## Is this for you?\n\n**You probably want KohakuTerrarium if** you need a new agent shape and don't want to rebuild the substrate; you want OOTB creatures you can customise; you want to embed agent behaviour in existing Python; your requirements are still evolving.\n\n**You probably don't if** an existing agent product (Claude Code, Codex, …) already fits your stable needs; your mental model doesn't map onto controller / tools / triggers / sub-agents / channels; you need sub-50 ms per-operation latency. More honesty at [boundaries](docs/en/concepts/boundaries.md).\n\n## What KohakuTerrarium is\n\nKohakuTerrarium is a framework for building agents — not another agent.\n\nThe last two years produced a striking number of agent products: Claude Code, Codex, OpenClaw, Gemini CLI, Hermes Agent, OpenCode, and many more. They are genuinely different, and they all re-implement the same substrate from scratch: a controller loop, tool dispatch, trigger system, sub-agent mechanism, sessions, persistence, multi-agent wiring. Every new agent shape costs a new ground-up reimplementation of the plumbing.\n\nKohakuTerrarium's job is to put that substrate in one place so the next agent shape costs a config file and a few custom modules, not a new repo.\n\nThe core abstraction is the **creature**: a standalone agent with its own controller, tools, sub-agents, triggers, memory, and I/O. Creatures are hosted by a **Terrarium** engine: a graph runtime for channels, lifecycle, output wiring, hot-plug, and the topology + session bookkeeping that follows graph changes. A **Studio** layer sits above that for catalog, identity, active sessions, persistence, live traces, and web/desktop/API management. Optionally, a **Laboratory** transport layer can split host and engine across machines — Studio + Terrarium stay unchanged, with a WebSocket-based network hop slotted in between. Everything is Python, so agents can be embedded inside tools, triggers, plugins, and outputs of other agents.\n\nFor out-of-the-box creatures you can try today, see [**kt-biome**](https://github.com/Kohaku-Lab/kt-biome) — the showcase pack of useful agents and plugins built on top of the framework.\n\n## Where it fits\n\n|  | Product | Framework | Utility / Wrapper |\n|--|---------|-----------|-------------------|\n| **LLM App** | ChatGPT, Claude.ai | LangChain, LangGraph, Dify | DSPy |\n| **Agent** | ***kt-biome***, Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent… | ***KohakuTerrarium***, smolagents | — |\n| **Multi-Agent** | ***kt-biome*** | ***KohakuTerrarium***  | CrewAI, AutoGen |\n\nMost tooling sits below the agent layer or jumps straight to multi-agent orchestration with a thin idea of what an agent is. KohakuTerrarium starts with the agent itself.\n\nA creature is made of:\n\n- **Controller** — the reasoning loop\n- **Input** — how events enter the agent\n- **Output** — how results leave the agent\n- **Tools** — what actions it can take\n- **Triggers** — what wakes it up\n- **Sub-agents** — internal delegation for specialised tasks\n\nA terrarium composes multiple creatures horizontally through channels, lifecycle management, and observability.\n\n## Key features\n\n- **Agent-level abstraction.** The six-module creature model is the first-class concept. Every new agent shape is \"write a config and maybe a few custom modules,\" not \"rebuild the runtime.\"\n- **Built-in session persistence and resume.** Sessions store operational state, not just chat history. Resume a run hours later with `kt resume`.\n- **Searchable session history.** Every event is indexed. `kt search` and the `search_memory` tool let you (and the agent) look up past work.\n- **Non-blocking context compaction.** Long-running agents keep working while context is compacted in the background.\n- **Comprehensive built-in tools and sub-agents.** File, shell, web, JSON, notebook/Jupyter, search, editing, planning, review, research, plus the `group_*` graph-editor tools registered on privileged nodes.\n- **MCP support.** Connect stdio, streamable HTTP, or legacy SSE/HTTP MCP servers per-agent or globally; tools surface in the prompt automatically.\n- **Package system.** Install creatures / terrariums / plugins / LLM presets from Git or local paths; compose installed packages with inheritance.\n- **Python-native.** Agents are async Python objects. Embed them inside tools, triggers, plugins, or outputs of other agents.\n- **Composition algebra.** `\u003e\u003e`, `\u0026`, `|`, `*`, `.iterate` operators for stitching agents into pipelines programmatically.\n- **Multiple runtime surfaces.** CLI, TUI, web dashboard, and desktop app out of the box.\n- **Optional four-layer auth.** Host token, admin password, multi-user accounts — opt in per layer for LAN / family-server / internet-exposed deployments. Defaults are everything off (current single-user behaviour preserved). See [Authentication](docs/en/guides/authentication.md).\n- **Useful OOTB creatures via [`kt-biome`](https://github.com/Kohaku-Lab/kt-biome).** Start by running strong default agents; customise or inherit from them later.\n\n## Quick start\n\n\u003e **Recommended Python version**: 3.12 or newer. CI validates 3.12+ only; 3.10 and 3.11 still install and run (`requires-python = \"\u003e=3.10\"`) but are supported best-effort — older asyncio + SQLite-daemon-thread interaction is slower and the integration suite occasionally times out on those runtimes.\n\n### 1. Install KohakuTerrarium\n\n```bash\n# From PyPI\npip install kohakuterrarium\n# Optional extras: pip install \"kohakuterrarium[full]\"\n\n# Or from source (for development — uv is the project convention)\ngit clone https://github.com/Kohaku-Lab/KohakuTerrarium.git\ncd KohakuTerrarium\nuv pip install -e \".[dev]\"\n\n# Build the web frontend (required for `kt web` / `kt app` from source)\nnpm install --prefix src/kohakuterrarium-frontend\nnpm run build --prefix src/kohakuterrarium-frontend\n```\n\n### 2. Install OOTB creatures and plugins\n\n```bash\n# Official showcase pack\nkt install https://github.com/Kohaku-Lab/kt-biome.git\n\n# Any third-party package\nkt install \u003cgit-url\u003e\nkt install ./my-creatures -e        # editable install\n```\n\n### 3. Authenticate a model provider\n\n```bash\n# Codex OAuth (ChatGPT subscription)\nkt login codex\nkt model default gpt-5.4\n\n# Or native Anthropic / OpenAI-compatible providers via `kt config llm add`\n```\n\nSupports Codex OAuth, OpenRouter/OpenAI, native Anthropic, Google Gemini, and any OpenAI-compatible API.\n\n### 4. Run something\n\n```bash\n# Single creature\nkt run @kt-biome/creatures/swe --mode cli\nkt run @kt-biome/creatures/researcher\n\n# Multi-agent terrarium\nkt terrarium run @kt-biome/terrariums/swe_team\n\n# Web dashboard\nkt serve start\n\n# Native desktop\nkt app\n```\n\n## Choose your path\n\n### I want to run something now\n\n- [Getting Started](docs/en/guides/getting-started.md)\n- [`kt-biome`](https://github.com/Kohaku-Lab/kt-biome)\n- [CLI Reference](docs/en/reference/cli.md)\n- [Examples](examples/README.md)\n\n### I want to build my own creature\n\n- [First Creature tutorial](docs/en/tutorials/first-creature.md)\n- [Creatures guide](docs/en/guides/creatures.md)\n- [Custom Modules](docs/en/guides/custom-modules.md)\n- [Plugins](docs/en/guides/plugins.md)\n- [First Custom Tool tutorial](docs/en/tutorials/first-custom-tool.md)\n\n### I want multi-agent composition\n\n- [First Terrarium tutorial](docs/en/tutorials/first-terrarium.md)\n- [Terrariums guide](docs/en/guides/terrariums.md)\n- [Multi-agent concept](docs/en/concepts/multi-agent/README.md)\n\n### I want to embed it in Python\n\n- [First Python Embedding tutorial](docs/en/tutorials/first-python-embedding.md)\n- [Programmatic Usage](docs/en/guides/programmatic-usage.md)\n- [Composition Algebra](docs/en/guides/composition.md)\n- [Python API](docs/en/reference/python.md)\n\n### I want to understand what's going on\n\n- [Concept docs](docs/en/concepts/README.md)\n- [Glossary](docs/en/concepts/glossary.md) — plain-English definitions\n- [Why KohakuTerrarium](docs/en/concepts/foundations/why-kohakuterrarium.md)\n- [What is an agent](docs/en/concepts/foundations/what-is-an-agent.md)\n\n### I want to deploy it\n\n- [Deployment — Docker](docs/en/guides/deployment-docker.md) — AIO, host + workers, distributed compose recipes\n- [Deployment — systemd](docs/en/guides/deployment-systemd.md) — `kt service install` + hardened units\n- [Deployment — reverse proxy](docs/en/guides/deployment-reverse-proxy.md) — nginx / Cloudflare Tunnel + TLS\n- [Laboratory](docs/en/guides/laboratory.md) — multi-node lab-host / lab-client model\n\n### I want to work on the framework itself\n\n- [Development home](docs/en/dev/README.md)\n- [Internals](docs/en/dev/internals.md)\n- [Testing](docs/en/dev/testing.md)\n- Package READMEs under [`src/kohakuterrarium/`](src/kohakuterrarium/README.md)\n\n## Core mental model\n\n### Creature\n\n```text\n    List, Create, Delete  +------------------+\n                    +-----|   Tools System   |\n      +---------+   |     +------------------+\n      |  Input  |   |          ^        |\n      +---------+   V          |        v\n        |   +---------+   +------------------+   +--------+\n        +--\u003e| Trigger |--\u003e|    Controller    |--\u003e| Output |\nUser input  | System  |   |    (Main LLM)    |   +--------+\n            +---------+   +------------------+\n                              |          ^\n                              v          |\n                          +------------------+\n                          |    Sub Agents    |\n                          +------------------+\n```\n\nA creature is a standalone agent with its own runtime, tools, sub-agents, prompts, and state.\n\n```bash\nkt run path/to/creature\nkt run @package/path/to/creature\n```\n\n### Runtime hierarchy\n\n```text\nUser / API / Desktop\n        |\n        v\n+----------------------+     no reasoning loop\n| Studio / App Layer   |  catalog, identity, active sessions,\n|                      |  persistence, attach, editors, live traces\n+----------------------+\n        |\n        v\n+----------------------+     optional: only in multi-node mode\n| Laboratory (Lab)     |  WebSocket transport + custom envelope,\n|                      |  spans the host across N worker machines\n+----------------------+     transparent to Studio + Terrarium\n        |\n        v\n+----------------------+     no LLM; owns structure\n| Terrarium Engine     |  creature graph, topology, channels,\n|                      |  hot-plug, output wiring, session\n|                      |  merge / split bookkeeping\n+----------+-----------+\n           |\n   +-------+----------------+\n   |                        |\nPrivileged node         Worker creatures\n(user-facing, group     swe / coder / reviewer / ...\n tools, designated by\n recipe `root:`)\n   |\n   v\nSub-agents inside each creature\n(vertical/private delegation)\n```\n\n- **Studio** is the management framework used by the web dashboard, desktop app, and HTTP API. It owns catalog views, identity/settings, active sessions, persistence, attach/resume, editors, and live traces. It does not reason.\n- **Laboratory (Lab)** is the optional network layer between Studio and Terrarium. In single-machine mode it is not even imported. In `--mode lab-host` it lets one host coordinate creatures on N worker machines via WebSocket: Studio still calls one `TerrariumService`, Terrarium still ships local channel sends, but a `MultiNodeTerrariumService` routes per-creature ops to the right worker and a session-event tee mirrors every worker's session file back to the host. See [Laboratory concept](docs/en/concepts/laboratory.md) and the [Laboratory guide](docs/en/guides/laboratory.md).\n- **Terrarium** is the runtime engine that hosts every running creature in the process. A standalone agent is a one-creature graph; a multi-creature team is a connected graph. The engine runs no LLM and has no reasoning loop, but it owns *structure*: which creatures share a connected component, which channels exist, where each turn-end output is delivered, which session store backs which graph, and the auto-merge / auto-split bookkeeping that follows topology changes.\n- **Privileged node** is a creature inside a graph that has been granted the `group_*` tools (graph editor: spawn / remove creatures, draw / delete channels, start / stop members). The recipe `root:` keyword promotes one node to privileged + applies the standard user-facing wiring (`report_to_root` channel, listen on every channel). Privilege can also be granted inline (`privileged: true`) or imperatively (`is_privileged=True`).\n- **Creature** owns reasoning: controller, tools, triggers, sub-agents, plugins, memory, I/O, prompts, and private state. Creatures do not need to know whether they are alone or part of a graph.\n- **Sub-agents** are vertical/private delegation inside one creature. Prefer them when one controller can decompose the task internally; use Terrarium when multiple peer creatures need horizontal cooperation.\n\n### Channels and output wiring\n\nChannels and output wiring are the horizontal cooperation substrate between creatures:\n\n- **Channel** — named broadcast pipe. Every listener subscribed to it receives every send. Use for conditional / optional / observed traffic.\n- **Output wiring** — deterministic pipeline edges that auto-deliver a creature's turn-end output to named targets, no `send_message` required.\n\n### Modules\n\nA creature has six conceptual modules. **Five of them are user-extensible** — you swap their implementations in config or in Python. The sixth, the controller, is the reasoning loop that drives them; you rarely swap it (and when you do, you're writing the framework's successor).\n\n| Module | What it does | Example custom use |\n|--------|---------------|--------------------|\n| **Input** | Receives external events | Discord listener, webhook, voice input |\n| **Output** | Delivers agent output | Discord sender, TTS, file writer |\n| **Tool** | Executes actions | API calls, database access, RAG retrieval |\n| **Trigger** | Generates automatic events | Timer, scheduler, channel watcher |\n| **Sub-agent** | Delegated task execution | Planning, code review, research |\n\nPlus **plugins**, which modify the connections *between* modules without forking them (prompt plugins, lifecycle hooks). See [plugins guide](docs/en/guides/plugins.md).\n\n### Environment and session\n\n- **Environment** — shared terrarium state (shared channels).\n- **Session** — private creature state (scratchpad, private channels, sub-agent state).\n\nPrivate by default, shared by opt-in.\n\n## Practical capabilities\n\nKohakuTerrarium already ships:\n\n- Built-in file, shell, web, JSON, notebook/Jupyter, channel, trigger, and introspection tools, including single-edit and multi-edit file mutation primitives.\n- Built-in sub-agents for exploration, planning, implementation, review, summarisation, and research.\n- Background tool execution and non-blocking agent flow.\n- Session persistence with resumable operational state.\n- FTS + vector memory search (model2vec / sentence-transformer / API embedding providers).\n- Non-blocking auto-compaction for long-running agents.\n- MCP (Model Context Protocol) integration — stdio, streamable HTTP, and legacy SSE/HTTP transports.\n- Package manager for creatures, plugins, terrariums, and reusable agent packs (`kt install`, `kt update`).\n- Python embedding through the `Terrarium` engine plus lower-level `Agent` access.\n- HTTP and WebSocket serving.\n- Web dashboard and native desktop app.\n- Custom module and plugin systems.\n\n## Programmatic usage\n\nAgents are async Python values. One `Terrarium` engine per process hosts every running creature — a standalone agent is just a 1-creature graph in the engine.\n\n```python\nimport asyncio\nfrom kohakuterrarium import Terrarium\n\nasync def main():\n    # Solo creature\n    engine, alice = await Terrarium.with_creature(\"@kt-biome/creatures/swe\")\n    try:\n        async for chunk in alice.chat(\"Explain what this codebase does.\"):\n            print(chunk, end=\"\", flush=True)\n    finally:\n        await engine.shutdown()\n\n    # Multi-agent recipe\n    engine = await Terrarium.from_recipe(\"@kt-biome/terrariums/swe_team\")\n    try:\n        async for chunk in engine[\"swe\"].chat(\"Fix the auth bug.\"):\n            print(chunk, end=\"\", flush=True)\n    finally:\n        await engine.shutdown()\n\nasyncio.run(main())\n```\n\n### Composition algebra\n\nBecause agents are Python values, they compose with operators. `\u003e\u003e` (sequence), `\u0026` (parallel), `|` (fallback), `*N` (retry), `.iterate` (async loop):\n\n```python\nimport asyncio\nfrom kohakuterrarium.compose import agent, factory\nfrom kohakuterrarium.core.config import load_agent_config\n\ndef make_agent(name, prompt):\n    config = load_agent_config(\"@kt-biome/creatures/general\")\n    config.name, config.system_prompt, config.tools, config.subagents = name, prompt, [], []\n    return config\n\nasync def main():\n    # Persistent agents (accumulate conversation)\n    async with await agent(make_agent(\"writer\", \"You are a writer.\")) as writer, \\\n               await agent(make_agent(\"reviewer\", \"You are a strict reviewer. Say APPROVED if good.\")) as reviewer:\n\n        pipeline = writer \u003e\u003e (lambda text: f\"Review this:\\n{text}\") \u003e\u003e reviewer\n\n        async for feedback in pipeline.iterate(\"Write a haiku about coding\"):\n            print(f\"Reviewer: {feedback[:100]}\")\n            if \"APPROVED\" in feedback:\n                break\n\n    # Parallel ensemble with retry + fallback\n    fast = factory(make_agent(\"fast\", \"Answer concisely.\"))\n    deep = factory(make_agent(\"deep\", \"Answer thoroughly.\"))\n    safe = (fast \u0026 deep) \u003e\u003e (lambda results: max(results, key=len))\n    safe_with_retry = (safe * 2) | fast\n    print(await safe_with_retry(\"What is recursion?\"))\n\nasyncio.run(main())\n```\n\nMore: [Programmatic Usage](docs/en/guides/programmatic-usage.md), [Composition](docs/en/guides/composition.md), [Python API](docs/en/reference/python.md), and [`examples/code/`](examples/).\n\n## Runtime surfaces\n\n### CLI and TUI\n\n- **cli** — rich inline terminal experience\n- **tui** — full-screen Textual application\n- **plain** — simple stdout/stdin for pipes and CI\n\nSee [CLI Reference](docs/en/reference/cli.md).\n\n### Web dashboard\n\nVue-based dashboard + FastAPI server backed by the Studio management layer.\n\n```bash\nkt web                       # one-shot, foreground\nkt serve start               # long-running daemon\n# Frontend dev: npm run dev --prefix src/kohakuterrarium-frontend\n```\n\nSee [HTTP API](docs/en/reference/http.md), [Serving guide](docs/en/guides/serving.md), [Frontend Architecture](docs/en/dev/frontend.md).\n\n### Desktop app\n\n`kt app` launches the web UI inside a native desktop window (requires `pywebview`).\n\n### Deployment (Docker / systemd / multi-node)\n\nThree first-party Docker images on GHCR — pick the shape:\n\n```bash\n# AIO: lab-host + an embedded worker in one container\ndocker run -d -p 8001:8001 -v kt:/home/kt/.kohakuterrarium \\\n  ghcr.io/kohaku-lab/kohakuterrarium:1.5.0\n\n# Host + workers (different boxes): two images, same shared token\ndocker run -d -p 8001:8001 -p 8100:8100 \\\n  -e KT_HOST_TOKEN=$TOKEN ghcr.io/kohaku-lab/kohakuterrarium-host:1.5.0\ndocker run -d -e KT_HOST_URL=ws://host:8100 -e KT_HOST_TOKEN=$TOKEN \\\n  -e KT_CLIENT_NAME=worker-a ghcr.io/kohaku-lab/kohakuterrarium-client:1.5.0\n```\n\nsystemd alternative — install a hardened native service in one command:\n\n```bash\nsudo kt service install --all                              # AIO unit\nsudo kt service install --host                             # host unit\nsudo kt service install --client --name worker-a --host-url ws://… --host-token …\nsudo systemctl enable --now kohakuterrarium-host kohakuterrarium-client@worker-a\n```\n\nReady-to-use compose files under `examples/deployment/` (AIO, host + workers, distributed) and an nginx template for TLS termination. `/healthz` + `/readyz` endpoints drive Docker `HEALTHCHECK` and reverse-proxy active health.\n\nSee [Deployment — Docker](docs/en/guides/deployment-docker.md), [Deployment — systemd](docs/en/guides/deployment-systemd.md), [Deployment — reverse proxy](docs/en/guides/deployment-reverse-proxy.md).\n\n## Sessions, memory, and resume\n\nSessions save to `~/.kohakuterrarium/sessions/` unless disabled.\n\n```bash\nkt resume            # pick interactively\nkt resume --last     # resume most recent\nkt resume swe_team   # resume by name prefix\n```\n\nThe same store powers searchable history:\n\n```bash\nkt embedding \u003csession\u003e                       # build FTS + vector indices\nkt search \u003csession\u003e \"auth bug fix\"           # hybrid/semantic/FTS search\n```\n\nAnd the agent can search its own history via the `search_memory` tool.\n\n`.kohakutr` files store conversation, tool calls, events, scratchpad, sub-agent state, channel messages, jobs, resumable triggers, and config metadata.\n\nSee [Sessions](docs/en/guides/sessions.md), [Memory](docs/en/guides/memory.md).\n\n## Packages, defaults, and examples\n\nCreatures are meant to be packaged, installed, reused, and shared.\n\n```bash\nkt install https://github.com/someone/cool-creatures.git\nkt install ./my-creatures -e\nkt list\nkt update --all\n```\n\nRun installed configs with package references:\n\n```bash\nkt run @cool-creatures/creatures/my-agent\nkt terrarium run @cool-creatures/terrariums/my-team\n```\n\nAvailable resources:\n\n- [`kt-biome/`](https://github.com/Kohaku-Lab/kt-biome) — official showcase creatures, terrariums, and plugin pack\n- `examples/agent-apps/` — config-driven creature examples\n- `examples/code/` — Python usage examples\n- `examples/terrariums/` — multi-agent examples\n- `examples/plugins/` — plugin examples\n\nSee [examples/README.md](examples/README.md).\n\n## Codebase map\n\n```text\nsrc/kohakuterrarium/\n  core/              # Agent runtime, controller, executor, events, environment\n  bootstrap/         # Agent initialisation factories (LLM, tools, I/O, triggers, plugins)\n  cli/               # `kt` command dispatcher\n  studio/            # Management facade: catalog, identity, sessions, persistence, attach, editors\n  terrarium/         # Runtime engine: creature graph, topology, channels, output wiring, hot-plug\n  builtins/          # Built-in tools, sub-agents, I/O modules, TUI, user commands, CLI UI\n  builtin_skills/    # Markdown skill manifests for on-demand docs\n  session/           # Session persistence, memory search, embeddings\n  serving/           # Launch/transport helpers and compatibility streaming wrappers\n  api/               # FastAPI HTTP + WebSocket adapters over Studio and Terrarium\n  compose/           # Composition algebra primitives\n  mcp/               # MCP client manager\n  modules/           # Base protocols for tools, inputs, outputs, triggers, sub-agents, user commands\n  llm/               # LLM providers, profiles, API key management\n  parsing/           # Tool-call parsing and stream handling\n  prompt/            # Prompt aggregation, plugins, skill loading\n  testing/           # Test infrastructure (ScriptedLLM, TestAgentBuilder, recorders)\n\nsrc/kohakuterrarium-frontend/   # Vue web frontend\nkt-biome/                    # (separate repo) Official OOTB pack\nexamples/                       # Example creatures, terrariums, code samples, plugins\ndocs/                           # Tutorials, guides, concepts, reference, dev\n```\n\nEvery subpackage has its own README describing files, dependency direction, and invariants.\n\n## Documentation map\n\nFull docs live in [`docs/`](docs/en/README.md).\n\n### Tutorials\n[First Creature](docs/en/tutorials/first-creature.md) · [First Terrarium](docs/en/tutorials/first-terrarium.md) · [First Python Embedding](docs/en/tutorials/first-python-embedding.md) · [First Custom Tool](docs/en/tutorials/first-custom-tool.md) · [First Plugin](docs/en/tutorials/first-plugin.md)\n\n### Guides\n[Getting Started](docs/en/guides/getting-started.md) · [Creatures](docs/en/guides/creatures.md) · [Terrariums](docs/en/guides/terrariums.md) · [Sessions](docs/en/guides/sessions.md) · [Memory](docs/en/guides/memory.md) · [Configuration](docs/en/guides/configuration.md) · [Programmatic Usage](docs/en/guides/programmatic-usage.md) · [Composition](docs/en/guides/composition.md) · [Custom Modules](docs/en/guides/custom-modules.md) · [Plugins](docs/en/guides/plugins.md) · [MCP](docs/en/guides/mcp.md) · [Packages](docs/en/guides/packages.md) · [Serving](docs/en/guides/serving.md) · [Laboratory](docs/en/guides/laboratory.md) · [Deployment — Docker](docs/en/guides/deployment-docker.md) · [Deployment — systemd](docs/en/guides/deployment-systemd.md) · [Deployment — reverse proxy](docs/en/guides/deployment-reverse-proxy.md) · [Examples](docs/en/guides/examples.md)\n\n### Concepts\n[Glossary](docs/en/concepts/glossary.md) · [Why KohakuTerrarium](docs/en/concepts/foundations/why-kohakuterrarium.md) · [What is an agent](docs/en/concepts/foundations/what-is-an-agent.md) · [Composing an agent](docs/en/concepts/foundations/composing-an-agent.md) · [Modules](docs/en/concepts/modules/README.md) · [Agent as a Python object](docs/en/concepts/python-native/agent-as-python-object.md) · [Composition algebra](docs/en/concepts/python-native/composition-algebra.md) · [Multi-agent](docs/en/concepts/multi-agent/README.md) · [Patterns](docs/en/concepts/patterns.md) · [Boundaries](docs/en/concepts/boundaries.md)\n\n### Reference\n[CLI](docs/en/reference/cli.md) · [HTTP](docs/en/reference/http.md) · [Python API](docs/en/reference/python.md) · [Configuration](docs/en/reference/configuration.md) · [Builtins](docs/en/reference/builtins.md) · [Plugin hooks](docs/en/reference/plugin-hooks.md)\n\n## Roadmap\n\nNear-term directions include more reliable terrarium flow, richer UI output / interaction modules across CLI / TUI / web, more built-in creatures, plugins, and integrations, and better daemon-backed workflows for long-running and remote usage. See [ROADMAP.md](ROADMAP.md).\n\n## Contributing\n\n- [Contributing docs](docs/en/dev/README.md)\n- [Testing](docs/en/dev/testing.md)\n- [Internals](docs/en/dev/internals.md)\n- [Frontend architecture](docs/en/dev/frontend.md)\n\n## License\n\n[KohakuTerrarium License 1.0](LICENSE): based on Apache-2.0 with naming and attribution requirements.\n\n- Derivative works must include `Kohaku` or `Terrarium` in their name.\n- Derivative works must provide visible attribution with a link to this project.\n\nCopyright 2024-2026 Shih-Ying Yeh (KohakuBlueLeaf) and contributors.\n\n## Community\n- QQ: 1097666427\n- Discord: https://discord.gg/xWYrkyvJ2s\n- Forum: https://linux.do/\n\n## FAQ\n\n### General\n\n**What is KohakuTerrarium?**\nKohakuTerrarium is a Python-native AI agent framework for building autonomous agents. The public hierarchy is: **Creature** for the agent unit, **Terrarium** for the runtime engine that owns the creature graph (topology, channels, sessions — no LLM of its own), and **Studio** for catalog / session / persistence / API management above the engine.\n\n**How does it differ from other agent frameworks?**\nUnlike monolithic frameworks, KohakuTerrarium keeps responsibilities separated: creatures own reasoning and tools, the Terrarium engine owns graph topology / channels / lifecycle / session bookkeeping, and Studio owns management surfaces. Horizontal teams use Terrarium recipes and channels; Python request pipelines can still use composition algebra.\n\n### Installation \u0026 Setup\n\n**What Python version is required?**\nPython 3.10 or higher. Install via `pip install kohakuterrarium`. **Python 3.12+ is recommended** — that's what CI validates and what the agent runtime is tuned for. 3.10 and 3.11 are supported on a best-effort basis (everything installs and runs, but the asyncio + SQLite-daemon-thread interaction on those older runtimes is slower and occasionally fights the per-test timeouts in the integration suite).\n\n**Which LLM providers are supported?**\nCodex OAuth, OpenAI/OpenRouter-style providers, native Anthropic, Google Gemini, local OpenAI-compatible servers (Ollama, vLLM), and other OpenAI-compatible cloud providers. Configure with `kt login`, `kt config llm add`, `kt config provider add`, or provider API keys.\n\n**Can I use local models?**\nYes. Point the LLM endpoint to your local server (Ollama, vLLM, etc.) and configure the model name in your creature configuration.\n\n### Core Concepts\n\n**What is a \"Creature\"?**\nA Creature is the standalone agent unit: controller, tools, triggers, sub-agents, plugins, memory, I/O, prompts, and private state. It can run alone or as a node in a Terrarium graph.\n\n**What is a \"Terrarium\"?**\nA Terrarium is the runtime engine that hosts creature graphs. It runs no LLM and has no reasoning loop, but it owns the structural decisions: connected components, channel registry, hot-plug, output wiring, session merge / split bookkeeping. Each creature still owns its controller, tools, memory, and private state.\n\n**What are \"Plugins\"?**\nPlugins extend the framework's capabilities — custom tools, I/O modules, triggers, or behavior hooks. They follow a hook-based system for clean integration.\n\n### Development\n\n**How do I create a custom Creature?**\nDefine a YAML configuration with tools, prompts, and behavior, or use the Python API to build one programmatically. See `docs/en/tutorials/first-creature.md` for a step-by-step guide.\n\n**Can I embed agents in my Python application?**\nYes. KohakuTerrarium provides a Python-native API for programmatic agent creation and execution. See `examples/code/` and `docs/en/guides/programmatic-usage.md`.\n\n**How does multi-agent composition work?**\nUse Terrarium recipes/engine channels/output wiring for horizontal multi-agent teams. Use `compose` for lightweight Python-side request pipelines (`\u003e\u003e`, `\u0026`, `|`, retry) when you do not need a long-lived graph. See `examples/terrariums/` and `examples/code/`.\n\n### Troubleshooting\n\n**Why is my creature not responding?**\nCheck that your LLM provider is configured correctly with `kt login`. Verify network connectivity and API key validity.\n\n**How do I debug agent behavior?**\nUse `kt run --verbose` for detailed logs. Resume or inspect prior work with `kt resume`, search it with `kt search`, or use the Studio session viewer in the web/desktop UI.\n\n**Where can I get help?**\n- QQ Group: 1097666427\n- Discord: https://discord.gg/xWYrkyvJ2s\n- Forum: https://linux.do/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkohaku-lab%2Fkohakuterrarium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkohaku-lab%2Fkohakuterrarium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkohaku-lab%2Fkohakuterrarium/lists"}