Chetter
Chetter is an Open Source system written in Go for running autonomous AI development agents using standard harnesses (OpenCode, Claude Code, CodeWhale, Pi, Codex, Niffler) in standard Docker or Kubernetes environments.
If you are looking for a simple(r) solution to self host standard autonomous coding agents, then Chetter should be interesting. Hop into our Discord if you want to know more.
- Submit tasks to standard harnesses against Git repos with LLM agents in Docker containers
- Track live progress — streaming events, logs, session transcripts
- Automation — cron triggers, generic webhooks, PR review webhooks, GitHub PR/issue/comment responders
- Pause and resume — pause agent sessions and resume on the same runner with follow-up prompts
- Manage via MCP or web UI — web UI, MCP tools, team tokens, audit log, runner fleet health
Design Principles
Chetter was built as a reaction towards the solutions available (E2B, Daytona, Modal etc) which often are not Open Source or want to lock you into them hosting your agents, need relatively exotic infrastructure like Firecracker VMs or use custom harnesses instead of industry standard harnesses.
Chetter instead ...
- Is true Open Source. Chetter was built for organisations that feel that the future of software development should be under their own control.
- Uses Standard harnesses. Chetter delegates agent execution to existing CLI tools — primarily OpenCode, with support for Claude Code, CodeWhale, Pi, Codex, and Niffler. No custom agent runtime. We believe that the popular harnesses have the momentum and we also feel that constructing an autonomous agent should be done with the same tools that you use as an individual developer.
- Deploys in Docker or Kubernetes. Both the server and runners run on standard Docker or Kubernetes. No special infrastructure is needed for convenience execution. For a task security boundary, enable gVisor; plain Docker execution is not sandboxed against a malicious task.
- Relies on GitHub-native orchestration. Chetter integrates deeply with GitHub and uses PRs, issues, reviews, and comments to drive agent workflows — the same primitives developers already use.
- Uses plain containers as environments. The agent runs in a normal Docker container. You define the image with the tools and stack your project needs.
- Is MCP and API first, web UI for observation. The server has a full ConnectRPC API exposed also as MCP tools. There is also a web UI primarily for monitoring, inspection, and admin tasks.
Quick Start
Prerequisites
- Docker Engine with the Compose plugin and BuildKit/buildx (the
Dockerfiles use BuildKit-only features). Docker from
docs.docker.com ships both; on
Ubuntu's
docker.io package install docker-buildx too:
sudo apt-get install -y docker.io docker-compose-v2 docker-buildx
git- An LLM provider API key (e.g.
DEEPSEEK_API_KEY) — set it in .env
git clone https://github.com/flatout-works/chetter.git
cd chetter
cp .env.example .env
# Edit .env: set CHETTER_MCP_AUTH_TOKEN and at least one LLM provider key
./deploy/build.sh
docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml up -d
The MCP server is at http://localhost:18088, the web UI at http://localhost:18090.
See docs/MANUAL.md for detailed setup, configuration, and operations.
What you get: a dev TiDB (bundled via deploy/compose.local.yaml,
single-node unistore, MySQL-wire compatible — the chetter database and
all migrations are created automatically on startup), the MCP server, and two
runners. To run your first task you also need a default Git identity
(chetter_create_git_identity + chetter_set_git_identity_default via any
MCP client).
⚠ Security note: the quickstart runs agent tasks in plain Docker,
without gVisor sandboxing (compose.local.yaml sets
CHETTER_ALLOW_UNISOLATED=true and USE_GVISOR=false). That is fine for
development, but it is not a security boundary against a malicious
task. For a hardened deployment, enable gVisor — see
docs/DEPLOYMENT.md and "Verifying gVisor" below.
Verifying gVisor
The server defaults to hardened mode: every task requires gVisor-enforced
isolation unless the deployment opts out. To go from the quickstart to a
sandboxed setup:
- Install
runsc on the host and register it with Docker, per
docs/DEPLOYMENT.md ("Docker + gVisor").
- In
deploy/compose.local.yaml, set USE_GVISOR: "true" for the runners
(or drop the override) and remove CHETTER_ALLOW_UNISOLATED.
- Recreate the stack (
docker compose up -d --force-recreate).
- Verify sandboxing is actually in effect:
Validating the Quick Start
ops/test-quickstart.sh runs the full Quick Start from scratch on a
disposable Ubuntu 24.04 KVM VM and asserts every step — ideal before
releases:
DEEPSEEK_API_KEY=sk-... ./ops/test-quickstart.sh # plain-Docker quickstart
DEEPSEEK_API_KEY=sk-... ./ops/test-quickstart.sh --gvisor # ...then gVisor hardening
The default run provisions the VM (no Docker preinstalled), installs the
prerequisites, and validates: image build, compose up, database
auto-creation + migrations, MCP connect, fleet health, a real task
execution, and the self-test. --gvisor additionally installs runsc,
switches the stack to hardened mode and re-validates with
isolation="required" tasks (including the HostConfig.Runtime == runsc
check). Each step is reported PASS/FAIL; the VM is torn down afterwards
(QS_KEEP_VM=1 keeps it for debugging). Requires /dev/kvm, libvirt
tooling, and sudo. See the script header for all options.
Next Steps
- Configure the GitHub App for PR review and issue automation (webhook, label,
/chetter-review): see docs/TRIGGERS.md.
- Point Chetter at a definitions repo for agents, skills, triggers, task
templates, and the model catalog: see docs/CONFIGURATION.md.
- Enable gVisor for a task security boundary: see docs/DEPLOYMENT.md.
- For production Kubernetes, see docs/EKS.md; for local k3s
validation, docs/K3S.md.
Connect Your AI Client
- OpenCode — built-in config at
.opencode/opencode.json; set CHETTER_MCP_TOKEN and point the url at your server
- Claude Code —
claude mcp add --transport http chetter https://chetter.example.com/mcp --header "Authorization: Bearer $TOKEN"
- Any MCP client — standard remote MCP server format; see docs/MANUAL.md
Repository Layout
| Path | Purpose |
|---|
main.go | Server entry point |
internal/ | Config, store, service, webhook, web UI |
cmd/ | chetterctl token management CLI |
db/ | Migrations and sqlc query files (TiDB/MySQL under db/migrations/, PostgreSQL under db/postgres/) |
proto/ | ConnectRPC service definitions (server ↔ runner) |
runner/ | Containerized runner harness |
web/ | SvelteKit web UI (Flowbite-Svelte) |
deploy/ | Docker Compose and Kubernetes manifests |
docs/ | Documentation |
Docs
Build From Source
Requires Go 1.26+, Node.js 24 + npm (the server embeds the web UI),
and GNU Make.
make check && make build
make build compiles the SvelteKit web UI, embeds it into the server via
go:embed, and produces two binaries in bin/:
bin/chetter — the MCP server / control planebin/chetterctl — the token management CLI
After changing proto/ or any db/queries/*.sql, regenerate the protobuf
and sqlc code (this also refreshes the dialect facade):
make generate
See AGENTS.md for the full developer command reference.
License
MIT
