{
  "title": "Quilt Documentation",
  "description": "Complete guide to building with Quilt — container infrastructure for AI agents.",
  "url": "https://quilt.sh/docs",
  "sections": [
    {
      "id": "intro",
      "title": "What is Quilt",
      "content": [
        {
          "type": "heading",
          "level": 3,
          "text": "The Problem"
        },
        {
          "type": "paragraph",
          "text": "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."
        },
        {
          "type": "paragraph",
          "text": "This is unacceptable."
        },
        {
          "type": "paragraph",
          "text": "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."
        },
        {
          "type": "heading",
          "level": 3,
          "text": "The Solution"
        },
        {
          "type": "paragraph",
          "text": "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."
        },
        {
          "type": "code",
          "language": "typescript",
          "code": "// One tool. Complete isolation.\nconst container = await quilt.create({\n  cmd: ['python3', 'analyze.py']\n});\n\n// Something wrong? Kill it.\nawait quilt.kill({ container_id: container.container_id });"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Key Benefits"
        },
        {
          "type": "cards",
          "items": [
            {
              "term": "Scoped Access Privileges",
              "description": "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."
            },
            {
              "term": "Parallel Execution",
              "description": "Spin up multiple container instances running different code versions or approaches. The agent can compare outcomes across isolated environments simultaneously."
            },
            {
              "term": "Reversible Operations",
              "description": "Every action an agent takes inside a container can be undone by terminating that container."
            },
            {
              "term": "Collaborative Development",
              "description": "The same container runtime works via CLI for human developers. You and your agent can work inside the same containerized environments."
            }
          ]
        }
      ]
    },
    {
      "id": "how-it-works",
      "title": "How It Works",
      "content": [
        {
          "type": "heading",
          "level": 3,
          "text": "Technology Stack"
        },
        {
          "type": "table",
          "headers": [
            "Component",
            "Technology",
            "Purpose"
          ],
          "rows": [
            [
              "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"
            ]
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Architecture"
        },
        {
          "type": "pre",
          "text": "CLI/SDK ──gRPC:50051──> Daemon Server\n                           │\n                           ├─ Sync Engine (SQLite)\n                           ├─ Container Runtime (namespaces/cgroups)\n                           ├─ Network Manager (bridge/DNS)\n                           └─ Background Services"
        },
        {
          "type": "paragraph",
          "text": "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."
        },
        {
          "type": "callout",
          "text": "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."
        }
      ]
    },
    {
      "id": "containers",
      "title": "Containers",
      "content": [
        {
          "type": "heading",
          "level": 3,
          "text": "Isolation"
        },
        {
          "type": "paragraph",
          "text": "Each container gets full Linux namespace isolation:"
        },
        {
          "type": "list",
          "items": [
            {
              "term": "PID",
              "description": "Process tree isolation"
            },
            {
              "term": "Mount",
              "description": "Filesystem isolation"
            },
            {
              "term": "Network",
              "description": "Network stack isolation"
            },
            {
              "term": "UTS",
              "description": "Hostname isolation"
            },
            {
              "term": "IPC",
              "description": "Inter-process communication isolation"
            },
            {
              "term": "Cgroups",
              "description": "Resource limits (CPU, memory, PIDs)"
            }
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Container Environments"
        },
        {
          "type": "paragraph",
          "text": "Containers are created with minimal NixOS-based environments optimized for agent workloads."
        },
        {
          "type": "paragraph",
          "text": "Each container includes BusyBox with 100+ utilities (ls, cat, grep, curl, wget, etc.), allowing agents to execute commands immediately."
        },
        {
          "type": "paragraph",
          "text": "Containers support custom configurations through the SDK."
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Resource Limits"
        },
        {
          "type": "paragraph",
          "text": "Default limits per container:"
        },
        {
          "type": "list",
          "items": [
            {
              "description": "Memory: 512MB"
            },
            {
              "description": "CPU: 50%"
            },
            {
              "description": "PIDs: 1024 (prevents fork bombs)"
            }
          ]
        },
        {
          "type": "paragraph",
          "text": "Kernel OOM killer handles memory violations. CPU uses CFS scheduler."
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Lifecycle"
        },
        {
          "type": "pre",
          "text": "CREATE → START → RUNNING → STOP/KILL → REMOVE\n           ↓\n         EXEC (run commands while running)\n           ↓\n         LOGS (retrieve output)"
        },
        {
          "type": "paragraph",
          "text": "Containers are persistent by default. They maintain state until explicitly removed."
        },
        {
          "type": "heading",
          "level": 3,
          "text": "States"
        },
        {
          "type": "list",
          "items": [
            {
              "term": "PENDING",
              "description": "Created, not started"
            },
            {
              "term": "RUNNING",
              "description": "Active"
            },
            {
              "term": "EXITED",
              "description": "Completed"
            },
            {
              "term": "FAILED",
              "description": "Failed to start"
            }
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Volumes"
        },
        {
          "type": "paragraph",
          "text": "Persistent storage options:"
        },
        {
          "type": "list",
          "items": [
            {
              "term": "Named volumes",
              "description": "Managed by Quilt, persist independently"
            },
            {
              "term": "Bind mounts",
              "description": "Map host directories (/host:/container)"
            },
            {
              "term": "Tmpfs",
              "description": "In-memory storage"
            }
          ]
        }
      ]
    },
    {
      "id": "networking",
      "title": "Networking",
      "content": [
        {
          "type": "heading",
          "level": 3,
          "text": "Bridge Architecture"
        },
        {
          "type": "paragraph",
          "text": "All containers connect via quilt0 bridge at 10.42.0.1. Each container gets:"
        },
        {
          "type": "list",
          "items": [
            {
              "description": "Unique IP from 10.42.x.x pool"
            },
            {
              "description": "Virtual ethernet pair (veth) connecting to bridge"
            },
            {
              "description": "Default route via bridge"
            }
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "DNS Resolution"
        },
        {
          "type": "paragraph",
          "text": "Built-in DNS server resolves container names to IPs:"
        },
        {
          "type": "list",
          "items": [
            {
              "description": "container-name → 10.42.x.x"
            },
            {
              "description": "FQDN: container-name.quilt.local"
            }
          ]
        },
        {
          "type": "paragraph",
          "text": "Containers can communicate by name automatically:"
        },
        {
          "type": "code",
          "language": "typescript",
          "code": "const server = await quilt.create({\n  name: 'api',\n  cmd: ['python3', '-m', 'http.server', '8000']\n});\n\nconst client = await quilt.create({\n  name: 'client',\n  cmd: ['curl', 'http://api:8000/data']\n});"
        }
      ]
    },
    {
      "id": "sdk",
      "title": "SDK Syntax and Examples",
      "content": [
        {
          "type": "heading",
          "level": 3,
          "text": "Connection"
        },
        {
          "type": "code",
          "language": "typescript",
          "code": "import Quilt from 'quilt-sdk';\n\nconst quilt = await Quilt.connect({\n  apiBaseUrl: 'http://localhost:8080', // Default\n  token: 'optional-auth-token',\n  timeout: 30000  // 30s default\n});"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Property Name Flexibility"
        },
        {
          "type": "paragraph",
          "text": "All naming conventions normalize internally:"
        },
        {
          "type": "code",
          "language": "typescript",
          "code": "// Short form\nawait quilt.create({\n  cmd: ['node', 'app.js'],\n  env: { PORT: '3000' },\n  memory: 512,\n  cpu: 50\n});\n\n// Camel case / Snake case also supported"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Complete Example"
        },
        {
          "type": "code",
          "language": "typescript",
          "code": "import Quilt from 'quilt-sdk';\n\nasync function main() {\n  const quilt = await Quilt.connect();\n\n  // Create container\n  const container = await quilt.create({\n    name: 'worker',\n    env: { WORKER_ID: '001' },\n    memory: 256\n  });\n\n  // Execute command\n  const result = await quilt.exec({\n    container_id: container.container_id,\n    capture_output: true\n  });\n\n  // Stop and remove\n  await quilt.stop({ container_id: container.container_id });\n  await quilt.remove({ container_id: container.container_id });\n}"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Parallel Operations"
        },
        {
          "type": "code",
          "language": "typescript",
          "code": "const [web, api, db] = await Promise.all([\n  quilt.create({ name: 'web', cmd: ['nginx'] }),\n  quilt.create({ name: 'api', cmd: ['node', 'server.js'] }),\n  quilt.create({ name: 'db', cmd: ['postgres'] })\n]);"
        }
      ]
    },
    {
      "id": "api",
      "title": "API Reference",
      "content": [
        {
          "type": "heading",
          "level": 3,
          "text": "Container Operations"
        },
        {
          "type": "table",
          "headers": [
            "Method",
            "Description"
          ],
          "rows": [
            [
              "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"
            ]
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Volume Operations"
        },
        {
          "type": "table",
          "headers": [
            "Method",
            "Description"
          ],
          "rows": [
            [
              "createVolume(params)",
              "Create volume"
            ],
            [
              "removeVolume(params)",
              "Delete volume"
            ],
            [
              "listVolumes()",
              "List all volumes"
            ],
            [
              "inspectVolume(params)",
              "Get volume details"
            ]
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Network Operations"
        },
        {
          "type": "table",
          "headers": [
            "Method",
            "Description"
          ],
          "rows": [
            [
              "listNetworkAllocations()",
              "List all network allocations"
            ],
            [
              "getContainerNetwork(params)",
              "Get container network config"
            ],
            [
              "setContainerNetwork(params)",
              "Set network config"
            ],
            [
              "listDNSEntries()",
              "List DNS mappings"
            ]
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Health and Monitoring"
        },
        {
          "type": "table",
          "headers": [
            "Method",
            "Description"
          ],
          "rows": [
            [
              "health()",
              "Server health status"
            ],
            [
              "getMetrics(params)",
              "Resource metrics"
            ],
            [
              "getSystemInfo()",
              "System information"
            ],
            [
              "listMonitors()",
              "List active monitors"
            ]
          ]
        }
      ]
    },
    {
      "id": "cli",
      "title": "CLI Usage",
      "content": [
        {
          "type": "paragraph",
          "text": "Same binary as daemon, different subcommand."
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Daemon Management"
        },
        {
          "type": "code",
          "language": "bash",
          "code": "quilt daemon start          # Foreground\nquilt daemon stop           # Stop\nquilt daemon restart        # Restart"
        },
        {
          "type": "paragraph",
          "text": "Port: 50051 (gRPC)"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Core Commands"
        },
        {
          "type": "code",
          "language": "bash",
          "code": "quilt create --name my-container -- /bin/sh\nquilt list\nquilt status <id>\nquilt logs <id>\nquilt exec <id> <command>\nquilt shell <id>              # Interactive shell\nquilt stop <id>\nquilt remove <id> [--force]"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Create Flags"
        },
        {
          "type": "table",
          "headers": [
            "Flag",
            "Default"
          ],
          "rows": [
            [
              "--name",
              "Container name"
            ],
            [
              "--memory-limit",
              "512 MB"
            ],
            [
              "--cpu-limit",
              "50%"
            ],
            [
              "-v /host:/container",
              "Bind mount"
            ],
            [
              "--env KEY=VALUE",
              "Environment"
            ],
            [
              "--async-mode",
              "Keep alive"
            ]
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Volume Management"
        },
        {
          "type": "code",
          "language": "bash",
          "code": "quilt volume create <name>\nquilt volume list\nquilt volume remove <name>"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Example Workflow"
        },
        {
          "type": "code",
          "language": "bash",
          "code": "# Create container\nquilt create --cmd 'python3 server.py' --memory 512 --cpu 50\n\n# Create with environment variables\nquilt create --cmd 'node app.js' --env PORT=3000 --env NODE_ENV=production\n\n# Execute commands\nquilt exec myproject npm install\nquilt exec myproject npm test\n\n# Cleanup\nquilt remove myproject --force"
        }
      ]
    },
    {
      "id": "self-hosting",
      "title": "Self-Hosting",
      "content": [
        {
          "type": "heading",
          "level": 3,
          "text": "Requirements"
        },
        {
          "type": "list",
          "items": [
            {
              "term": "OS",
              "description": "Linux only"
            },
            {
              "term": "Architecture",
              "description": "x86_64"
            },
            {
              "term": "Privileges",
              "description": "Root (for namespaces/cgroups)"
            },
            {
              "term": "Kernel",
              "description": "Namespace support enabled"
            }
          ]
        },
        {
          "type": "paragraph",
          "text": "Not supported: macOS, Windows, ARM"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Build"
        },
        {
          "type": "code",
          "language": "bash",
          "code": "cargo build --release\n# Binary: ./target/release/quilt"
        },
        {
          "type": "paragraph",
          "text": "Dependencies: Rust toolchain, protoc"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Generate Images"
        },
        {
          "type": "code",
          "language": "bash",
          "code": "./scripts/dev.sh generate minimal    # Basic shell\n./scripts/dev.sh generate dev        # Development tools\n./scripts/dev.sh generate python     # Python environment"
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Start Daemon"
        },
        {
          "type": "code",
          "language": "bash",
          "code": "./target/release/quilt daemon start"
        },
        {
          "type": "paragraph",
          "text": "Configure logging via RUST_LOG environment variable."
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Agent Integration"
        },
        {
          "type": "paragraph",
          "text": "The SDK exports OpenAI-compatible function schemas:"
        },
        {
          "type": "code",
          "language": "typescript",
          "code": "import { QUILT_TOOLS } from 'quilt-sdk';\n// 26 tool definitions ready for function calling"
        },
        {
          "type": "paragraph",
          "text": "Agents can use Quilt directly as a tool without wrapper code."
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Summary"
        },
        {
          "type": "callout",
          "text": "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."
        }
      ]
    }
  ]
}