KohakuTerrarium Agent工作流

Build the web frontend (required for `kt web` / `kt app` from source)

npm install --prefix src/kohakuterrarium-frontend npm run build --prefix src/kohakuterrarium-frontend ```

1. Install KohakuTerrarium

```bash

Optional extras: pip install "kohakuterrarium[full]"

2. Install OOTB creatures and plugins

```bash

I want to build my own creature

• First Creature tutorial
• Creatures guide
• Custom Modules
• Plugins
• First Custom Tool tutorial

I want to deploy it

• Deployment — Docker — AIO, host + workers, distributed compose recipes
• Deployment — systemd — kt service install + hardened units
• Deployment — reverse proxy — nginx / Cloudflare Tunnel + TLS
• Laboratory — multi-node lab-host / lab-client model

Deployment (Docker / systemd / multi-node)

Three first-party Docker images on GHCR — pick the shape:

```bash

Installation & Setup

What Python version is required? Python 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).

Which LLM providers are supported? Codex 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.

Can I use local models? Yes. Point the LLM endpoint to your local server (Ollama, vLLM, etc.) and configure the model name in your creature configuration.

Quick start

Recommended Python version: 3.12 or newer. CI validates 3.12+ only; 3.10 and 3.11 still install and run (requires-python = ">=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.

Programmatic usage

Agents 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.

import asyncio
from kohakuterrarium import Terrarium

async def main():
    # Solo creature
    engine, alice = await Terrarium.with_creature("@kt-biome/creatures/swe")
    try:
        async for chunk in alice.chat("Explain what this codebase does."):
            print(chunk, end="", flush=True)
    finally:
        await engine.shutdown()

    # Multi-agent recipe
    engine = await Terrarium.from_recipe("@kt-biome/terrariums/swe_team")
    try:
        async for chunk in engine["swe"].chat("Fix the auth bug."):
            print(chunk, end="", flush=True)
    finally:
        await engine.shutdown()

asyncio.run(main())

Packages, defaults, and examples

Creatures are meant to be packaged, installed, reused, and shared.

kt install https://github.com/someone/cool-creatures.git
kt install ./my-creatures -e
kt list
kt update --all

Run installed configs with package references:

kt run @cool-creatures/creatures/my-agent
kt terrarium run @cool-creatures/terrariums/my-team

Available resources:

• kt-biome/ — official showcase creatures, terrariums, and plugin pack
• examples/agent-apps/ — config-driven creature examples
• examples/code/ — Python usage examples
• examples/terrariums/ — multi-agent examples
• examples/plugins/ — plugin examples

See examples/README.md.

Tutorials

First Creature · First Terrarium · First Python Embedding · First Custom Tool · First Plugin

Guides

Getting Started · Creatures · Terrariums · Sessions · Memory · Configuration · Programmatic Usage · Composition · Custom Modules · Plugins · MCP · Packages · Serving · Laboratory · Deployment — Docker · Deployment — systemd · Deployment — reverse proxy · Examples

Official showcase pack

kt install https://github.com/Kohaku-Lab/kt-biome.git

Or native Anthropic / OpenAI-compatible providers via `kt config llm add`

```

Supports Codex OAuth, OpenRouter/OpenAI, native Anthropic, Google Gemini, and any OpenAI-compatible API.

Environment and session

• Environment — shared terrarium state (shared channels).
• Session — private creature state (scratchpad, private channels, sub-agent state).

Private by default, shared by opt-in.

CLI and TUI

• cli — rich inline terminal experience
• tui — full-screen Textual application
• plain — simple stdout/stdin for pipes and CI

See CLI Reference.

Reference

CLI · HTTP · Python API · Configuration · Builtins · Plugin hooks

Any third-party package

kt install <git-url> kt install ./my-creatures -e # editable install ```

Modules

A 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).

Plus plugins, which modify the connections between modules without forking them (prompt plugins, lifecycle hooks). See plugins guide.

FAQ

Troubleshooting

Why is my creature not responding? Check that your LLM provider is configured correctly with kt login. Verify network connectivity and API key validity.

How do I debug agent behavior? Use 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.

Where can I get help? - QQ Group: 1097666427 - Discord: https://discord.gg/xWYrkyvJ2s - Forum: https://linux.do/