ClawCrate: Instructions file for Claude Code

CLAUDE.md — ClawCrate Development Guide

Project Overview

ClawCrate is a secure execution runtime for AI agents. A single Rust binary per platform (~15-20MB) that sandboxes shell commands using native OS primitives: Landlock + seccomp on Linux, Seatbelt on macOS. No Docker, no VMs, no root required.

This file is the source of truth for all development work. Read it fully before writing any code.

Specification document: docs/clawcrate-v3.1.1.md contains the full project specification including architecture decisions, competitive landscape, and rationale for every design choice. This CLAUDE.md extracts the actionable implementation details.

---

Core Architecture

clawcrate run --profile build -- cargo test
    │
    ├── Parse CLI args (clap)
    ├── Resolve profile (safe|build|install|open or custom YAML)
    ├── Auto-detect stack if no profile specified (Cargo.toml → rust, package.json → node)
    ├── Determine workspace mode: DefaultMode from profile + CLI flags (--replica/--direct)
    ├── Materialize WorkspaceMode: if Replica, create temp dir + filtered copy
    ├── Scrub environment variables (remove *_SECRET*, *_TOKEN, *_KEY, etc.)
    ├── Generate execution plan (plan.json)
    │
    ├── LAUNCH (platform-specific):
    │     Linux:  fork → set rlimits → apply Landlock → apply seccomp → exec
    │     macOS:  generate SBPL → exec via /usr/bin/sandbox-exec
    │
    ├── CAPTURE: pipe stdout/stderr, monitor child process
    ├── COLLECT: wait for exit, compute fs-diff (snapshot pre vs post)
    ├── WRITE ARTIFACTS: plan.json, result.json, stdout.log, stderr.log, audit.ndjson, fs-diff.json
    │
    └── Report result to user (human-readable or --json)

Key Design Decisions — DO NOT DEVIATE

1. Deny by default. The sandboxed process starts with zero permissions and receives only what the profile grants. Never start permissive and restrict.

2. Platform-native sandboxing only. Linux uses Landlock + seccomp. macOS uses Seatbelt. No Docker, no VMs, no containers. The sandbox is kernel-level, irremovible from inside, and inherited by all child processes.