# Koboi Agent

> Self-hostable AI agents you can actually leave running — durable crash-resume, governed autonomy, seccomp sandbox, offline-replayable workflows, CI-native eval. Async-Python, YAML-config, multi-provider (OpenAI/Anthropic/Cloudflare), MIT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hedypamungkas-koboi-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hedypamungkas](https://agentstack.voostack.com/s/hedypamungkas)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hedypamungkas](https://github.com/hedypamungkas)
- **Source:** https://github.com/hedypamungkas/koboi-agent
- **Website:** https://pypi.org/project/koboi-agent/

## Install

```sh
agentstack add mcp-hedypamungkas-koboi-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://github.com/hedypamungkas/koboi-agent/actions/workflows/ci.yml)
  [](https://codecov.io/gh/hedypamungkas/koboi-agent)
  [](https://pypi.org/project/koboi-agent/)
  [](https://pypi.org/project/koboi-agent/)
  [](https://github.com/hedypamungkas/koboi-agent/blob/main/LICENSE)
  [](https://github.com/hedypamungkas/koboi-agent/actions/workflows/docker.yml)

  

  Self-hostable AI agents you can actually leave running.
  Durable crash-resume · governed autonomy · seccomp sandbox · offline-replayable · CI-native eval — all at the library level.

  

  Quickstart  · 
  vs LangGraph / CrewAI / OpenAI Agents SDK  · 
  Features  · 
  Architecture  · 
  Positioning

---

> **koboi-agent** is an MIT-licensed, async-Python framework for building AI agents you can run **unattended** — background jobs, long sessions, tool-using assistants that touch real systems. You configure a whole agent stack (model, tools, guardrails, RAG, serving) from one YAML file, then run it as a CLI, a library, or a self-hosted server. Most agent frameworks are great for demos; koboi is built for the boring question that decides whether a demo becomes production: *what happens when it crashes, when it's told to do something unsafe, or when no one is watching?*

## Why koboi

Four things, rare **together at the library level**, make an agent safe to leave running:

- 🛡️ **Durable by default** — Sessions survive crashes, redeploys, and `SIGKILL`. A SQLite step journal writes a `running` marker *before* every LLM call, so `koboi run --resume ` rehydrates and re-runs **only the tool calls that never finished** — non-idempotent tools (`write_file`, `run_shell`) are never silently replayed. See [`benchmarks/crash_recovery/run.py`](benchmarks/crash_recovery/run.py) for a reproducible crash→resume demo.
- 🧱 **Governed autonomy** — Agents act, but only inside a seccomp-isolated sandbox (syscall-level egress deny, no container required), with **deny-by-default approvals**, a trust database, rate limits, and guardrails. The **C3 contract**: autonomous destructive jobs are *refused* unless `sandbox.backend='restricted'`.
- 🔁 **Offline-replayable & CI-native** — Freeze any run into a re-runnable bundle, optionally with its LLM response cache, for byte-identical replay with **no API key** (`koboi capture --with-cache` → `run --replay-mode replay`). Treat agent behavior like code with an eve-style eval DSL that runs mock-deterministic on every commit (`koboi eval-test --mock`).
- 🏠 **Self-hostable, no platform upsell** — `koboi serve` is a real FastAPI service: interactive SSE chat with human-in-the-loop approvals **and** autonomous background jobs (Bearer keys, per-session ownership, idempotency, durable resume, HMAC webhooks). Run it on your own infrastructure — no managed tier required for durability or governance.

> [!NOTE]
> Several headline features — **self-healing**, **proactive memory**, **grounding/handover**, **multimodal**, **cross-instance A2A**, **deep research**, **deterministic replay**, and **seccomp HARD** isolation — are **opt-in / default-off** so the default install stays minimal and predictable. Each is documented where it appears. See [Honest limitations](#honest-limitations) for where koboi is deliberately lean.

## Quickstart

```bash
pip install koboi-agent
export OPENAI_API_KEY=sk-...        # or ANTHROPIC_API_KEY / CLOUDFLARE_API_KEY
# (cloned the repo? `cp .env.example .env` and edit it — koboi auto-loads .env)
```

One-shot from the CLI (works on a bare install, no extras):

```bash
koboi run configs/simple_chat.yaml -m "What is 2 + 2?"
```

Or as a library:

```python
import asyncio
from koboi import KoboiAgent

async def main():
    async with KoboiAgent.from_config("configs/simple_chat.yaml") as agent:
        result = await agent.run("What is 2 + 2?")
        print(result.content)

asyncio.run(main())
```

Optional extras (each unlocks one surface; the bare install covers run, validate, keys, mcp-serve, eval-test, graph, export/capture, workflows)

```bash
pip install koboi-agent[tui]            # interactive `koboi chat` (Textual TUI) + examples (click + rich)
pip install koboi-agent[api]            # `koboi serve` (FastAPI HTTP/SSE server)
pip install koboi-agent[tokenizer]      # accurate OpenAI token counts (tiktoken); chars/3 heuristic is the fallback
pip install koboi-agent[rerank-local]   # local BGE cross-encoder rerank (jina/cohere are hosted APIs, no extra)
pip install koboi-agent[indo-nlp]       # Indonesian stemmer (Sastrawi) for lexical RAG
pip install koboi-agent[media-cloud]    # R2/S3 media-artifact storage (local storage needs no extra)
pip install koboi-agent[rag]            # RAG document parsers (pypdf / python-docx / pdfplumber)
pip install koboi-agent[browser]        # Playwright fetch provider (then `playwright install chromium`)
pip install koboi-agent[tracing]        # Langfuse observability
pip install koboi-agent[dev,tui,api]    # everything (contributors)
```

System packages (not pip): `python3-seccomp` for HARD sandbox isolation (Linux only); `playwright install chromium` for the browser fetch provider.

## See it in 60 seconds: an agent that survives a crash

The fastest way to *see* the difference is durability. Start a run, kill it mid-flight, and resume:

```bash
# kick off a long-running, tool-using task, then Ctrl-C / kill the process mid-run
koboi run configs/simple_chat.yaml -m "Read ./data and summarize each file"

# list the interrupted session and resume it — only the unfinished tool calls re-run
koboi sessions configs/simple_chat.yaml
koboi run   configs/simple_chat.yaml --resume 
```

Reproducible benchmark with wall-clock numbers: `python benchmarks/crash_recovery/run.py`.

Another "wait, it does *that*?" moment — **human-in-the-loop on a self-hosted server**, on a bare install:

```bash
pip install koboi-agent[api] && koboi keys create
koboi serve configs/hitl_demo.yaml          # interactive SSE chat with approval prompts
python examples/hitl_client.py              # httpx-only client that auto-resolves pending_approval events
```

## How koboi compares

koboi's edge is the **integration** of durability + sandbox isolation + governed approval + self-hostable serving + CI-native eval at the framework core — it's rare to find all five together without a managed platform tier. Where koboi is leaner, we say so.

| Capability | koboi | LangChain / LangGraph | CrewAI | OpenAI Agents SDK |
|---|:--:|:--:|:--:|:--:|
| Multi-provider LLM | ✅ OpenAI / Anthropic / Cloudflare | ✅ broadest | ✅ | ✅ |
| **Crash/redeploy resume at library level** | ✅ `--resume`, non-idempotent-tool safe, on by default | ◐ checkpointer (manual wiring) | — | — |
| **Seccomp sandbox (no container) + deny-by-default approval + trust DB** | ✅ | ◐ minimal | ◐ HITL gates | ◐ container Sandbox Agents |
| **Self-hostable server: interactive SSE + async jobs** | ✅ `koboi serve` | ◐ LangServe / Platform | ◐ Enterprise | — |
| **Deterministic offline replay (no API key)** | ✅ | — | — | — |
| **CI-native eval-as-code (mock-deterministic)** | ✅ `koboi eval-test` | ◐ LangSmith (platform) | ◐ | — |
| Multi-agent orchestration (seq / parallel / DAG / deep research) | ✅ | ✅ LangGraph | ✅ Flows | ◐ handoffs |
| MCP client **and** server | ✅ | ✅ | ◐ | ✅ |
| Cross-instance agent-to-agent (A2A + trace) | ✅ | ◐ via Platform | ◐ | — |
| Multimodal generation (image/video/music/speech/STT) | ✅ | ◐ wrappers | ◐ | ◐ via API tools |

✅ = first-class, library-level  ·  ◐ = partial / separate product / platform tier  ·  — = not a focus

What koboi is (and isn't)

koboi is an **autonomous-loop** framework (the Claude Code / AutoGPT family) with multi-agent coordination layered on top — not a pure workflow-graph engine like LangGraph or CrewAI Flows. It shines for *agents you leave running*; if your primary need is a large, visual node-graph DAG runtime, LangGraph is the stronger choice there.

## Features

| Area | What you get |
|---|---|
| **Models** | OpenAI, Anthropic, Cloudflare Workers AI; `ProviderPool` failover + named-providers resolver — switch models without rewriting agents |
| **Tools** | 13 builtin modules (calculator, filesystem, shell, web, memory, search, git, subagent, task, ingest, handover, media, peer) + custom tools via `@tool()`; sync or async, dependency-injected |
| **Safety** | Input/output guardrails, policy engine, approval handlers, graduated trust DB, rate limiting, audit trail, secret redaction |
| **Sandbox** | Passthrough (default) or restricted: per-session workdir, rlimits, PATH allowlist, secret-stripped env, SOFT token-scan or **HARD seccomp** syscall egress deny (Linux) |
| **Memory** | In-memory or SQLite-WAL (hosts the step journal); opt-in **proactive long-term memory** (auto-extract facts → semantic recall each turn → always-in-context core block) |
| **Hooks** | 15 lifecycle events + 24+ specialized hooks; declarative **external-command hooks** (`hooks:` YAML — no Python required) |
| **RAG** | Chunking (fixed/sentence/paragraph/semantic), retrieval (keyword/BM25/semantic/hybrid), cross-encoder rerank (jina/cohere/local), query rewrite/HyDE, metadata filters, Indonesian stopwords+stemmer, HTTP/S3 sources — no vector DB required |
| **Web** | Pluggable search/fetch providers (mock, DuckDuckGo, Brave, Firecrawl + httpx/readability/Playwright) behind `web_search`/`web_fetch` |
| **Orchestration** | Keyword/LLM/hybrid routing; sequential, parallel, DAG, conditional, dynamic (LLM-planned); **deep_research** mode (plan → search → fetch → coverage-gate → cited report) |
| **Confidence & handover** | Opt-in grounding guardrail (claim-decompose + NLI judge, abstains when ungrounded) + `transfer_to_human` tool + handover detection + warm-handoff digest |
| **Self-healing** *(opt-in)* | Bounded verifier-grounded reflection → escalation ladder (retry → reflect → replan → handover) under a shared recovery budget → graceful degrade on `max_iterations`; optional CRITIC + self-consistency |
| **Multimodal** *(opt-in)* | image/video/music/speech + transcription via a pluggable gateway (Surplus; mock offline) — agent tools, sync+async REST, R2/S3 storage, budget caps |
| **Cross-instance A2A** *(opt-in)* | `call_peer_agent` tool + `POST /v1/peer/invoke` inbound + signed agent-card discovery + W3C trace propagation; a remote peer as a first-class orchestration node |
| **Determinism** *(opt-in)* | `koboi export`/`capture` freezes a run + optional response cache; `run --replay-mode replay` is byte-identical and **offline** |
| **MCP** | Client (stdio + HTTP) and server (`koboi mcp-serve` exposes your agent's tools; SAFE-only by default) |
| **Skills** | agentskills.io-aligned, 3-tier progressive disclosure, budget-aware, supply-chain-hardened (`!cmd` shell off by default) |
| **Eval** | eve-style `t` DSL with outcome assertions (`calledTool`/`toolWasBlocked`/`retrievedChunk`/`completed`…), mock-deterministic, 25 scorer classes; BFCL/GAIA/SWE-bench/RAGAS/DeepEval harnesses |
| **Serving** | `koboi serve`: interactive SSE chat (HITL) + autonomous jobs (durable resume), Bearer keys, ownership, idempotency, HMAC webhooks |
| **Modes** | `chat` / `plan` / `act` / `auto` / `yolo` — graduated tool risk; YOLO bypasses gates but never hardcoded safety |
| **TUI** *(opt-in)* | Textual terminal UI: chat, command palette, diff view, session manager, F2 MCP-status, F3 media gallery |

## Serve it (HTTP/SSE + autonomous jobs)

```bash
pip install koboi-agent[api]
koboi keys create                                        # mint a Bearer key
koboi serve configs/server_deploy.yaml --host 0.0.0.0 --port 8080
```

Two paths, same composition: `koboi serve ` (built-in) or `create_app(config, extra_tools=..., extra_hooks=..., approval_handler=...)` (customize by code).

```bash
# interactive SSE chat (stream tokens + HITL approvals)
curl -N -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message":"What is 2+2?"}' http://localhost:8080/v1/chat/stream

# autonomous job (202 + poll / SSE replay; durable resume on crash)
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message":"Summarize the Q3 report"}' http://localhost:8080/v1/jobs
```

Self-host with Docker (3 customization tiers, no rebuild)

The published image (`ghcr.io/hedypamungkas/koboi-agent:`) is a base layer:

- **Mount a YAML config** — `docker run -e KOBOI_CONFIG=/app/agent.yaml -v agent.yaml:/app/agent.yaml …`
- **Mount an extensions dir** — `docker run -e KOBOI_EXTENSIONS_DIR=/app/ext -v ext/:/app/ext …` (custom tools / RAG retrievers; auto-added to `sys.path`)
- **Derive a new image** — `FROM ghcr.io/hedypamungkas/koboi-agent:` for full `create_app(extra_tools=…, extra_routes=…)` composition

See [`examples/docker/`](examples/docker) for runnable, LLM-free proofs of each tier. Cloudflare Tunnel deploy via the bundled `docker-compose.yml`.

## Configure

One YAML file describes the whole stack, with `${ENV_VAR:default}` interpolation to keep secrets out:

```yaml
agent:
  name: "my-agent"
  system_prompt: "You are helpful."
  mode: "chat"                 # chat | plan | act | auto | yolo

llm:
  provider: "openai"           # openai | anthropic | cloudflare
  model: "gpt-4o-mini"
  api_key: "${OPENAI_API_KEY}"

tools:
  builtin: [calculator, web_search, memory_store, memory_recall]

context:
  strategy: "smart_truncation" # noop | truncation | smart_truncation | key_facts | sliding_window
  max_context_tokens: 8000

rag:
  enabled: true
  retriever: "hybrid"          # keyword | semantic | hybrid (BM25)
  top_k: 10
  documents:
    - path: "./data/sample/product_catalog.md"

guardrails:
  input: { max_length: 10000 }
  rate_limit: { max_calls_per_minute: 20 }

sandbox:
  backend: "restricted"        # passthrough (default) | restricted (+ seccomp HARD)
```

See [`configs/`](configs/) for 39 ready-to-run configs and `docs/architecture.md` for the full schema. Notable configs: `self_healing_demo.yaml`, `deep_research_demo.yaml`, `workflow_export_demo.yaml`, `hitl_demo.yaml`, `a2a_instance_x.yaml`, `aegis_ops_full.yaml` (nearly all 32 `KoboiConfig` sections in one DAG-orchestrated scenario).

## Architecture

`KoboiAgent` (`facade.py`) is the single entry point — it assembles every subsystem from one YAML `Config`. The autonomous loop runs inside the governed boundary (the durable journal + sandbox + trust/approval seams are what make it safe to leave running):

```mermaid
flowchart LR
  CFG["YAML configmodel · tools · guardrails · rag · serve"] --> FAC["KoboiAgentfacade.py"]

  subgraph LOOP["Autonomous loop (governed)"]
    AC["AgentCore+ tool pipeline"]
    HK["HookChain15 lifecycle events"]
    TR["ToolRegistry13 builtin + custom"]
    JN["StepJournalcrash-resume · SQLite WAL"]
    SB["Sandboxpassthrough → seccomp HARD"]
    TU["Trust · Approvaldeny-by-default"]
  end

  FAC --> LOOP
  LOOP --> OUT["Orchestratorseq · parallel · DAG · deep_research"]
  LOOP --> SRV["koboi serveSSE chat + async jobs"]
  LOOP --> WF["Workflow exportoffline replay · no API key"]
  OUT -.->|"call_peer_agent /v1/peer/invoke"| PEER["Remote peer instance(cross-instance A2A)"]
```

Deep dive (agent-loop lifecycle, hook system, tool pipeline, extension points): **[docs/architecture.md](docs/architecture.md)**.

## Build with koboi from your own agent

koboi speaks the protocols your coding agent already uses:

```bash
# expose this agent's tools as a stdio MCP server (SAFE-only by default; --allow / --allow-all to escalate)
koboi mcp-serve configs/simple_chat.yaml
```

Reusable, supply-chain-hardened **skills** (agentskills.io-aligned) ship in [`skills/`](skills/) — `code_review`, `customer_service`, `hotel_receptionist`, `search_and_summarize`. Define your own and they're discovered, budget-capped, and invoked with fail-closed `!cmd` preprocessing.

## Examples

[`examples/`](examples) has 39 numbered scripts plus server, HITL, A2A, and workflo

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hedypamungkas](https://github.com/hedypamungkas)
- **Source:** [hedypamungkas/koboi-agent](https://github.com/hedypamungkas/koboi-agent)
- **License:** MIT
- **Homepage:** https://pypi.org/project/koboi-agent/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hedypamungkas-koboi-agent
- Seller: https://agentstack.voostack.com/s/hedypamungkas
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.