convez.ai
MCP Server
flatout-works

chetter

flatout-works/chetter

Ver no GitHub
InicialPluginScore · de 0 a 100

Chetter: self-hosted MCP server and runner fleet for autonomous AI development tasks

Instalação

$npx convez-ai flatout-works/chetter

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
2
Acompanhando
0
Saúde
50%
Último commit
há 2 dias
Versão
v0.1.0
Issues abertas
73
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

Chetter

Chetter is a self-hosted MCP (Model Context Protocol) server for running autonomous AI development agents. It gives your AI tooling a way to submit software development work to a fleet of containerized runners.

A Chetter runner can clone a repository, start an OpenCode agent, execute a prompt, stream progress events, and persist the final result. You interact with it through MCP tools from clients such as Claude Desktop, Cursor, Continue, or your own agent stack.

What It Can Do

  • Submit one-off development tasks against a Git repository.
  • Run LLM agents in isolated runner containers.
  • Track task status, logs, progress, and result details.
  • Run recurring cron-backed maintenance jobs.
  • Cancel pending or running tasks.
  • Inspect runner health and heartbeat freshness.
  • Expose the whole control plane through a standard HTTP MCP endpoint.

Quick Start

These steps are intended for a fresh Linux cloud machine with Docker installed.

1. Clone

git clone https://github.com/flatout-works/chetter.git
cd chetter

2. Configure

cp .env.example .env

Edit .env and set at least:

  • MYSQL_PASSWORD
  • MYSQL_ROOT_PASSWORD
  • CHETTER_MCP_AUTH_TOKEN
  • At least one LLM provider key, such as OPENAI_API_KEY, DEEPSEEK_API_KEY, SYNTHETIC_API_KEY, or OPENCODE_API_KEY

For public servers, always set CHETTER_MCP_AUTH_TOKEN.

3. Start

docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml up -d

This starts:

  • MySQL for Chetter state
  • The Chetter MCP server on port 18088
  • Two runner containers that pick up tasks

The deploy/compose.local.yaml override adds the bundled MySQL service. If you already have MySQL or TiDB, set DATABASE_DSN in .env and run only -f deploy/compose.yaml.

4. Check It

curl http://localhost:18088/healthz
docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml ps

5. Connect Your AI Client

OpenCode

This repo includes ready-to-use OpenCode configuration at .opencode/opencode.json. It defines:

  • MCP connection to the Chetter server
  • Slash commands: /chetter-status, /chetter-tasks, /chetter-submit, /chetter-triggers, /chetter-cancel
  • Skill at .opencode/skill/chetter/SKILL.md with workflows and schedule management guidance

To set up in your own OpenCode project:

  1. Copy .opencode/opencode.json (or the relevant mcp and command blocks) into your project's opencode.json.
  2. Copy .opencode/skill/chetter/SKILL.md to your project's .opencode/skill/chetter/SKILL.md.
  3. Set the token:
    export CHETTER_MCP_TOKEN=your-token
    
  4. Verify:
    opencode mcp list
    # Should show "chetter" as enabled
    

If you cloned this repo, the config is already in place; just set CHETTER_MCP_TOKEN.

Claude Code

Claude Code supports remote MCP servers. Add the server:

claude mcp add --transport http chetter https://chetter.flatout.works/mcp \
  --header "Authorization: Bearer $CHETTER_MCP_TOKEN"

Or create a project-scoped .mcp.json:

{
  "mcpServers": {
    "chetter": {
      "type": "http",
      "url": "https://chetter.flatout.works/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

For similar command workflows, translate the OpenCode command templates into your Claude Code command setup.

Verify:

claude mcp list
# Should show chetter

Other MCP Clients (Cursor, Continue, Claude Desktop)

Use the standard MCP remote server format:

{
  "mcpServers": {
    "chetter": {
      "url": "https://chetter.flatout.works/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CHETTER_MCP_AUTH_TOKEN"
      }
    }
  }
}

If you self-host Chetter, use http://YOUR_SERVER:18088/mcp instead.

6. Submit A Task

Call the chetter_submit_task MCP tool from your AI client, or use /chetter-submit in OpenCode:

{
  "prompt": "Add input validation to all API handlers and run the tests.",
  "git_url": "https://github.com/my-org/my-repo",
  "git_ref": "main",
  "agent_image": "ghcr.io/flatout-works/chetter-runner:main"
}

Set GITHUB_TOKEN in .env if runners need access to private repositories or need to create branches and pull requests.

Trying Chetter Locally with k3s

k3s is the most widely used lightweight Kubernetes distribution for local development. It's a single binary, installs in seconds, and supports all standard Kubernetes APIs. If you want to test Chetter on Kubernetes without a cloud cluster, k3s is the recommended path.

Other options exist — kind (Kubernetes in Docker) and minikube — but k3s is preferred because it runs actual containers (not nested Docker-in-Docker), making Docker socket passthrough and gVisor work naturally.

Prerequisites

  • A Linux machine (bare metal or VM) with at least 4 GB RAM and Docker installed
  • (Optional) KVM support if you want gVisor

Step 1: Install k3s

curl -sfL https://get.k3s.io | sh -

# k3s writes kubeconfig to /etc/rancher/k3s/k3s.yaml
# For non-root access:
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

# Verify
kubectl get nodes

k3s automatically includes Traefik as an ingress controller and its own container runtime. It uses Docker as the default runtime if Docker is installed on the host, which is what we want for the runner's Docker socket passthrough.

Step 2: Create the namespace and secrets

kubectl apply -f deploy/k8s/namespace.yaml

kubectl create secret generic chetter-secrets \
  --namespace=chetter \
  --from-literal=CHETTER_MCP_AUTH_TOKEN=your-token \
  --from-literal=DATABASE_DSN='chetter:password@tcp(mysql:3306)/chetter?parseTime=true' \
  --from-literal=GITHUB_TOKEN=your-gh-token \
  --from-literal=DEEPSEEK_API_KEY=your-key

Step 3: Deploy MySQL

For local testing, run MySQL in the cluster:

kubectl apply -n chetter -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
spec:
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
      - name: mysql
        image: mysql:8.0
        env:
        - name: MYSQL_ROOT_PASSWORD
          value: password
        - name: MYSQL_DATABASE
          value: chetter
        - name: MYSQL_USER
          value: chetter
        - name: MYSQL_PASSWORD
          value: password
        ports:
        - containerPort: 3306
        readinessProbe:
          exec:
            command: ["mysqladmin", "ping", "-h", "localhost"]
          initialDelaySeconds: 10
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  selector:
    app: mysql
  ports:
  - port: 3306
    targetPort: 3306
EOF

Step 4: Deploy Chetter

# Apply the MCP server and runner manifests
kubectl apply -f deploy/k8s/mcp-service.yaml
kubectl apply -f deploy/k8s/mcp-deployment.yaml
kubectl apply -f deploy/k8s/runner-deployment.yaml

# Wait for everything to come up
kubectl -n chetter rollout status deployment/chetter-mcp
kubectl -n chetter rollout status deployment/chetter-runner

Step 5: Verify

# Check all pods are running
kubectl -n chetter get pods

# Check MCP server health
kubectl -n chetter port-forward deployment/chetter-mcp 18088:8080 &
curl http://localhost:18088/healthz

# Watch runner logs
kubectl -n chetter logs -f deployment/chetter-runner

Step 6: Connect your AI client

Port-forward the MCP server and use http://localhost:18088/mcp as your MCP endpoint. See Quick Start step 5 for client-specific setup.

Optional: Enable gVisor

If you want sandbox isolation on your k3s node:

# Install gVisor on the host (not inside k3s)
curl -fsSL https://gvisor.dev/archive.key | \
  sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | \
  sudo tee /etc/apt/sources.list.d/gvisor.list
sudo apt-get update && sudo apt-get install -y runsc

# Register runsc with the container runtime
sudo /usr/bin/runsc install
sudo systemctl restart docker

# Apply the RuntimeClass (optional — only if you want runner pods under gVisor too)
kubectl apply -f deploy/k8s/gvisor-runtimeclass.yaml

# Enable gVisor for agent containers by setting the env var
kubectl -n chetter set env deployment/chetter-runner USE_GVISOR=true

Cleaning up

# Remove Chetter
kubectl delete namespace chetter

# Uninstall k3s
/usr/local/bin/k3s-uninstall.sh

Common Commands

# Follow all service logs
docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml logs -f

# Follow only the MCP server
docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml logs -f chetter-mcp

# Follow runner logs
docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml logs -f chetter-runner chetter-runner-2

# Restart after editing .env
docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml up -d

# Stop the stack
docker compose --env-file .env -f deploy/compose.yaml -f deploy/compose.local.yaml down

MCP Tools

| Tool | Purpose | |---|---|---| | chetter_submit_task | Submit a one-off development task | | chetter_task_status | Fetch persisted task status and result | | chetter_list_tasks | List recent tasks | | chetter_create_trigger | Create a trigger (cron schedule or PR review webhook) | | chetter_update_trigger | Update a trigger by name | | chetter_list_triggers | List triggers, optionally filtered by type | | chetter_delete_trigger | Delete a trigger by name | | chetter_run_trigger | Run a cron trigger immediately | | chetter_cancel_task | Cancel a pending or running task | | chetter_clear_queue | Clear queued tasks | | chetter_task_events | Fetch full event history for a task | | chetter_task_progress | Fetch distilled task progress | | chetter_task_latest_event | Fetch latest event for a task | | chetter_runner_health | Derive fleet health and runner status | | chetter_create_token | Create an API token for a team and user | | chetter_list_tokens | List API tokens with user and team info | | chetter_delete_token | Delete an API token by name | | chetter_create_team | Create a new team (admin only) | | chetter_list_teams | List all teams (admin only) | | chetter_delete_team | Delete a team and cascade to its users, tokens, tasks, and schedules (admin only) | | chetter_list_users | List users, optionally filtered by team name (admin only) | | chetter_list_schedule_runs | List schedule runs for the current team, optionally filtered by schedule name |

Configuration

Main Environment Variables

VariableDescription
CHETTER_MCP_AUTH_TOKENBearer token required by /mcp
MYSQL_PASSWORDPassword for the local chetter MySQL user
MYSQL_ROOT_PASSWORDRoot password for the local MySQL container
DATABASE_DSNOptional external MySQL/TiDB DSN override
GITHUB_TOKENOptional token for private repos and GitHub write operations
GITHUB_APP_IDGitHub App ID for PR review webhooks
GITHUB_APP_PRIVATE_KEY_B64Base64-encoded GitHub App private key (PEM)
GITHUB_INSTALLATION_IDGitHub App installation ID
GITHUB_WEBHOOK_SECRETHMAC-SHA256 secret for webhook signature verification
ARCANE_SERVER_URLArcane platform API URL for image builds
ARCANE_API_KEYArcane platform API key
OPENAI_API_KEYOptional OpenAI key for runner agents
DEEPSEEK_API_KEYOptional DeepSeek key for runner agents
SYNTHETIC_API_KEYOptional Synthetic key for runner agents
OPENCODE_API_KEYOptional OpenCode provider key
MEM9_API_KEYOptional Mem9 memory provider key
USE_GVISORSet to true to run agent containers under gVisor (--runtime=runsc)
CHETTER_RUNNER_IMAGE_DIGESTOptional pinned image digest for PR signature footers

If DATABASE_DSN is not set, use deploy/compose.local.yaml to add the bundled MySQL service. Production deployments should usually set DATABASE_DSN and run only deploy/compose.yaml.

Runner Environment Variables

VariableDescription
RUNNER_LOCALSet to true for local/Docker execution mode (default)
CHETTER_SERVER_URLMCP server URL (e.g. http://chetter-mcp:8080)
CHETTER_RUNNER_AUTH_TOKENAuth token for runner → MCP server communication
RUNNER_MAX_CONCURRENTMax concurrent tasks per runner (default: 2)
USE_GVISORSet to true to run agent containers under gVisor (--runtime=runsc)
CHETTER_RUNNER_IMAGERunner image reference for task signature footers
CHETTER_RUNNER_IMAGE_DIGESTPinned image digest for task signature footers

Runner Concurrency

Each runner can handle multiple tasks simultaneously via RUNNER_MAX_CONCURRENT. Each task gets its own Docker container with its own port, so tasks are process-isolated even within a single runner.

Higher concurrency per runner (MAX_CONCURRENT=5) vs. more runners (MAX_CONCURRENT=1):

Multiple tasks per runnerMore runners
OverheadOne process, one heartbeat stream, one Docker connectionN× process overhead, N× heartbeats
Resource efficiencyLower baseline CPU/memory when idleEach runner consumes resources even when idle
ScalingChange one env varProvision more pods
Task pickupSemaphore slot frees immediatelyNew runner must spin up
Blast radiusRunner crash/OOM kills all in-flight tasksOnly one task lost per runner failure
IsolationOne greedy container can starve othersFull isolation per runner
DebuggingInterleaved logs from concurrent tasksClean per-runner logs
Docker SPOFDocker hang affects all tasksOnly one task affected

Recommended: RUNNER_MAX_CONCURRENT=2 or 3 per runner pod. This gives good density without excessive blast radius. For production, a mix works well — e.g., 4 pods with MAX_CONCURRENT=2 = 8 concurrent tasks, with only 2 tasks lost per pod failure.

Deploying on Kubernetes

The runner uses a stateless pull model: it connects to the MCP server over HTTP, long-polls ClaimTask to pick up work, sends heartbeats, and reports task events. No special protocols, no broker, no runner pre-registration. This maps directly to a Kubernetes Deployment.

MCP Server

apiVersion: v1
kind: Service
metadata:
  name: chetter-mcp
spec:
  selector:
    app: chetter-mcp
  ports:
  - port: 8080
    targetPort: 8080
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: chetter-mcp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: chetter-mcp
  template:
    metadata:
      labels:
        app: chetter-mcp
    spec:
      containers:
      - name: mcp
        image: ghcr.io/flatout-works/chetter-mcp:main
        ports:
        - containerPort: 8080
        envFrom:
        - secretRef:
            name: chetter-secrets
        env:
        - name: HTTP_ADDR
          value: ":8080"
        - name: DEFAULT_AGENT_IMAGE
          value: ghcr.io/flatout-works/chetter-runner:main

Runners

apiVersion: apps/v1
kind: Deployment
metadata:
  name: chetter-runner
spec:
  replicas: 4   # scale with kubectl scale deployment chetter-runner --replicas=8
  selector:
    matchLabels:
      app: chetter-runner
  template:
    metadata:
      labels:
        app: chetter-runner
    spec:
      runtimeClassName: gvisor   # optional — requires gVisor on the nodes
      containers:
      - name: runner
        image: ghcr.io/flatout-works/chetter-runner:main
        envFrom:
        - secretRef:
            name: chetter-secrets
        env:
        - name: CHETTER_SERVER_URL
          value: "http://chetter-mcp:8080"
        - name: RUNNER_LOCAL
          value: "true"
        - name: RUNNER_MAX_CONCURRENT
          value: "2"
        - name: USE_GVISOR
          value: "true"   # agent containers will use --runtime=runsc

Scaling is just kubectl scale. Each runner pod independently polls for tasks. Adding or removing runners does not require any coordination — the MCP server's ClaimTask uses SELECT ... FOR UPDATE SKIP LOCKED for atomic task assignment.

gVisor on Kubernetes

See the Sandbox Isolation section for the DaemonSet that installs gVisor on cluster nodes and the RuntimeClass registration. On GKE, use GKE Sandbox instead — no DaemonSet needed.

When runtimeClassName: gvisor is set on the runner pod, the runner container itself runs under gVisor. When USE_GVISOR=true is also set, agent containers spawned by the runner (via Docker) also use the runsc runtime. These are independent: you can run the runner under gVisor while agents use runc, or vice versa.

For local Kubernetes testing, see Trying Chetter Locally with k3s.

Deploying with Docker + gVisor

When running Chetter via Docker Compose, you can enable gVisor for agent containers by installing runsc on the host and setting USE_GVISOR=true.

Install gVisor on the host

# Add the gVisor repository
curl -fsSL https://gvisor.dev/archive.key | \
  sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | \
  sudo tee /etc/apt/sources.list.d/gvisor.list
sudo apt-get update && sudo apt-get install -y runsc

# Register runsc with Docker
sudo /usr/bin/runsc install
sudo systemctl restart docker

# Verify
docker run --runtime=runsc --rm alpine dmesg
# Should show "Starting gVisor..."

Enable in Docker Compose

Add USE_GVISOR=true to .env or the runner service environment:

chetter-runner:
  image: ghcr.io/flatout-works/chetter-runner:main
  environment:
    RUNNER_LOCAL: "true"
    USE_GVISOR: "true"   # agent containers will use --runtime=runsc
    # ... other vars
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock   # required for docker run

When USE_GVISOR=true, the runner passes --runtime=runsc to docker run when starting agent containers. The runner container itself does not need gVisor — only the host Docker daemon needs the runsc runtime registered.

The Docker socket mount is required because the runner shells out to docker run to create agent containers. The runsc binary is resolved by the host Docker daemon, so it does not need to exist inside the runner container.

Arcane Deployment

Chetter's production deployment uses Arcane GitOps and Arcane image builds on wowbagger. GitHub Actions does not build Docker images.

The deployment flow is:

  1. Push to main.
  2. GitHub Actions runs make check.
  3. The workflow calls Arcane's API to sync GitOps, build images on wowbagger, push them to GHCR, and redeploy the Chetter project.
  4. Arcane redeploys containers from the GHCR images.

Required GitHub repository secrets:

SecretDescription
ARCANE_URLArcane base URL, for example https://wowbagger.krampe.se
ARCANE_API_KEYArcane API key with project build/deploy permissions
ARCANE_CHETTER_PROJECT_IDArcane Chetter project ID
ARCANE_CHETTER_GITOPS_IDArcane GitOps sync ID

Optional GitHub repository variable:

VariableDescription
ARCANE_ENVIRONMENT_IDArcane environment ID, defaults to 0

Arcane must have GHCR registry credentials configured in Arcane's registry settings. Do not store GHCR_TOKEN in GitHub Actions for this deployment path.

Arcane GitOps must use:

  • Compose path: compose.yaml
  • Directory sync: enabled

The root compose.yaml is for Arcane GitOps and uses build: directives with explicit GHCR image tags. The deploy/compose.yaml file is the portable self-hosted compose stack that pulls the published GHCR images.

Repository Layout

PathPurpose
compose.yamlArcane GitOps compose file with build directives
main.goMCP/HTTP server entry point
internal/config/Environment-backed configuration
internal/store/MySQL/TiDB schema and persistence
internal/repository/sqlc-generated database queries
db/goose migrations and sqlc query files
internal/service/MCP tools and task orchestration
internal/webhook/Optional GitHub webhook handling
deploy/compose.yamlPortable Docker Compose stack using published GHCR images
runner/Runner runtime, image Dockerfiles, and entrypoint
schedules/Active production schedules
schedules-examples/Example schedule templates
tools/skills/OpenCode skills baked into the runner image

Sandbox Isolation

Chetter runners execute AI-generated code. The isolation strategy is driven by three practical requirements:

  1. Works on standard managed Kubernetes (EKS, GKE) without custom AMIs or node-level modifications beyond a DaemonSet.
  2. Supports streaming interaction with the agent — real-time events, session management, and progress tracking via the OpenCode serve API. Batch-only runtimes break this.
  3. Provides decent security — stronger than plain namespace isolation, without requiring VMs or custom host kernels.

gVisor is the chosen path

Chetter uses gVisor (runsc) as its sandboxed execution runtime. gVisor provides an application kernel (the Sentry) written in Go that intercepts every system call the container makes and implements the Linux ABI in userspace. The application never touches the host kernel directly. This gives kernel-level isolation without VMs, without custom AMIs, and without sacrificing streaming interaction.

The runner integrates gVisor through containerd — the same ctr interface already used for other runtimes, just with --runtime io.containerd.runsc.v1 instead of --runtime io.containerd.runc.v2. Normal container networking works, so the interactive opencode serve flow (create session, send prompt, watch events, export session) functions exactly as it does with plain Docker.

Why gVisor over alternatives

RequirementgVisorKata ContainersSysboxBoxLiteDaytona (self-hosted)
Isolation modelApplication kernel (syscall interception)Micro-VM (dedicated guest kernel)User namespaces + procfs/sysfs virtualizationMicro-VM (Firecracker-class)VM + full sandbox lifecycle
Streaming interactionYesNo (batch only)YesYes (via exec + port forwarding)Yes (via Toolbox API)
Standard EKS/GKE (no custom AMI)Yes (DaemonSet install)No (needs nested virt + custom shim)No (needs host-installed daemons)No (library model, KVM required)No (9+ service control plane)
Kernel-level isolationYesYesPartial (shared host kernel)YesYes
Integration complexityLow (swap containerd runtime flag)High (netns plumbing, no port mapping)Medium (host install required)High (new execution mode)Very high (full platform)

Kata Containers were removed from Chetter. They cannot expose a port from the micro-VM back to the runner host through ctr, so the interactive serve flow is impossible — Kata runs the agent as a batch command and scrapes stdout. They also require nested virtualization and custom AMIs on managed Kubernetes, defeating operational simplicity.

Sysbox provides good isolation (user namespaces, virtualized /proc and /sys) and supports streaming, but must be installed on the host (sysbox-runc, sysbox-mgr, sysbox-fs). This rules out managed Kubernetes without custom AMIs.

BoxLite offers hardware-level micro-VM isolation with an embeddable library model, but requires KVM on the host and uses a SDK interaction model rather than containerd, requiring a new Chetter execution mode.

Daytona (self-hosted) provides the most complete sandboxing platform, but requires deploying its full control plane (PostgreSQL, Redis, MinIO, NestJS API, proxy, SSH gateway, registry). This is a heavy infrastructure dependency for what Chetter needs.

Enabling gVisor on a standard Kubernetes cluster

gVisor can be installed on any Kubernetes cluster using a DaemonSet — no custom AMIs required. The DaemonSet copies the runsc binary and containerd-shim-runsc-v1 onto each node, updates the containerd configuration, and restarts containerd.

1. Install gVisor on the nodes

Apply the DaemonSet that installs runsc on every node:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: gvisor-installer
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: gvisor-installer
  template:
    metadata:
      labels:
        app: gvisor-installer
    spec:
      hostPID: true
      containers:
      - name: installer
        image: gcr.io/gvisor-containers/runsc:latest
        securityContext:
          privileged: true
        volumeMounts:
        - name: host-bin
          mountPath: /host-bin
        - name: host-containerd
          mountPath: /etc/containerd
        command: ["/bin/sh", "-c"]
        args:
        - |
          cp /usr/local/bin/runsc /host-bin/runsc
          cp /usr/local/bin/containerd-shim-runsc-v1 /host-bin/containerd-shim-runsc-v1
          if ! grep -q "runsc" /etc/containerd/config.toml; then
            cat >> /etc/containerd/config.toml <<'EOF'

          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
            runtime_type = "io.containerd.runsc.v1"
          EOF
            nsenter -t 1 -m systemctl restart containerd
          fi
          sleep infinity
      volumes:
      - name: host-bin
        hostPath:
          path: /usr/local/bin
      - name: host-containerd
        hostPath:
          path: /etc/containerd

2. Register the RuntimeClass

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor
handler: runsc

3. Annotate runner pods

Set runtimeClassName: gvisor on the Chetter runner pod spec. Pods without this annotation continue to use the default runc runtime.

apiVersion: v1
kind: Pod
metadata:
  name: chetter-runner
spec:
  runtimeClassName: gvisor
  containers:
  - name: runner
    image: ghcr.io/flatout-works/chetter-runner:main
    # ...

4. GKE shortcut

On Google Kubernetes Engine, gVisor is available as a built-in feature. Create a node pool with gVisor enabled and GKE handles the rest — no DaemonSet needed. See GKE Sandbox for details.

The trade-off

gVisor adds per-syscall latency because every call is intercepted by the Sentry. For coding agent workloads (file I/O, git, compilation, HTTP calls) this is negligible. For syscall-heavy workloads (databases, high-frequency networking) the overhead can be noticeable. If that becomes a problem, runners can fall back to standard runc by omitting runtimeClassName: gvisor from the pod spec.

Network isolation

Regardless of the container runtime, Chetter runners provide outbound network filtering via a transparent HTTP proxy and DNS proxy. The proxy enforces an allowlist of domains and blocks everything else. This is independent of gVisor and works in all execution modes.

Custom Dev Container Images

Tasks run inside a "dev container" image specified by agent_image. Chetter ships several built-in variants, but you can create your own.

Built-in Variants

VariantImage TagContents
Golang (default)ghcr.io/flatout-works/chetter-runner:mainGo, buf, sqlc, goose, govulncheck, osv-scanner, gh, hcloud, opencode, claude-code
Pythonghcr.io/flatout-works/chetter-runner:pythonPython 3, pip, venv, ruff, mypy, pytest, opencode, claude-code
Node.jsghcr.io/flatout-works/chetter-runner:nodeNode 22, pnpm, TypeScript, eslint, prettier, opencode, claude-code
Rustghcr.io/flatout-works/chetter-runner:rustrustup, cargo, clippy, rustfmt, cargo-audit, opencode, claude-code
Minimalghcr.io/flatout-works/chetter-runner:minimalopencode, claude-code, git, curl — no language toolchain

Using an Image in a Task

Pass the image reference via agent_image:

{
  "prompt": "Refactor the FastAPI endpoints and add type hints.",
  "git_url": "https://github.com/my-org/my-api",
  "agent_image": "ghcr.io/flatout-works/chetter-runner:python"
}

Or set a default in the server config with DEFAULT_AGENT_IMAGE.

Creating a Custom Image

All images inherit from chetter-runner-base (except minimal which starts from debian:bookworm-slim). The base provides opencode, claude-code, git, and core tooling — you just add your language stack.

1. Create a Dockerfile

Put it under runner/images/<name>/Dockerfile:

# syntax=docker/dockerfile:1.7
ARG BASE_IMAGE=ghcr.io/flatout-works/chetter-runner-base:main

# Build stages (copy from any existing variant)
FROM golang:1.26-bookworm AS runner-builder
ARG CACHEBUST
WORKDIR /src
COPY go.mod go.sum* ./
COPY gen/ ./gen/
COPY runner/go.mod runner/go.sum* ./runner/
WORKDIR /src/runner
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go mod download
WORKDIR /src
COPY runner/ ./runner/
WORKDIR /src/runner
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o /out/runner ./cmd/runner

FROM golang:1.26-bookworm AS mcp-bridge-builder
WORKDIR /build
COPY runner/harness/mcp-bridge/main.go ./
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o /out/mcp-bridge ./main.go

# Final image: base + your tools + app layer
FROM ${BASE_IMAGE}

# --- Add your language/tool stack here ---
RUN apt-get update && apt-get install -y --no-install-recommends \
    my-language-runtime \
    && rm -rf /var/lib/apt/lists/*
# ------------------------------------------

# App layer (required — same for all variants)
COPY --from=runner-builder /out/runner /usr/local/bin/runner
COPY --from=mcp-bridge-builder /out/mcp-bridge /usr/local/bin/mcp-bridge
COPY runner/chetter-entrypoint.sh /usr/local/bin/chetter-entrypoint
COPY tools/skills/ /opt/opencode/.agents/skills/
COPY .opencode/agent/ /opt/opencode/.config/opencode/agent/
RUN chmod +x /usr/local/bin/runner /usr/local/bin/mcp-bridge /usr/local/bin/chetter-entrypoint \
    && chmod -R 755 /opt/opencode/.agents/skills /opt/opencode/.config/opencode/agent

ENV RUNNER_LOCAL=true
ENV RUNNER_WORKSPACE_ROOT=/var/lib/chetter-runner/workspaces
WORKDIR /var/lib/chetter-runner/workspaces
ENTRYPOINT ["chetter-entrypoint"]

The only hard requirements for the image are:

  • opencode binary in $PATH (or claude for the Claude Code harness)
  • HOME=/opt/opencode set in the environment
  • The chetter-entrypoint as ENTRYPOINT

2. Build it

# From the repo root
docker build -f runner/images/myvariant/Dockerfile -t my-org/chetter-runner:myvariant .

3. Push to a registry

docker push my-org/chetter-runner:myvariant

4. Use it

{
  "prompt": "Fix the build pipeline.",
  "git_url": "https://github.com/my-org/my-repo",
  "agent_image": "my-org/chetter-runner:myvariant"
}

Adding a Makefile Target

For convenience, add a build target to the root Makefile:

docker-build-myvariant:
	docker build -f runner/images/myvariant/Dockerfile -t $(RUNNER_IMAGE)-myvariant .

Image Contract

The runner injects these environment variables into every container at runtime:

VariableDescription
TASK_IDThe task identifier
WORKSPACEPath to the cloned repo (typically /workspace)
MCP_SOCKET_PATHUnix socket for the runner-bridge MCP server
HOMESet to /opt/opencode
XDG_CONFIG_HOMESet to /opt/opencode/.config
CHETTER_AGENT_NAMEAgent name from the task request
CHETTER_MODEL_IDResolved LLM model identifier
CHETTER_RUNNER_IMAGEImage reference of the runner itself
CHETTER_RUNNER_IMAGE_DIGESTDigest of the runner image

Secrets (API keys) are forwarded automatically when set in the runner's environment.

Build From Source

make check
make build

Build images locally:

make docker-build-mcp
make docker-build-runner-base
make docker-build-runner

License

MIT

Ver o original no GitHub

Relacionados