mitos: Instructions file for Claude Code

CLAUDE.md

Project Overview

Snapshot-fork sandboxes for AI agents on Kubernetes. The system boots Firecracker microVMs, forks them via copy-on-write snapshots, and exposes the whole lifecycle through declarative CRDs (SandboxPool, Sandbox, Workspace) in API group mitos.run/v1.

Components:

• controller (Deployment): reconciles the CRDs, selects nodes, drives forkd.
• forkd (DaemonSet): per-node fork daemon; gRPC on :9090 for the controller, HTTP sandbox API on :9091 for exec and file traffic.
• guest agent (PID 1 in the VM): speaks the vsock protocol for exec, files, env, and fork notifications.
• sandbox-server (standalone): the same engine behind a plain REST API, no Kubernetes required.
• Python SDK (sdk/python): client for both k8s mode and sandbox-server mode.

ROADMAP.md is the priority order for all work. docs/api/v2-spec.md is the target API.

Operating Principles

These outrank convenience:

1. No unverified claims. Every public number must be reproducible from bench/ or it does not get written.
2. Security findings block features. The threat model (docs/threat-model.md) must be updated in the same PR whenever the security surface moves.
3. Honest Kubernetes semantics. Sandboxes are not pods; never imply pod-scoped mechanisms (NetworkPolicy, ResourceQuota, PSA) govern them.
4. Boring failure behavior. Every component defines what happens on crash, node loss, slow etcd, and capacity exhaustion.
5. Bare metal is a first-class target.
6. Experience is DNA. Every user-facing surface follows the journey rules: no dead ends, simple surface with depth one click down, intent-shaped aha. See docs/superpowers/specs/2026-06-27-hosted-launch-journey-design.md.
7. Self-host is first-class (Apache-2.0). mitos is open source and people run it themselves; the self-hosted experience is a peer of the hosted one, never an afterthought to the SaaS. One console image and SPA serve both, differing ONLY by the capabilities document (GET /console/capabilities); never fork an edition build. Every hosted-only surface (self-serve signup, billing, credits and top-up, the allowlist gate, Paddle, abuse email checks) MUST be capability-gated so a self-hoster gets a clean, complete product: no dead links, no empty billing panels, no "add credits" or signup prompts. The journey rules apply to the community first-run too; it points at the SDK/CLI and a real first success, never at a paywall.