# ClawLess Documentation

## Table of Contents

- [Architecture Overview](#architecture-overview)
- [SDK API Reference](#sdk-api-reference)
  - [ClawContainer Class](#clawcontainer-class)
- [Plugin System](#plugin-system)
  - [ClawContainerPlugin Interface](#clawcontainerplugin-interface)
  - [TabDefinition](#tabdefinition)
- [Template System](#template-system)
- [Policy Engine](#policy-engine)
  - [Policy Structure](#policy-structure)
  - [PolicyAction Types](#policyaction-types)
  - [Rules](#rules)
  - [YAML Format](#yaml-format)
  - [Glob Matching](#glob-matching)
  - [PolicyEngine Methods](#policyengine-methods)
- [Audit Logging](#audit-logging)
  - [AuditEntry](#auditentry)
  - [AuditLog Methods](#auditlog-methods)
- [Git Service](#git-service)
  - [GitService](#gitservice)
  - [Supported URL Formats](#supported-url-formats)
- [Network Interception](#network-interception)
  - [Browser-side (net-intercept.ts)](#browser-side-net-interceptts)
  - [Container-side (network-hook.ts)](#container-side-network-hookts)
- [Configuration](#configuration)
  - [Environment Variables](#environment-variables)
  - [Supported Providers & Models](#supported-providers--models)
  - [LocalStorage Persistence](#localstorage-persistence)
- [Security Model](#security-model)

## Architecture Overview

ClawLess is a browser-based AI agent container runtime built on WebContainers. Data flow:

```
User Input → ClawContainer (SDK) → ContainerManager → WebContainer
                                  → PolicyEngine (enforce)
                                  → AuditLog (record)
                                  → GitService (sync)
                                  → TerminalManager (display)
                                  → UIManager → PluginManager
                                  → EventEmitter → Plugins
```

## SDK API Reference

### ClawContainer Class

Constructor: `new ClawContainer(selector: string, options?: ClawContainerOptions)`

**ClawContainerOptions:**

```typescript
interface ClawContainerOptions {
  agent?: AgentConfig | false;
  workspace?: Record<string, string>;
  services?: Record<string, string>;
  env?: Record<string, string>;
  startupScript?: string;
  template?: string | ContainerTemplate;
  plugins?: ClawContainerPlugin[];
  tabs?: TabDefinition[];
}
```

**Lifecycle Methods:**

- `start(): Promise<void>` - Boot container, install deps, configure env, launch agent
- `stop(): Promise<void>` - Stop container and dispatch onDestroy to plugins
- `restart(): Promise<void>` - Stop then start

**Command Execution:**

- `exec(cmd: string): Promise<string>` - Execute command and return output
- `shell(): Promise<void>` - Open interactive shell
- `sendInput(data: string): Promise<void>` - Send input to running process

**File System (cc.fs):**

- `read(path): Promise<string>`
- `write(path, content): Promise<void>`
- `list(dir?): Promise<string[]>`
- `mkdir(path): Promise<void>`
- `remove(path): Promise<void>`

**Git (cc.git):**

- `clone(url, token): Promise<void>`
- `push(message?): Promise<string>`

**Events:**

```typescript
type ClawContainerEvents = {
  ready: [];
  error: [error: Error];
  status: [status: string];
  'file.change': [path: string];
  'process.exit': [code: number];
  'server.ready': [port: number, url: string];
  log: [entry: AuditEntry];
};
```

- `on(event, fn)`, `off(event, fn)`, `once(event, fn)`

**Plugin & Tab:**

- `use(plugin: ClawContainerPlugin): void`
- `addTab(def: TabDefinition): void`
- `removeTab(id: string): void`

**Static:**

- `ClawContainer.registerTemplate(template): void`
- `ClawContainer.parseTemplate(yaml): ContainerTemplate`

## Plugin System

### ClawContainerPlugin Interface

```typescript
interface ClawContainerPlugin {
  name: string;
  services?: Record<string, string>;
  workspace?: Record<string, string>;
  env?: Record<string, string>;
  tabs?: TabDefinition[];
  onInit?(cc: ClawContainerSDK): void;
  onReady?(cc: ClawContainerSDK): void;
  onDestroy?(cc: ClawContainerSDK): void;
}
```

Lifecycle: onInit (after register, before boot) → onReady (after container ready) → onDestroy (on stop).
Plugins can merge services, workspace files, env vars, and custom tabs.

### TabDefinition

```typescript
interface TabDefinition {
  id: string;
  label: string;
  render: string | ((container: HTMLDivElement) => void);
}
```

## Template System

Templates pre-configure agent, workspace, services, env, tabs.

```typescript
interface ContainerTemplate {
  name: string;
  description?: string;
  agent?: AgentConfig | false;
  workspace?: Record<string, string>;
  services?: Record<string, string>;
  env?: Record<string, string>;
  startupScript?: string;
  tabs?: TabDefinition[];
}
```

Built-in template: `gitclaw` (gitclaw@1.1.4 agent).

YAML template format example:

```yaml
name: my-template
description: My custom template
agent:
  package: gitclaw
  version: 1.1.4
  entry: dist/index.js
  args: ["--dir", "<home>/workspace"]
workspace:
  'src/index.ts': |
    export function hello() {}
services:
  lodash: "4.17.21"
env:
  DEBUG: "true"
startupScript: npm run build
```

Register via `ClawContainer.registerTemplate(template)` or pass template name/object in options.

## Policy Engine

YAML-based guardrails for controlling agent behavior.

### Policy Structure

```typescript
interface Policy {
  version: '1';
  mode: 'allow-all' | 'deny-all';
  files: { read: FileRule[]; write: FileRule[] };
  processes: ProcessRule[];
  ports: PortRule[];
  tools: ToolRule[];
  limits: RuntimeLimits;
}
```

### PolicyAction Types

`file.read`, `file.write`, `process.spawn`, `server.bind`, `env.configure`, `tool.use`, `git.clone`, `git.push`

### Rules

```typescript
interface FileRule { pattern: string; allow: boolean; }
interface ProcessRule { pattern: string; allow: boolean; }
interface PortRule { port: number | '*'; allow: boolean; }
interface ToolRule { name: string; allow: boolean; }
interface RuntimeLimits {
  maxFileSize: number;    // default 10MB
  maxProcesses: number;   // default 10
  maxTurns: number;       // default 50
  timeoutSec: number;     // default 120
}
```

### YAML Format

```yaml
version: "1"
mode: allow-all
files:
  read:
    - pattern: "workspace/**"
      allow: true
    - pattern: "node_modules/**"
      allow: false
  write:
    - pattern: "workspace/**"
      allow: true
processes:
  - pattern: "npm *"
    allow: true
  - pattern: "rm -rf *"
    allow: false
ports:
  - port: "*"
    allow: true
tools:
  - name: "*"
    allow: true
limits:
  maxFileSize: 10485760
  maxProcesses: 10
  maxTurns: 50
  timeoutSec: 120
```

### Glob Matching

Supports `*` (single segment), `**` (any depth), `?` (single char).

### PolicyEngine Methods

- `check(action, subject, meta?): CheckResult` - Check without throwing
- `enforce(action, subject, meta?): CheckResult` - Throws PolicyDeniedError if denied
- `loadPolicy(policy)`, `getPolicy()`, `toYaml()`, `static fromYaml(yaml)`

## Audit Logging

### AuditEntry

```typescript
interface AuditEntry {
  timestamp: string;          // ISO8601
  event: AuditEvent;
  detail: string;
  meta?: Record<string, unknown>;
  source?: AuditSource;
  level?: AuditLevel;
}
```

**Sources:** `boot`, `user`, `agent`, `system`, `policy`

**Levels:** `info`, `warn`, `error`

**Events:**
`process.spawn`, `process.exit`, `file.read`, `file.write`, `io.stdout`, `io.stdin`, `env.configure`, `server.ready`, `status.change`, `policy.deny`, `policy.load`, `boot.mount`, `net.request`, `net.response`, `git.clone`, `git.push`

### AuditLog Methods

- `log(event, detail, meta?, opts?)` - Log an entry
- `filter({ source?, level?, event? })` - Filter entries
- `toText()` - Export grouped by source
- `toJSON()` - Export as JSON
- `onEntry(fn)` - Subscribe (returns unsubscribe fn)
- `static maskKey(val)` - Mask API keys
- `static maskHeaders(headers)` - Mask sensitive headers

## Git Service

Browser-native GitHub integration using the GitHub REST API (no git binary).

### GitService

```typescript
constructor(token: string, owner: string, repo: string, branch?: string)
static parseRepoUrl(url: string): { owner: string; repo: string }
async detectDefaultBranch(): Promise<string>
async fetchRepoTree(): Promise<GitFile[]>   // batch fetch, skip >1MB, max 10 concurrent
async pushChanges(files: GitFile[], message: string): Promise<string>  // atomic: blobs→tree→commit→ref
```

### Supported URL Formats

Handles `https://github.com/owner/repo`, `https://github.com/owner/repo.git`, and other GitHub URL formats.

## Network Interception

### Browser-side (net-intercept.ts)

Patches `window.fetch` to log all outbound HTTP requests with:

- Request: method, headers (masked), body preview
- Response: status, headers, duration

### Container-side (network-hook.ts)

Node.js hook injected via `NODE_OPTIONS=--require ./network-hook.cjs`. Patches:

- `http.request()` & `http.get()`
- `https.request()` & `https.get()`
- `globalThis.fetch()` (Node 18+)

Output format: `__NET_AUDIT__:{json}` on stderr, parsed by ContainerManager.
Sensitive headers masked. Bodies truncated to 2000 chars. Skipped during npm install.

## Configuration

### Environment Variables

Configure through the UI config panel or programmatically via options.env:

- `ANTHROPIC_API_KEY` - Anthropic API key
- `OPENAI_API_KEY` - OpenAI API key
- `GOOGLE_API_KEY` - Google AI API key
- `GITHUB_TOKEN` - GitHub personal access token (for git operations)

### Supported Providers & Models

- **Anthropic:** claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
- **OpenAI:** gpt-4o, gpt-4o-mini, o3-mini
- **Google:** gemini-2.0-flash, gemini-2.5-pro

### LocalStorage Persistence

Config persisted with `clawchef_` prefix:

- `clawchef_provider`, `clawchef_model`, `clawchef_envVars`, `clawchef_policy`

## Security Model

- **Sandboxing:** All code runs inside a WebContainer (WASM-based). No access to host filesystem or network beyond browser APIs.
- **Policy enforcement:** Every file read/write, process spawn, and port bind is checked against the policy engine before execution.
- **Network auditing:** All HTTP requests (browser and container) are intercepted, logged, and sensitive headers masked.
- **API key masking:** Keys are masked in logs (first 7 + last 4 chars visible).
- **COOP/COEP headers:** Required for SharedArrayBuffer (WebContainer). Configured via Vite dev server.