# 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.

```typescript
// 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:

```typescript
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

```typescript
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:

```typescript
// Short form
await quilt.create({
  cmd: ['node', 'app.js'],
  env: { PORT: '3000' },
  memory: 512,
  cpu: 50
});

// Camel case / Snake case also supported
```

### Complete Example

```typescript
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

```typescript
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

```bash
quilt daemon start          # Foreground
quilt daemon stop           # Stop
quilt daemon restart        # Restart
```

Port: 50051 (gRPC)

### Core Commands

```bash
quilt create --name my-container -- /bin/sh
quilt list
quilt status <id>
quilt logs <id>
quilt exec <id> <command>
quilt shell <id>              # Interactive shell
quilt stop <id>
quilt remove <id> [--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

```bash
quilt volume create <name>
quilt volume list
quilt volume remove <name>
```

### Example Workflow

```bash
# 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

```bash
cargo build --release
# Binary: ./target/release/quilt
```

Dependencies: Rust toolchain, protoc

### Generate Images

```bash
./scripts/dev.sh generate minimal    # Basic shell
./scripts/dev.sh generate dev        # Development tools
./scripts/dev.sh generate python     # Python environment
```

### Start Daemon

```bash
./target/release/quilt daemon start
```

Configure logging via RUST_LOG environment variable.

### Agent Integration

The SDK exports OpenAI-compatible function schemas:

```typescript
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.

---