Krellin

A local-first runtime for AI-assisted development that keeps agent work sandboxed, repeatable, and explainable.

1. Project Overview

Krellin pairs a lightweight daemon with per-repo Docker capsules so AI agents can run real commands and edit real files without directly touching your host environment.

The core goal is simple:

Let an agent do real work while keeping the host machine out of the blast radius.

Krellin is designed for developers who want agentic workflows but require:

• isolation (work happens in a capsule, not on the host)
• determinism (capsules can be reset to known-good state)
• traceability (the agent’s actions are serialized and inspectable)
• repeatability (workflows can be rerun with the same preconditions)

This is actively being exercised against real agent workflows, and the current design reflects early constraints around reproducibility, failure isolation, and toolchain drift.

Status: under active development. Expect breaking changes and rough edges.

Key Guarantees

• No host $HOME mount by default
• No Docker socket passthrough by default
• Actions are serialized and written to an ordered log
• Capsules are resettable to a known-good state

2. Design Principles

• Local-first: fast feedback loops without relying on hosted agent runtimes
• Safety by default: avoid implicit trust in the host filesystem and host privileges
• Deterministic resets: every repo capsule should be able to return to a clean known state
• Serialized work: agent actions are intentionally not free-for-all parallel chaos
• Auditable changes: it should be easy to answer “what happened?” and “what changed?”
• Explicit capability boundaries: the capsule’s allowed tools and access are deliberate, not accidental

3. What it looks like (today)

A typical loop is:

1. Start a repo capsule
2. Ask the agent to make a change
3. Inspect the action log
4. Reset and replay if needed

User/TUI ──> Krellin Daemon ──> Capsule (per repo)
                    │
                    └── Ordered action log (commands, patches, file writes)

4. Architecture

Krellin is split into three conceptual parts:

1. Daemon (Control Plane)
2. Capsules (Execution Plane)
3. Client / TUI (Operator Plane)

4.1 Daemon (Control Plane)

The daemon is responsible for:

• managing capsule lifecycle (create / start / stop / reset)
• mediating and serializing agent actions
• enforcing baseline safety invariants (no host home mount, no docker socket passthrough, etc.)
• providing a stable API for UI and integrations

Design goal: the daemon is predictable under failure.

4.2 Capsules (Execution Plane)

A capsule is a per-repo container environment that contains:

• the repo workspace
• a curated toolchain surface (shell tools, language runtimes, linters, formatters, etc.)
• network and filesystem constraints appropriate to the workflow

Invariants (non-negotiable):

• no host $HOME mount by default
• no host Docker socket by default
• capsule state can be reset deterministically
• capsule actions occur through the daemon’s mediation

4.3 Client / TUI (Operator Plane)

The UI exists to:

• show capsule status and active work
• present a clean action log
• make resets and reproductions easy
• keep the operator in control of what runs

5. Execution Model: Serialized Actions

Krellin treats agent work as a sequence of actions.

An action may be:

• running a command (go test, npm test, rg, etc.)
• writing/editing files
• applying a patch
• fetching dependencies
• generating an artifact

Core invariant: actions are serialized, producing an ordered event log.

This:

• makes outcomes explainable
• reduces non-deterministic drift
• creates a natural audit trail

6. Determinism & Resets

Krellin is built around fast, deterministic resets.

Reset scope typically includes:

• workspace reset to known git state
• tool state cleanup
• container recreation from pinned image

Goal: retries happen under the same conditions.

7. Tooling Surface Area

AI agents require a non-trivial CLI surface:

• language runtimes
• JSON/text tooling
• version control
• build systems

Krellin makes this surface:

• explicit
• reproducible
• declarative

Missing tools should be a build-time concern, not a runtime surprise.

8. Failure Modes & Safety Posture

Krellin prefers safe failure over silent recovery.

8.1 Docker unavailable

• Capsule fails to start
• Clear error surfaced
• No host mutation

8.2 Image drift

• Prefer pinned digests
• Fail fast rather than substituting

8.3 Bad agent output

• Inspect action log
• Reset capsule
• Replay deterministically

8.4 Host protection

Krellin aims to prevent:

• writes outside workspace
• host secret leakage
• privilege escalation

9. Design Constraints & Tradeoffs

• Serialization over parallelism
  • Improves determinism and debuggability
• Docker over custom sandboxing
  • Practical and available, though not perfect isolation
• Local-first over distributed execution
  • Optimizes for developer iteration speed

These tradeoffs are intentional and may evolve with real-world use.

10. Non-Goals (v1)

• Multi-host orchestration
• Consensus systems
• Perfect sandboxing against malicious actors
• Replacing container runtimes

11. Quick Start

curl -fsSL https://raw.githubusercontent.com/cbdeane/krellin/main/scripts/quickstart.sh | bash

Requirements: Docker, Git, Go.

12. What I’d Change Next

• improved multi-step task decomposition
• policy controls for capsule capabilities
• deterministic base images by default
• improved auth handling for tools
• better replay semantics

Closing Note

Krellin is intentionally opinionated: agentic workflows are only useful if they are resettable, replayable, and explainable.

The goal is not “AI writes code.”

The goal is agent work you can trust enough to run.