Archipelago AI Quarantine Architecture

How AIUI (Claude) is sandboxed from your node's sensitive data — a defense-in-depth approach across 6 layers

0 Architecture Overview

The AI is treated as untrusted code in a hostile environment. It runs inside an iframe with sandbox restrictions, inside a Podman container with no outbound network. All data it receives passes through a Context Broker that checks user permissions and strips sensitive fields before anything reaches Claude's API.

1 Layer 1: Container Isolation (Podman)

# apps/aiui/manifest.yml
security:
  capabilities: []              # No Linux capabilities at all
  readonly_root: true           # Read-only filesystem
  no_new_privileges: true       # Cannot escalate privileges
  network_policy: isolated      # NO outbound network access

ports:
  - host: 5180
    container: 80
    bind: 127.0.0.1             # Only reachable via nginx, not externally

What this means:

• The AIUI container cannot make HTTP requests to the internet or to other containers
• It serves static files only — the actual Claude API calls happen in the browser, not the container
• Even with root access in the container, you can't escalate or modify the filesystem
• The container port (5180) is bound to 127.0.0.1, so only nginx (on the same machine) can reach it

2 Layer 2: Iframe Sandbox (Browser)

<!-- neode-ui/src/views/Chat.vue -->
<iframe
  :src="aiuiUrl"
  sandbox="allow-scripts allow-same-origin allow-forms"
  allow="microphone"
/>

The sandbox attribute restricts AIUI from:

• Navigating the parent page — cannot redirect Archy
• Opening popups/new windows — allow-popups is NOT granted
• Accessing parent DOM — cross-origin isolation is enforced
• Submitting forms to external URLs — forms are scoped to same origin
• Running plugins — no plugin execution

The only communication channel is window.postMessage(), which is intercepted by the Context Broker.

3 Layer 3: The Context Broker (postMessage Gate)

How it works

// contextBroker.ts — the critical permission check
private async handleContextRequest(id, category, query?) {
  const perms = useAIPermissionsStore()

  if (!perms.isEnabled(category)) {
    // DENIED — send empty response, no data
    this.postToIframe({
      type: 'context:response', id,
      data: null,
      permitted: false,    // ← AIUI knows it was denied
    })
    return
  }

  // ALLOWED — fetch and sanitize before sending
  const data = await this.fetchAndSanitize(category, query)
  this.postToIframe({
    type: 'context:response', id,
    data,                  // ← sanitized data only
    permitted: true,
  })
}

Origin Validation (both sides)

• Context Broker (host): Rejects any message where event.origin !== this.allowedOrigin
• archyBridge (AIUI): Rejects any message where event.origin !== allowedOrigin
• Responses use explicit target origin: iframe.contentWindow.postMessage(msg, this.allowedOrigin)

4 Layer 4: Per-Category Permission Toggles

Permissions stored in localStorage key: archipelago-ai-permissions

Store: neode-ui/src/stores/aiPermissions.ts

5 Layer 5: Data Sanitization

Example: Bitcoin sanitization

// contextBroker.ts — sanitizeBitcoin()
// ONLY these fields are extracted and sent to AI:
return {
  available: true,
  status: 'running',
  block_height: info.block_height,
  sync_progress: info.sync_progress,
  chain: info.chain,
  difficulty: info.difficulty,
  mempool_size: info.mempool_size,
  mempool_tx_count: info.mempool_tx_count,
  verification_progress: info.verification_progress,
}
// NOT included: wallet data, addresses, keys, RPC auth, raw responses

Example: Wallet sanitization

// contextBroker.ts — sanitizeWallet()
// ONLY these safe summary fields:
return {
  available: true,
  status: 'running',
  alias: info.alias,
  num_active_channels: info.num_active_channels,
  num_peers: info.num_peers,
  synced_to_chain: info.synced_to_chain,
  block_height: info.block_height,
  balance_sats: info.balance_sats,
  channel_balance_sats: info.channel_balance_sats,
  pending_open_balance: info.pending_open_balance,
}
// NEVER included: private keys, seed phrases, macaroons,
//                 channel points, backup data, node pubkeys

Example: Network sanitization

// contextBroker.ts — sanitizeNetwork()
// Only booleans — no addresses:
return {
  connected: store.isConnected,        // true/false
  torConnected: hasTor,                // true/false
  tailscaleActive: tailscale?.state === 'running',  // true/false
}
// NEVER: IP addresses, .onion addresses, peer info, MAC addresses

6 Layer 6: Proxy & Nginx Authentication

# nginx-archipelago.conf
location /aiui/api/claude/ {
    if ($cookie_session = "") {
        return 401 '{"error":"Unauthorized"}';  # No session = blocked
    }
    proxy_pass http://127.0.0.1:3141/;  # → Claude Proxy
}

The Claude Proxy (port 3141):

• OAuth token stored securely (macOS keychain → .env.local)
• Auto-refreshes tokens 5 minutes before expiry
• Never exposes the token to the browser — the proxy adds auth headers server-side
• Only the browser's fetch to /aiui/api/claude/ goes through this proxy

Content Security Policy (CSP):

Content-Security-Policy: default-src 'self';
  connect-src 'self' ws: wss:;
  frame-src 'self' http://127.0.0.1:* http://localhost:*;

The CSP restricts the AIUI iframe to only connect to the same origin and local addresses. No external fetch calls are possible.

7 The postMessage Protocol

AIUI and Archy communicate via a strictly-typed protocol defined in neode-ui/src/types/aiui-protocol.ts.

AIUI → Archy (Requests)

Archy → AIUI (Responses)

8 What the AI System Prompt Sees

The buildArchyContext() function in AIUI constructs a context string that gets appended to Claude's system prompt. It only includes data for permitted categories:

// Example output when apps + bitcoin + wallet are enabled:

**Archy Node Context** (this user is running AIUI on their Archipelago node):
**Installed apps on this node:**
- Bitcoin Knots (installed, running)
- LND (installed, running)
- Mempool (installed, running)
- File Browser (installed, running)
**Bitcoin:** Block 890,123, 99.99% synced, mainnet, mempool: 42,815 txs
**Lightning (LND):** MyNode | 5 channels | 3 peers | On-chain: 150,000 sats

You can help the user manage their node. Available actions: open an app
(open-app), install an app (install-app), navigate in Archy (navigate).

9 What the AI Can NEVER See

10 Permitted Actions

The AI can request a limited set of actions through the Context Broker. Each action is validated and requires the relevant permission category to be enabled.

11 Current Bugs & Issues

12 Source File Reference

Archipelago AI Quarantine Architecture — Generated 2026-03-06 — v1.0.0