QUILT DOCUMENTATION =================== Complete guide to building with Quilt — container infrastructure for AI agents. WHAT IS QUILT ============= The Problem ----------- Agents with external access operate on hope. Hope that they understand your intent correctly. Hope that they don't misinterpret a command. Hope that they don't execute something irreversible. This is unacceptable. When an agent has direct access to your filesystem, network, or system resources, a single misunderstanding can result in deleted files, corrupted data, or compromised security. The current paradigm treats agent access as binary: either full trust or no access at all. The Solution ------------ Quilt provides isolated container environments that agents can spin up, operate within, and terminate—all through a single tool integration. The agent gets a complete Linux environment with full capabilities, while you maintain absolute control over what persists. // One tool. Complete isolation. const container = await quilt.create({ cmd: ['python3', 'analyze.py'] }); // Something wrong? Kill it. await quilt.kill({ container_id: container.container_id }); Key Benefits ------------ * Scoped Access Privileges: Give an agent access to a container, not your entire system. The agent can read, write, execute, and network within that container. Your actual system remains untouched. * Parallel Execution: Spin up multiple container instances running different code versions or approaches. The agent can compare outcomes across isolated environments simultaneously. * Reversible Operations: Every action an agent takes inside a container can be undone by terminating that container. * Collaborative Development: The same container runtime works via CLI for human developers. You and your agent can work inside the same containerized environments. HOW IT WORKS ============ Technology Stack ---------------- Component Technology Purpose -------------- ---------- ------------------- Runtime Rust Core daemon Communication gRPC CLI/SDK to daemon State SQLite Fast async queries Container Base Nix Reproducible images Utilities BusyBox 100+ Unix utilities SDK TypeScript Client library Architecture ------------ CLI/SDK ──gRPC:50051──> Daemon Server │ ├─ Sync Engine (SQLite) ├─ Container Runtime (namespaces/cgroups) ├─ Network Manager (bridge/DNS) └─ Background Services Single unified binary serves as both daemon and CLI client. The Rust daemon manages container lifecycles, resource allocation, networking, and cleanup. The SDK communicates with the daemon over HTTP (bridged to internal gRPC), providing a TypeScript interface. Quilt places container management responsibility on the agent. The agent is intelligent enough to decide when to create containers, determine resource limits, execute commands, and clean up. Quilt provides the infrastructure. The agent provides the intelligence. CONTAINERS ========== Isolation --------- Each container gets full Linux namespace isolation: * PID: Process tree isolation * Mount: Filesystem isolation * Network: Network stack isolation * UTS: Hostname isolation * IPC: Inter-process communication isolation * Cgroups: Resource limits (CPU, memory, PIDs) Container Environments ---------------------- Containers are created with minimal NixOS-based environments optimized for agent workloads. Each container includes BusyBox with 100+ utilities (ls, cat, grep, curl, wget, etc.), allowing agents to execute commands immediately. Containers support custom configurations through the SDK. Resource Limits --------------- Default limits per container: * Memory: 512MB * CPU: 50% * PIDs: 1024 (prevents fork bombs) Kernel OOM killer handles memory violations. CPU uses CFS scheduler. Lifecycle --------- CREATE → START → RUNNING → STOP/KILL → REMOVE ↓ EXEC (run commands while running) ↓ LOGS (retrieve output) Containers are persistent by default. They maintain state until explicitly removed. States ------ * PENDING: Created, not started * RUNNING: Active * EXITED: Completed * FAILED: Failed to start Volumes ------- Persistent storage options: * Named volumes: Managed by Quilt, persist independently * Bind mounts: Map host directories (/host:/container) * Tmpfs: In-memory storage NETWORKING ========== Bridge Architecture ------------------- All containers connect via quilt0 bridge at 10.42.0.1. Each container gets: * Unique IP from 10.42.x.x pool * Virtual ethernet pair (veth) connecting to bridge * Default route via bridge DNS Resolution -------------- Built-in DNS server resolves container names to IPs: * container-name → 10.42.x.x * FQDN: container-name.quilt.local Containers can communicate by name automatically: const server = await quilt.create({ name: 'api', cmd: ['python3', '-m', 'http.server', '8000'] }); const client = await quilt.create({ name: 'client', cmd: ['curl', 'http://api:8000/data'] }); SDK SYNTAX AND EXAMPLES ======================= Connection ---------- import Quilt from 'quilt-sdk'; const quilt = await Quilt.connect({ apiBaseUrl: 'http://localhost:8080', // Default token: 'optional-auth-token', timeout: 30000 // 30s default }); Property Name Flexibility ------------------------- All naming conventions normalize internally: // Short form await quilt.create({ cmd: ['node', 'app.js'], env: { PORT: '3000' }, memory: 512, cpu: 50 }); // Camel case / Snake case also supported Complete Example ---------------- import Quilt from 'quilt-sdk'; async function main() { const quilt = await Quilt.connect(); // Create container const container = await quilt.create({ name: 'worker', env: { WORKER_ID: '001' }, memory: 256 }); // Execute command const result = await quilt.exec({ container_id: container.container_id, capture_output: true }); // Stop and remove await quilt.stop({ container_id: container.container_id }); await quilt.remove({ container_id: container.container_id }); } Parallel Operations ------------------- const [web, api, db] = await Promise.all([ quilt.create({ name: 'web', cmd: ['nginx'] }), quilt.create({ name: 'api', cmd: ['node', 'server.js'] }), quilt.create({ name: 'db', cmd: ['postgres'] }) ]); API REFERENCE ============= Container Operations -------------------- Method Description -------------------------- -------------------------------- create(params) Create new container start(params) Start stopped container stop(params) Graceful shutdown (with timeout) kill(params) Immediate termination remove(params) Delete container status(params) Get container state list() List all containers logs(params) Retrieve output logs exec(params) Execute command in container getContainerByName(params) Lookup by name Volume Operations ----------------- Method Description --------------------- ------------------ createVolume(params) Create volume removeVolume(params) Delete volume listVolumes() List all volumes inspectVolume(params) Get volume details Network Operations ------------------ Method Description --------------------------- ---------------------------- listNetworkAllocations() List all network allocations getContainerNetwork(params) Get container network config setContainerNetwork(params) Set network config listDNSEntries() List DNS mappings Health and Monitoring --------------------- Method Description ------------------ -------------------- health() Server health status getMetrics(params) Resource metrics getSystemInfo() System information listMonitors() List active monitors CLI USAGE ========= Same binary as daemon, different subcommand. Daemon Management ----------------- quilt daemon start # Foreground quilt daemon stop # Stop quilt daemon restart # Restart Port: 50051 (gRPC) Core Commands ------------- quilt create --name my-container -- /bin/sh quilt list quilt status quilt logs quilt exec quilt shell # Interactive shell quilt stop quilt remove [--force] Create Flags ------------ Flag Default ------------------- -------------- --name Container name --memory-limit 512 MB --cpu-limit 50% -v /host:/container Bind mount --env KEY=VALUE Environment --async-mode Keep alive Volume Management ----------------- quilt volume create quilt volume list quilt volume remove Example Workflow ---------------- # Create container quilt create --cmd 'python3 server.py' --memory 512 --cpu 50 # Create with environment variables quilt create --cmd 'node app.js' --env PORT=3000 --env NODE_ENV=production # Execute commands quilt exec myproject npm install quilt exec myproject npm test # Cleanup quilt remove myproject --force SELF-HOSTING ============ Requirements ------------ * OS: Linux only * Architecture: x86_64 * Privileges: Root (for namespaces/cgroups) * Kernel: Namespace support enabled Not supported: macOS, Windows, ARM Build ----- cargo build --release # Binary: ./target/release/quilt Dependencies: Rust toolchain, protoc Generate Images --------------- ./scripts/dev.sh generate minimal # Basic shell ./scripts/dev.sh generate dev # Development tools ./scripts/dev.sh generate python # Python environment Start Daemon ------------ ./target/release/quilt daemon start Configure logging via RUST_LOG environment variable. Agent Integration ----------------- The SDK exports OpenAI-compatible function schemas: import { QUILT_TOOLS } from 'quilt-sdk'; // 26 tool definitions ready for function calling Agents can use Quilt directly as a tool without wrapper code. Summary ------- Quilt transforms agent capability from dangerous to powerful. Give it a container. Let it experiment in complete isolation. When it's done—or if something goes wrong—clean up with a single command. The agent gets full Linux capabilities. You get complete control. That's Quilt.