@openparachute/agent 0.1.0

package/docs/docker-sandboxes.md

@@ -0,0 +1,359 @@
+# Running Paraclaw in Docker Sandboxes (Manual Setup)
+
+This guide walks through setting up Paraclaw inside a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) from scratch — no install script, no pre-built fork. You'll clone the upstream repo, apply the necessary patches, and have agents running in full hypervisor-level isolation.
+
+## Architecture
+
+```
+Host (macOS / Windows WSL)
+└── Docker Sandbox (micro VM with isolated kernel)
+    ├── Paraclaw process (Node.js)
+    │   ├── Channel adapters (WhatsApp, Telegram, etc.)
+    │   └── Container spawner → nested Docker daemon
+    └── Docker-in-Docker
+        └── paraclaw-agent containers
+            └── Claude Agent SDK
+```
+
+Each agent runs in its own container, inside a micro VM that is fully isolated from your host. Two layers of isolation: per-agent containers + the VM boundary.
+
+The sandbox provides a MITM proxy at `host.docker.internal:3128` that handles network access and injects your Anthropic API key automatically.
+
+> **Note:** This guide is based on a validated setup running on macOS (Apple Silicon) with WhatsApp. Other channels (Telegram, Slack, etc.) and environments (Windows WSL) may require additional proxy patches for their specific HTTP/WebSocket clients. The core patches (container runner, credential proxy, Dockerfile) apply universally — channel-specific proxy configuration varies.
+
+## Prerequisites
+
+- **Docker Desktop v4.40+** with Sandbox support
+- **Anthropic API key** (the sandbox proxy manages injection)
+- For **Telegram**: a bot token from [@BotFather](https://t.me/BotFather) and your chat ID
+- For **WhatsApp**: a phone with WhatsApp installed
+
+Verify sandbox support:
+```bash
+docker sandbox version
+```
+
+## Step 1: Create the Sandbox
+
+On your host machine:
+
+```bash
+# Create a workspace directory
+mkdir -p ~/paraclaw-workspace
+
+# Create a shell sandbox with the workspace mounted
+docker sandbox create shell ~/paraclaw-workspace
+```
+
+If you're using WhatsApp, configure proxy bypass so WhatsApp's Noise protocol isn't MITM-inspected:
+
+```bash
+docker sandbox network proxy shell-paraclaw-workspace \
+  --bypass-host web.whatsapp.com \
+  --bypass-host "*.whatsapp.com" \
+  --bypass-host "*.whatsapp.net"
+```
+
+Telegram does not need proxy bypass.
+
+Enter the sandbox:
+```bash
+docker sandbox run shell-paraclaw-workspace
+```
+
+## Step 2: Install Prerequisites
+
+Inside the sandbox:
+
+```bash
+sudo apt-get update && sudo apt-get install -y build-essential python3
+npm config set strict-ssl false
+```
+
+## Step 3: Clone and Install Paraclaw
+
+Paraclaw must live inside the workspace directory — Docker-in-Docker can only bind-mount from the shared workspace path.
+
+```bash
+# Clone to home first (virtiofs can corrupt git pack files during clone)
+cd ~
+git clone https://github.com/ParachuteComputer/paraclaw.git
+
+# Replace with YOUR workspace path (the host path you passed to `docker sandbox create`)
+WORKSPACE=/Users/you/paraclaw-workspace
+
+# Move into workspace so DinD mounts work
+mv paraclaw "$WORKSPACE/paraclaw"
+cd "$WORKSPACE/paraclaw"
+
+# Install dependencies
+pnpm install
+pnpm install https-proxy-agent
+```
+
+## Step 4: Apply Proxy and Sandbox Patches
+
+Paraclaw needs several patches to work inside a Docker Sandbox. These handle proxy routing, CA certificates, and Docker-in-Docker mount restrictions.
+
+### 4a. Dockerfile — proxy args for container image build
+
+`pnpm install` inside `docker build` fails with `SELF_SIGNED_CERT_IN_CHAIN` because the sandbox's MITM proxy presents its own certificate. Add proxy build args to `container/Dockerfile`:
+
+Add these lines after the `FROM` line:
+
+```dockerfile
+# Accept proxy build args
+ARG http_proxy
+ARG https_proxy
+ARG no_proxy
+ARG NODE_EXTRA_CA_CERTS
+ARG npm_config_strict_ssl=true
+RUN npm config set strict-ssl ${npm_config_strict_ssl}
+```
+
+And after the `RUN pnpm install` line:
+
+```dockerfile
+RUN npm config set strict-ssl true
+```
+
+### 4b. Build script — forward proxy args
+
+Patch `container/build.sh` to pass proxy env vars to `docker build`:
+
+Add these `--build-arg` flags to the `docker build` command:
+
+```bash
+--build-arg http_proxy="${http_proxy:-$HTTP_PROXY}" \
+--build-arg https_proxy="${https_proxy:-$HTTPS_PROXY}" \
+--build-arg no_proxy="${no_proxy:-$NO_PROXY}" \
+--build-arg npm_config_strict_ssl=false \
+```
+
+### 4c. Container runner — proxy forwarding, CA cert mount, /dev/null fix
+
+Three changes to `src/container-runner.ts`:
+
+**Replace `/dev/null` shadow mount.** The sandbox rejects `/dev/null` bind mounts. Find where `.env` is shadow-mounted to `/dev/null` and replace it with an empty file:
+
+```typescript
+// Create an empty file to shadow .env (Docker Sandbox rejects /dev/null mounts)
+const emptyEnvPath = path.join(DATA_DIR, 'empty-env');
+if (!fs.existsSync(emptyEnvPath)) fs.writeFileSync(emptyEnvPath, '');
+// Use emptyEnvPath instead of '/dev/null' in the mount
+```
+
+**Forward proxy env vars** to spawned agent containers. Add `-e` flags for `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and their lowercase variants.
+
+**Mount CA certificate.** If `NODE_EXTRA_CA_CERTS` or `SSL_CERT_FILE` is set, copy the cert into the project directory and mount it into agent containers:
+
+```typescript
+const caCertSrc = process.env.NODE_EXTRA_CA_CERTS || process.env.SSL_CERT_FILE;
+if (caCertSrc) {
+  const certDir = path.join(DATA_DIR, 'ca-cert');
+  fs.mkdirSync(certDir, { recursive: true });
+  fs.copyFileSync(caCertSrc, path.join(certDir, 'proxy-ca.crt'));
+  // Mount: certDir -> /workspace/ca-cert (read-only)
+  // Set NODE_EXTRA_CA_CERTS=/workspace/ca-cert/proxy-ca.crt in the container
+}
+```
+
+### 4d. Container runtime — prevent self-termination
+
+In `src/container-runtime.ts`, the `cleanupOrphans()` function matches containers by the `paraclaw-install=<slug>` label. Inside a sandbox, the sandbox container itself may match. Filter out the current hostname:
+
+```typescript
+// In cleanupOrphans(), filter out os.hostname() from the list of containers to stop
+```
+
+### 4e. Credential proxy — route through MITM proxy
+
+In `src/credential-proxy.ts`, upstream API requests need to go through the sandbox proxy. Add `HttpsProxyAgent` to outbound requests:
+
+```typescript
+import { HttpsProxyAgent } from 'https-proxy-agent';
+
+const proxyUrl = process.env.HTTPS_PROXY || process.env.https_proxy;
+const upstreamAgent = proxyUrl ? new HttpsProxyAgent(proxyUrl) : undefined;
+// Pass upstreamAgent to https.request() options
+```
+
+### 4f. Setup script — proxy build args
+
+Patch `setup/container.ts` to pass the same proxy `--build-arg` flags as `build.sh` (Step 4b).
+
+## Step 5: Build
+
+```bash
+pnpm run build
+bash container/build.sh
+```
+
+## Step 6: Add a Channel
+
+### Telegram
+
+```bash
+# Apply the Telegram skill
+pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-telegram
+
+# Rebuild after applying the skill
+pnpm run build
+
+# Configure .env
+cat > .env << EOF
+TELEGRAM_BOT_TOKEN=<your-token-from-botfather>
+ASSISTANT_NAME=paraclaw
+ANTHROPIC_API_KEY=proxy-managed
+EOF
+mkdir -p data/env && cp .env data/env/env
+
+# Register your chat
+pnpm exec tsx setup/index.ts --step register \
+  --jid "tg:<your-chat-id>" \
+  --name "My Chat" \
+  --trigger "@paraclaw" \
+  --folder "telegram_main" \
+  --channel telegram \
+  --assistant-name "paraclaw" \
+  --is-main \
+  --no-trigger-required
+```
+
+**To find your chat ID:** Send any message to your bot, then:
+```bash
+curl -s --proxy $HTTPS_PROXY "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -m json.tool
+```
+
+**Telegram in groups:** Disable Group Privacy in @BotFather (`/mybots` > Bot Settings > Group Privacy > Turn off), then remove and re-add the bot.
+
+**Important:** If the Telegram skill creates `src/channels/telegram.ts`, you'll need to patch it for proxy support. Add an `HttpsProxyAgent` and pass it to grammy's `Bot` constructor via `baseFetchConfig.agent`. Then rebuild.
+
+### WhatsApp
+
+Make sure you configured proxy bypass in [Step 1](#step-1-create-the-sandbox) first.
+
+```bash
+# Apply the WhatsApp skill
+pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-whatsapp
+
+# Rebuild
+pnpm run build
+
+# Configure .env
+cat > .env << EOF
+ASSISTANT_NAME=paraclaw
+ANTHROPIC_API_KEY=proxy-managed
+EOF
+mkdir -p data/env && cp .env data/env/env
+
+# Authenticate (choose one):
+
+# QR code — scan with WhatsApp camera:
+pnpm exec tsx src/whatsapp-auth.ts
+
+# OR pairing code — enter code in WhatsApp > Linked Devices > Link with phone number:
+pnpm exec tsx src/whatsapp-auth.ts --pairing-code --phone <phone-number-no-plus>
+
+# Register your chat (JID = your phone number + @s.whatsapp.net)
+pnpm exec tsx setup/index.ts --step register \
+  --jid "<phone>@s.whatsapp.net" \
+  --name "My Chat" \
+  --trigger "@paraclaw" \
+  --folder "whatsapp_main" \
+  --channel whatsapp \
+  --assistant-name "paraclaw" \
+  --is-main \
+  --no-trigger-required
+```
+
+**Important:** The WhatsApp skill files (`src/channels/whatsapp.ts` and `src/whatsapp-auth.ts`) also need proxy patches — add `HttpsProxyAgent` for WebSocket connections and a proxy-aware version fetch. Then rebuild.
+
+### Both Channels
+
+Apply both skills, patch both for proxy support, combine the `.env` variables, and register each chat separately.
+
+## Step 7: Run
+
+```bash
+pnpm start
+```
+
+You don't need to set `ANTHROPIC_API_KEY` manually. The sandbox proxy intercepts requests and replaces `proxy-managed` with your real key automatically.
+
+## Networking Details
+
+### How the proxy works
+
+All traffic from the sandbox routes through the host proxy at `host.docker.internal:3128`:
+
+```
+Agent container → DinD bridge → Sandbox VM → host.docker.internal:3128 → Host proxy → api.anthropic.com
+```
+
+**"Bypass" does not mean traffic skips the proxy.** It means the proxy passes traffic through without MITM inspection. Node.js doesn't automatically use `HTTP_PROXY` env vars — you need explicit `HttpsProxyAgent` configuration in every HTTP/WebSocket client.
+
+### Shared paths for DinD mounts
+
+Only the workspace directory is available for Docker-in-Docker bind mounts. Paths outside the workspace fail with "path not shared":
+- `/dev/null` → replace with an empty file in the project dir
+- `/usr/local/share/ca-certificates/` → copy cert to project dir
+- `/home/agent/` → clone to workspace instead
+
+### Git clone and virtiofs
+
+The workspace is mounted via virtiofs. Git's pack file handling can corrupt over virtiofs during clone. Workaround: clone to `/home/agent` first, then `mv` into the workspace.
+
+## Troubleshooting
+
+### pnpm install fails with SELF_SIGNED_CERT_IN_CHAIN
+```bash
+npm config set strict-ssl false
+```
+
+### Container build fails with proxy errors
+```bash
+docker build \
+  --build-arg http_proxy=$http_proxy \
+  --build-arg https_proxy=$https_proxy \
+  -t paraclaw-agent:latest container/
+```
+
+### Agent containers fail with "path not shared"
+All bind-mounted paths must be under the workspace directory. Check:
+- Is Paraclaw cloned into the workspace? (not `/home/agent/`)
+- Is the CA cert copied to the project root?
+- Has the empty `.env` shadow file been created?
+
+### Agent containers can't reach Anthropic API
+Verify proxy env vars are forwarded to agent containers. Check container logs for `HTTP_PROXY=http://host.docker.internal:3128`.
+
+### WhatsApp error 405
+The version fetch is returning a stale version. Make sure the proxy-aware `fetchWaVersionViaProxy` patch is applied — it fetches `sw.js` through `HttpsProxyAgent` and parses `client_revision`.
+
+### WhatsApp "Connection failed" immediately
+Proxy bypass not configured. From the **host**, run:
+```bash
+docker sandbox network proxy <sandbox-name> \
+  --bypass-host web.whatsapp.com \
+  --bypass-host "*.whatsapp.com" \
+  --bypass-host "*.whatsapp.net"
+```
+
+### Telegram bot doesn't receive messages
+1. Check the grammy proxy patch is applied (look for `HttpsProxyAgent` in `src/channels/telegram.ts`)
+2. Check Group Privacy is disabled in @BotFather if using in groups
+
+### Git clone fails with "inflate: data stream error"
+Clone to a non-workspace path first, then move:
+```bash
+cd ~ && git clone https://github.com/ParachuteComputer/paraclaw.git && mv paraclaw /path/to/workspace/paraclaw
+```
+
+### WhatsApp QR code doesn't display
+Run the auth command interactively inside the sandbox (not piped through `docker sandbox exec`):
+```bash
+docker sandbox run shell-paraclaw-workspace
+# Then inside:
+pnpm exec tsx src/whatsapp-auth.ts
+```

package/docs/isolation-model.md

@@ -0,0 +1,88 @@
+# Channel Isolation Model
+
+Paraclaw decouples messaging channels from agent groups. When you connect a channel (Discord, Telegram, Slack, GitHub, etc.), you decide how it relates to your existing agents. There are three isolation levels.
+
+## The Three Levels
+
+### 1. Shared Session
+
+Multiple channels feed into the same conversation. The agent sees all messages from all channels in one thread.
+
+**What's shared:** Everything — workspace, memory, CLAUDE.md, and the conversation itself. A GitHub PR comment and a Slack message appear side by side in the agent's context.
+
+**Example:** A Slack channel paired with GitHub webhooks. The agent receives PR review requests via GitHub and discusses them in Slack — all in one session. When someone comments on a PR, the agent can reference the earlier Slack discussion about that feature.
+
+**When to use:** When one channel feeds context into another. Webhook/notification channels (GitHub, Linear) paired with a chat channel (Slack, Discord) are the classic case.
+
+**Technical:** Both messaging groups are wired to the same agent group with `session_mode: 'agent-shared'`. Session resolution looks up by agent group ID only, ignoring the messaging group — so all channels converge on one session.
+
+---
+
+### 2. Same Agent, Separate Sessions
+
+Multiple channels share the same agent (same workspace, memory, personality) but have independent conversations.
+
+**What's shared:** Workspace, memory, CLAUDE.md, and all persistent state. If you tell the agent something in one session, it can save that to memory and recall it in another. The agent's personality, knowledge, and tools are identical across sessions.
+
+**What's separate:** The conversation thread. Messages from one channel don't appear in the other channel's session. Each channel has its own context window and conversation history.
+
+**Example:** You have three Telegram chats with your agent — one for a side project, one for personal tasks, one for work. All three share the same agent workspace. If you ask it to remember your API key naming convention in the project chat, it may recall that convention in the work chat too. But the conversations themselves are independent.
+
+**When to use:** When you're the primary (or sole) participant across channels and you want a unified agent identity. This is the most common setup for personal use across multiple platforms or multiple groups within one platform.
+
+**Technical:** Multiple messaging groups are wired to the same agent group with `session_mode: 'shared'` (or `'per-thread'`). Each messaging group gets its own session, but they all run in the same agent group folder.
+
+---
+
+### 3. Separate Agent Groups
+
+Each channel gets its own agent with its own workspace, memory, and personality. Nothing is shared.
+
+**What's shared:** Nothing. The agents don't know about each other. Different CLAUDE.md, different memory, different workspace, different conversation history.
+
+**Example:** You have a Telegram group with a friend and a Discord server for a team project. The friend shouldn't know what you discuss with your team, and vice versa. Each gets its own agent with its own memory and personality.
+
+**When to use:** When different people are involved, or when the information in one channel should never leak to another. This is the right choice whenever there's a privacy or confidentiality boundary between channels.
+
+**Technical:** Each channel is wired to a different agent group, each with its own folder under `groups/`. Separate containers, separate session databases, separate everything.
+
+---
+
+## How to Decide
+
+The key question: **Are you okay with any and every piece of information from one channel being available in the other?**
+
+- **No** → Separate agent groups (level 3)
+- **Yes, and the channels should see each other's messages** → Shared session (level 1)
+- **Yes, but the conversations should be independent** → Same agent, separate sessions (level 2)
+
+### Rules of Thumb
+
+| Scenario | Recommended Level |
+|----------|------------------|
+| Just you, multiple platforms (Telegram + Discord + Slack) | Same agent, separate sessions |
+| Just you, multiple groups on one platform (3 Telegram chats) | Same agent, separate sessions |
+| Webhook channel + chat channel (GitHub + Slack) | Shared session |
+| Channel with friend A and channel with friend B | Separate agent groups |
+| Personal channel and work channel | Separate agent groups |
+| Team channel with different access levels | Separate agent groups |
+
+### When in Doubt
+
+If the participants are the same across channels → same agent group is usually fine.
+
+If different people are involved → separate agent groups. Information will cross-pollinate through agent memory if you don't.
+
+## Entity Model
+
+```
+agent_groups (workspace, memory, CLAUDE.md, personality)
+    ↕ many-to-many
+messaging_groups (a specific channel/chat/group on a platform)
+    via
+messaging_group_agents (session_mode, trigger_rules, priority)
+```
+
+- **Shared session:** multiple messaging_groups → same agent_group, `session_mode = 'agent-shared'`
+- **Same agent, separate sessions:** multiple messaging_groups → same agent_group, `session_mode = 'shared'`
+- **Separate agents:** each messaging_group → different agent_group

package/docs/ollama.md

@@ -0,0 +1,79 @@
+# Running Agents on Local Ollama
+
+Paraclaw agents can be routed to a local [Ollama](https://ollama.com) instance instead of the Anthropic API. This cuts API costs to zero and keeps all inference on your hardware.
+
+## How It Works
+
+Ollama exposes an Anthropic-compatible `/v1/messages` endpoint. The Claude Code CLI (which runs inside agent containers) uses the Anthropic SDK, which reads `ANTHROPIC_BASE_URL` to find the API host. Pointing that variable at Ollama is all that's needed — no new provider code, no changes to the agent runtime.
+
+```
+┌─────────────────────────────┐
+│  Agent container            │
+│                             │
+│  Claude Code CLI            │
+│    ↓ ANTHROPIC_BASE_URL     │
+│    http://host.docker.      │      ┌──────────────────┐
+│    internal:11434    ───────┼─────▶│  Ollama :11434   │
+│                             │      │  gemma4:latest   │
+└─────────────────────────────┘      └──────────────────┘
+```
+
+`host.docker.internal` is Docker's magic hostname that resolves to the host machine from inside a container — so Ollama running on your Mac or Linux box is reachable at that address.
+
+## Network Isolation
+
+Setting `ANTHROPIC_BASE_URL` redirects requests but doesn't prevent a misconfigured agent from accidentally reaching `api.anthropic.com` directly. The `blockedHosts` field in `container.json` adds a Docker `--add-host` flag that resolves the domain to `0.0.0.0`, making it physically unreachable from inside the container:
+
+```json
+"blockedHosts": ["api.anthropic.com"]
+```
+
+With this in place, even if the model setting drifts back to a Claude model name, the API call will fail immediately rather than silently billing your account.
+
+## Model Selection
+
+The Claude Code CLI reads its model from `~/.claude/settings.json` inside the container, which paraclaw bind-mounts from `data/sessions/<agent-group-id>/.claude-shared/settings.json`. Set `"model": "gemma4:latest"` (or whatever Ollama model you've pulled) there. Use the exact name from `ollama list`.
+
+Model selection considerations for Apple Silicon:
+
+| Model | Size | Quality | Speed (M4 Pro) |
+|-------|------|---------|----------------|
+| `gemma4:latest` | 12B | Good general-purpose | Fast |
+| `qwen3-coder:latest` | 32B | Excellent for coding tasks | Moderate |
+| `llama3.2:latest` | 3B | Basic | Very fast |
+
+The agent uses tool calls extensively (read/write files, shell commands). Models that support tool use reliably work best. Gemma 4 and Qwen 3 Coder both handle structured tool calls well.
+
+## What Changes at the Code Level
+
+Three files need to support this feature. See `/add-ollama-provider` for the exact changes.
+
+**`src/container-config.ts`** — `ContainerConfig` interface needs `env` and `blockedHosts` fields so the per-group JSON can carry them.
+
+**`src/container-runner.ts`** — At container spawn time, `env` entries become `-e KEY=VAL` Docker flags (applied after paraclaw's injected secret env vars so the per-group config wins), and `blockedHosts` entries become `--add-host HOST:0.0.0.0` flags.
+
+**`container/Dockerfile`** — The container runs as the host user's uid (e.g. 501 on macOS), not as the `node` user (uid 1000). The home directory must be `chmod 777` so any uid can write `~/.claude.json` and `~/.claude/settings.json`.
+
+## Tradeoffs
+
+| | Ollama (local) | Anthropic API |
+|---|---|---|
+| Cost | Free | Pay-per-token |
+| Privacy | Fully local | Data sent to Anthropic |
+| Model quality | Good (open-weight) | Excellent (Claude) |
+| Cold start | 5–30s (model load) | ~1s |
+| Context window | Varies by model | 200k tokens (Sonnet) |
+| Tool use reliability | Good (large models) | Excellent |
+| Hardware req. | 16GB+ RAM | None |
+
+For personal automation on capable hardware, the tradeoff favors local. For complex multi-step tasks requiring large context or high reliability, Claude is still ahead.
+
+## Reverting to Claude
+
+Remove the `env` and `blockedHosts` keys from `groups/<folder>/container.json`, remove `"model"` from the shared settings file, and restart the service. No rebuild needed.
+
+## See Also
+
+- `/add-ollama-provider` — step-by-step skill to configure any agent group for Ollama
+- [Ollama Anthropic compatibility docs](https://ollama.com/blog/openai-compatibility) — upstream docs on the API bridge
+- `docs/architecture.md` — how the container spawn and env injection pipeline works

package/docs/parachute-integration.md

@@ -0,0 +1,109 @@
+# Parachute integration
+
+parachute-agent is a Parachute module: it ships with a `.parachute/module.json` manifest, registers in the hub's services catalog at install, and accepts hub-issued JWTs on every `/api/*` route. This doc covers what gets wired up when you `parachute install parachute-agent`, plus how vault attachments work inside an agent group.
+
+## Module shape
+
+`.parachute/module.json` declares the slot:
+
+```json
+{
+  "name": "agent",
+  "manifestName": "parachute-agent",
+  "displayName": "Parachute Agent",
+  "kind": "frontend",
+  "port": 1944,
+  "paths": ["/agent"],
+  "health": "/api/health",
+  "startCmd": ["bun", "src/index.ts"],
+  "scopes": { "defines": ["agent:read", "agent:write", "agent:admin"] }
+}
+```
+
+The hub uses this to:
+- Reserve port 1944 on the operator's tailnet.
+- Mount the SPA at `/agent/`.
+- Add `agent:read|write|admin` to its OAuth scope catalog.
+- Record parachute-agent in `~/.parachute/services.json` so peer modules can discover it.
+
+parachute-agent also publishes its own capability card at `/.well-known/parachute.json` (sourced from the manifest) for runtime discovery without hardcoding.
+
+## Auth
+
+Every `/api/*` route requires a hub-issued JWT — operator token (CLI/scripts) or user OAuth (browser). Validation is via JWKS against the hub origin (`PARACHUTE_HUB_ORIGIN`, stamped on every spawned module by the hub lifecycle). Two routes stay unauthenticated: `/api/health` (operational probe) and `/api/discovery` (returns hub origin so the SPA can bootstrap OAuth without a baked-in URL).
+
+## Vault attachments
+
+An agent group can attach to one or more Parachute vaults. Each attachment grants the in-container Claude Agent SDK a Parachute Vault MCP tool surface (query-notes, create-note, update-note, delete-note, list-tags, update-tag, delete-tag, find-path, vault-info).
+
+### Storage
+
+Attachments are filesystem-scoped, not database-scoped. Two files per group:
+
+- `groups/<folder>/container.json` — the container's MCP config. The vault attachment lands here as an entry under `mcpServers`:
+
+  ```json
+  {
+    "mcpServers": {
+      "parachute-vault": {
+        "type": "http",
+        "url": "http://127.0.0.1:1940/vault/default/mcp",
+        "headers": { "Authorization": "Bearer pvt_..." },
+        "instructions": "You have access to a Parachute Vault at ..."
+      }
+    }
+  }
+  ```
+
+- `groups/<folder>/parachute.json` — a sibling record holding metadata for the host:
+
+  ```json
+  {
+    "vault": {
+      "parachute-vault": {
+        "vaultBaseUrl": "http://127.0.0.1:1940/vault/default",
+        "scope": "vault:read",
+        "tokenLabel": "claw-research-bot",
+        "attachedAt": "2026-04-28T..."
+      }
+    }
+  }
+  ```
+
+The agent-runner reads `container.json` at spawn and passes `mcpServers` straight through to Claude Agent SDK's `query()`, which supports HTTP-transport MCPs natively.
+
+### Workflow
+
+```sh
+# Mint a scoped token via the hub's vault module.
+parachute vault tokens create --scope vault:read --label claw-research-bot
+# → pvt_...
+
+# Attach via parachute-agent's web UI (preferred) or CLI.
+pnpm run parachute attach-vault research-bot --token pvt_... --scope vault:read
+
+# Inspect.
+pnpm run parachute status               # all groups
+pnpm run parachute status research-bot  # one group
+
+# Detach (does NOT revoke).
+pnpm run parachute detach-vault research-bot
+parachute vault tokens revoke claw-research-bot
+```
+
+### What this deliberately does NOT impose
+
+- **No prescribed note layout.** The agent group has vault access; how it organizes notes is the agent's business.
+- **No conflation with parachute-agent secrets.** Outbound third-party API keys (Telegram, OpenAI, etc.) live in parachute-agent's local AES-GCM secret store and get injected as container env vars. Vault is for the user's knowledge graph; the secret store is for outbound credentials. Different concerns, different layers.
+
+### Threat model
+
+- **Token scope is the boundary.** A `vault:read` agent physically cannot create or delete vault notes. A `vault:write` agent cannot revoke other tokens. A `vault:admin` agent is fully trusted; use sparingly.
+- **Token is plaintext on disk and inside the container.** The bearer lives in `container.json` (host) and at `/workspace/agent/container.json` (container, read-only mount). Anyone with shell access on either side can read it. Same posture as any MCP credential — once inside the container they're plaintext env vars, same as any standard process environment.
+- **Revocation is per-token.** `parachute vault tokens revoke <label>` invalidates the agent's access immediately; the next request will get 401.
+
+## Lifecycle hooks
+
+`parachute install`, `parachute start`, `parachute restart`, `parachute stop` — the hub drives lifecycle via the manifest. Install runs migrations, generates the master key if absent, and registers parachute-agent in the services catalog. Start runs `bun src/index.ts`.
+
+For the full design of hub-as-issuer OAuth and the services catalog, see `parachute.computer/design/2026-04-20-hub-as-portal-oauth-and-service-catalog.md`.