limbo-ai 1.26.0 → 1.28.0

package/ARCHITECTURE.md

@@ -0,0 +1,178 @@
+# Limbo — Architecture Reference
+
+> This file is loaded by AI assistants to avoid re-scanning the codebase every session.
+> Keep it updated when structure changes. Last verified: 2026-03-29.
+
+## What Is Limbo
+
+Self-hosted personal AI memory agent. Runs as a Docker container exposing a ZeroClaw gateway (WebSocket on :18789). Users interact via Telegram. The agent stores and retrieves knowledge from a markdown vault using MCP tools.
+
+**Stack**: ZeroClaw (Rust agent runtime, custom fork) + Node.js MCP server + SQLite FTS5 + Telegram bot.
+
+**Published as**: `limbo-ai` on npm — the CLI (`npx limbo-ai`) handles install, start, stop, update, and setup.
+
+## High-Level Flow
+
+```
+User (Telegram) → ZeroClaw Gateway (:18789) → LLM (configurable provider)
+                                                    ↓
+                                              MCP Tools (stdio)
+                                                    ↓
+                                         Vault (markdown + SQLite FTS5)
+```
+
+## Directory Structure
+
+```
+limbo/
+├── cli.js                    # Main CLI (84KB) — install, start, stop, update, configure
+├── Dockerfile                # Multi-stage: deps → zeroclaw binary → runtime (node:22-slim)
+├── config.toml.template      # ZeroClaw config — rendered by entrypoint via envsubst
+├── docker-compose.yml        # Production reference (generated per-user into ~/.limbo)
+├── docker-compose.dev.yml    # Local dev
+├── docker-compose.test.yml   # Local testing
+├── package.json              # npm package: limbo-ai v1.20.4
+│
+├── mcp-server/               # Node.js MCP server (JSON-RPC 2.0 over stdio)
+│   ├── index.js              # Entry point — tool routing, vault init, FTS setup
+│   ├── vault-index.js        # In-memory vault index (walks markdown files + YAML frontmatter)
+│   ├── fts.js                # SQLite FTS5 — BM25 scoring, title-weighted, WAL mode
+│   └── tools/                # One file per MCP tool
+│       ├── search.js         # vault_search — FTS5 full-text search
+│       ├── read.js           # vault_read — O(1) lookup via in-memory index
+│       ├── write.js          # vault_write_note — create/update with YAML frontmatter
+│       ├── update-map.js     # vault_update_map — append entries to MOCs
+│       ├── store-file.js     # vault_store_file — binary files (images/PDFs) + linked note
+│       └── get-file.js       # vault_get_file — retrieve stored files as base64
+│
+├── workspace/                # Agent persona files (injected into ZeroClaw context)
+│   ├── system/               # Product-owned, root-owned, reset every boot
+│   │   ├── AGENTS.md         # Behavioral workflows and rules
+│   │   ├── TOOLS.md          # Tool usage instructions
+│   │   └── limbo-skill.md    # Agent skill definitions
+│   └── templates/            # User-owned, seeded on first run only
+│       ├── IDENTITY.md
+│       ├── SOUL.md
+│       └── USER.md.template  # Rendered with envsubst on first run
+│
+├── setup-server/             # Zero-dependency HTTP setup wizard (pure Node.js)
+│   └── server.js             # Serves on :18789 until config complete, then exits
+│
+├── migrations/               # Data migration runner
+│   ├── index.js              # Runner — executes versioned migrations sequentially
+│   └── versions/             # Individual migration files (4 versions)
+│
+├── scripts/
+│   ├── entrypoint.sh         # Container startup (13KB) — 12-stage orchestration
+│   ├── build-zeroclaw.sh     # Custom ZeroClaw image builder (multi-platform)
+│   └── install.sh            # Server provisioning (Ubuntu/Debian)
+│
+├── evals/                    # End-to-end eval framework
+│   ├── cli.js                # Eval runner (28KB) — run, compare, promote, judge
+│   ├── docker-compose.eval.yml
+│   ├── cases/                # 20+ JSON test cases (search, create, multi-step, speed)
+│   ├── vault-seed/           # Pre-populated vault for deterministic eval runs
+│   ├── judge/                # LLM-as-judge rubrics
+│   ├── lib/                  # Shared eval utilities
+│   ├── dashboard/            # Web UI for results
+│   ├── results/              # Run outputs + baselines/
+│   └── scripts/              # Eval helper scripts
+│
+├── test/                     # Unit tests (node --test)
+│   ├── cli-filter.test.js
+│   ├── cli-auth.test.js
+│   ├── zeroclaw-migration.test.js
+│   ├── setup-server.test.js
+│   └── cli-wizard-parity.test.js
+│
+├── docs/                     # Public documentation
+├── agents/                   # Paperclip agent configs (not deployed in Limbo)
+└── squid/                    # Squid proxy config (for container network access)
+```
+
+## Docker Build (3 stages)
+
+1. **deps** (node:22-slim) — `npm ci` + compile better-sqlite3 native addon
+2. **zeroclaw** — copies binary from custom image `ghcr.io/tomasward1/zeroclaw:<ver>-custom`
+3. **runtime** (node:22-slim) — non-root `limbo` user, copies app + binary + node_modules
+
+**Data volume**: `/data` — contains vault/, db/, config/, logs/, backups/, memory/
+
+**Build arg**: `ZEROCLAW_IMAGE` — override to test custom ZeroClaw builds locally.
+
+## Entrypoint Flow (scripts/entrypoint.sh)
+
+12-stage startup:
+1. Directory setup (`/data/*`)
+2. Secrets sync (`/run/secrets/` → `$ZEROCLAW_STATE_DIR/secrets/`)
+3. First-run detection (presence of `.env` in /data)
+4. Setup wizard (if no `MODEL_PROVIDER` in .env → serve wizard on :18789)
+5. Workspace file seeding (templates → /data, system files symlinked)
+6. Config template rendering (envsubst on config.toml.template)
+7. Feature sections (Telegram, Voice, Web Search) conditionally appended to config.toml
+8. Auth profiles generation
+9. Migration runner
+10. FTS index build
+11. MCP server registration
+12. ZeroClaw launch
+
+## MCP Server Details
+
+- **Protocol**: JSON-RPC 2.0 over stdio
+- **Invoked by ZeroClaw**: `node /app/mcp-server/index.js`
+- **Vault path**: `/data/vault/` (markdown files with YAML frontmatter)
+- **FTS database**: `/data/db/fts.db` (SQLite, WAL mode)
+- **Index**: In-memory hashmap of all vault notes, rebuilt on startup
+
+### Frontmatter Schema
+
+```yaml
+---
+id: unique-slug
+title: Display Name
+description: Falsifiable claim or summary
+type: note|map|reminder|file
+status: seed|growing|evergreen
+domain: personal|tech|...
+created: 2026-03-29
+source: telegram|manual|...
+topics:
+  - "[[related-note]]"
+---
+```
+
+## Key Architectural Decisions
+
+These are documented in the vault but rarely change:
+
+- **Extension = MCP tools, not ZeroClaw features**. New capabilities go in `mcp-server/tools/` as Node.js. Cargo features only for things that must compile into Rust (e.g., `rag-pdf`).
+- **Separate container, not plugin**. Limbo is a standalone Docker container, not an OpenClaw plugin.
+- **System files reset on boot, user files persist**. AGENTS.md/TOOLS.md overwrite from image; SOUL.md/IDENTITY.md/USER.md survive across container restarts.
+- **Maps live in vault/maps/, notes in vault/notes/**. Separated to simplify `vault_update_map`.
+- **Feature integration pattern**: wizard toggle → secret file → env var → entrypoint appends TOML section.
+- **Minimal .env triggers setup wizard**. Container detects first run by absence of `MODEL_PROVIDER`.
+
+## Eval System
+
+- 20+ JSON test cases in `evals/cases/`
+- Each case: sends message via WebSocket, asserts on tool_called + response_matches + vault_state
+- Current baseline: 94.0% (FTS5 + ZeroClaw v0.6.3)
+- `node evals/cli.js run` → `compare --strict` → `promote`
+- Uses real LLM calls (costs tokens)
+
+## Environment Variables
+
+Key env vars (see `.env.example` for full list):
+- `MODEL_PROVIDER` — anthropic, openai, etc.
+- `TELEGRAM_ENABLED` — true/false
+- `LIMBO_PORT` — gateway port (default 18789)
+- `ZEROCLAW_STATE_DIR` — where ZeroClaw stores its state
+- `LIMBO_EVAL` — enables MCP tool call logging
+
+## Testing
+
+```bash
+npm test    # runs: cli-filter, cli-auth, zeroclaw-migration, setup-server, cli-wizard-parity
+```
+
+Tests use Node.js built-in test runner (`node --test`).

package/README.md

@@ -1,14 +1,21 @@
-# Limbo
+<p align="center">
+  <img src="assets/og-banner.png" alt="Limbo — Tu segundo cerebro" width="720" />
+</p>
 
-[![npm](https://img.shields.io/npm/v/limbo-ai?color=blue&label=release)](https://www.npmjs.com/package/limbo-ai)
-[![build](https://img.shields.io/github/actions/workflow/status/TomasWard1/limbo/ci.yml?branch=staging&label=build)](https://github.com/TomasWard1/limbo/actions)
-[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS-lightgrey)](.)
-[![docker](https://img.shields.io/badge/docker-%E2%9C%93-blue)](https://github.com/TomasWard1/limbo/pkgs/container/limbo)
+<p align="center">
+  <a href="https://www.npmjs.com/package/limbo-ai"><img src="https://img.shields.io/npm/v/limbo-ai?color=blue&label=release" alt="npm" /></a>
+  <a href="https://github.com/TomasWard1/limbo/actions"><img src="https://img.shields.io/github/actions/workflow/status/TomasWard1/limbo/ci.yml?branch=staging&label=build" alt="build" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
+  <a href="."><img src="https://img.shields.io/badge/platform-linux%20%7C%20macOS-lightgrey" alt="platform" /></a>
+  <a href="https://github.com/TomasWard1/limbo/pkgs/container/limbo"><img src="https://img.shields.io/badge/docker-%E2%9C%93-blue" alt="docker" /></a>
+  <a href="https://github.com/TomasWard1/limbo"><img src="https://img.shields.io/github/stars/TomasWard1/limbo?style=social" alt="stars" /></a>
+</p>
 
-A personal memory agent. Captures ideas, remembers things, and connects knowledge across time — running in a Docker container, accessible via Telegram or the ZeroClaw gateway.
+<p align="center">A personal memory agent that captures ideas, remembers things, and connects knowledge across time.</p>
 
-Limbo is a second brain with a conversational interface. It stores atomic notes in a local vault, searches them semantically, and maintains Maps of Content (MOCs) to keep knowledge navigable.
+---
+
+Limbo is a second brain with a conversational interface. It stores atomic notes in a local vault, searches them semantically, and maintains Maps of Content (MOCs) to keep knowledge navigable. Runs in a Docker container, accessible via Telegram or the ZeroClaw gateway.
 
 ---
 
@@ -208,6 +215,7 @@ Managed by `limbo start`, stored in `~/.limbo/.env`.
 | `AUTH_MODE` | `api-key` | `api-key` or `subscription` |
 | `MODEL_PROVIDER` | `anthropic` | `anthropic`, `openai`, `openai-codex`, or `openrouter` |
 | `MODEL_NAME` | `claude-sonnet-4-6` | Model to use |
+| `RUNTIME_REASONING_EFFORT` | `medium` | ZeroClaw `runtime.reasoning_effort` override |
 | `TELEGRAM_ENABLED` | `false` | Enable Telegram integration |
 | `VOICE_ENABLED` | `false` | Enable Groq voice transcription |
 | `WEB_SEARCH_ENABLED` | `false` | Enable Brave web search |

package/cli.js

@@ -15,6 +15,7 @@ const readline = require('readline');
 
 const LIMBO_DIR = path.join(os.homedir(), '.limbo');
 const VAULT_DIR = path.join(LIMBO_DIR, 'vault');
+const ZEROCLAW_STATE_DIR = path.join(LIMBO_DIR, 'zeroclaw-state');
 const SECRETS_DIR = path.join(LIMBO_DIR, 'secrets');
 const ENV_FILE = path.join(LIMBO_DIR, '.env');
 const COMPOSE_FILE = path.join(LIMBO_DIR, 'docker-compose.yml');
@@ -158,7 +159,7 @@ function composeContent() {
     volumes:
       - limbo-data:/data
       - ${VAULT_DIR}:/data/vault
-      - limbo-zeroclaw-state:/home/limbo/.zeroclaw
+      - ${ZEROCLAW_STATE_DIR}:/home/limbo/.zeroclaw
     secrets:
       - llm_api_key
       - telegram_bot_token
@@ -193,7 +194,6 @@ secrets:
 
 volumes:
   limbo-data:
-  limbo-zeroclaw-state:
 `;
 }
 
@@ -220,7 +220,7 @@ function composeContentHardened() {
     volumes:
       - limbo-data:/data
       - ${VAULT_DIR}:/data/vault
-      - limbo-zeroclaw-state:/home/limbo/.zeroclaw
+      - ${ZEROCLAW_STATE_DIR}:/home/limbo/.zeroclaw
     secrets:
       - llm_api_key
       - telegram_bot_token
@@ -286,7 +286,6 @@ secrets:
 
 volumes:
   limbo-data:
-  limbo-zeroclaw-state:
 `;
 }
 
@@ -1022,10 +1021,51 @@ async function collectConfig(existingEnv = {}) {
   };
 }
 
+// Migrate zeroclaw state from old named volume (limbo_limbo-zeroclaw-state or
+// limbo-zeroclaw-state) to the new bind-mount directory at ZEROCLAW_STATE_DIR.
+// Only runs if the bind-mount dir is empty and the named volume exists.
+function migrateZeroclawStateVolume() {
+  // Skip if bind-mount dir already has content
+  try {
+    const entries = fs.readdirSync(ZEROCLAW_STATE_DIR);
+    if (entries.length > 0) return;
+  } catch { return; }
+
+  // Check whether the old named volume exists (Docker may prefix with project name)
+  const candidateVolumes = ['limbo_limbo-zeroclaw-state', 'limbo-zeroclaw-state'];
+  let foundVolume = null;
+  try {
+    const result = spawnSync('docker', ['volume', 'ls', '--format', '{{.Name}}'], { encoding: 'utf8', stdio: 'pipe' });
+    if (result.status === 0) {
+      const existing = result.stdout.split('\n').map(s => s.trim());
+      foundVolume = candidateVolumes.find(v => existing.includes(v)) || null;
+    }
+  } catch { /* docker not available yet */ }
+
+  if (!foundVolume) return;
+
+  log(`Migrating ZeroClaw state from volume "${foundVolume}" to ${ZEROCLAW_STATE_DIR} ...`);
+  const migrate = spawnSync('docker', [
+    'run', '--rm',
+    '-v', `${foundVolume}:/src:ro`,
+    '-v', `${ZEROCLAW_STATE_DIR}:/dst`,
+    'alpine',
+    'sh', '-c', 'cp -a /src/. /dst/',
+  ], { stdio: 'pipe' });
+
+  if (migrate.status === 0) {
+    log('Migration complete. Old volume data is preserved and can be removed with: docker volume rm ' + foundVolume);
+  } else {
+    warn('Migration from old volume failed — continuing with empty state. Run `limbo start` again after verifying Docker is available.');
+  }
+}
+
 function ensureComposeFile(hardened = false) {
   fs.mkdirSync(LIMBO_DIR, { recursive: true });
   fs.mkdirSync(path.join(VAULT_DIR, 'notes'), { recursive: true });
   fs.mkdirSync(path.join(VAULT_DIR, 'maps'), { recursive: true });
+  fs.mkdirSync(ZEROCLAW_STATE_DIR, { recursive: true });
+  migrateZeroclawStateVolume();
   fs.mkdirSync(SECRETS_DIR, { recursive: true, mode: 0o700 });
   // Ensure secret files exist (Docker Compose secrets require the files to be present)
   for (const name of ['llm_api_key', 'telegram_bot_token', 'gateway_token', 'groq_api_key', 'brave_api_key']) {
@@ -1097,24 +1137,191 @@ function ensureVolumePermissions() {
   ], { stdio: 'pipe' });
 }
 
-// ─── Server detection & Cloudflare tunnel for remote wizard access ──────────
+// ─── Server detection & tunnel for remote wizard access ─────────────────────
 
 function isServerEnvironment() {
   return !!(process.env.SSH_CONNECTION || process.env.SSH_CLIENT ||
     (os.platform() === 'linux' && !process.env.DISPLAY));
 }
 
-// Creates a public HTTPS tunnel via localhost.run (SSH-based, zero install).
-// Falls back gracefully if SSH is unavailable or the service is down.
-async function createSetupTunnel(port) {
+const CF_CERT_PATH = path.join(os.homedir(), '.cloudflared', 'cert.pem');
+const CF_TUNNEL_CONFIG = path.join(LIMBO_DIR, 'tunnel-config.json');
+
+function hasCloudflared() {
+  try { execSync('cloudflared --version', { stdio: 'pipe' }); return true; } // hardcoded, safe
+  catch { return false; }
+}
+
+function isCloudflareLoggedIn() {
+  return fs.existsSync(CF_CERT_PATH);
+}
+
+// Interactive prompt: choose tunnel type
+async function promptTunnelChoice() {
+  const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+  console.log(`
+  ${c.bold}Setup wizard needs a public URL for your client.${c.reset}
+
+  ${c.green}1)${c.reset} Cloudflare tunnel ${c.dim}(stable URL under your domain, recommended)${c.reset}
+  ${c.green}2)${c.reset} Quick tunnel      ${c.dim}(instant, temporary URL via localhost.run)${c.reset}
+`);
+  const choice = (await ask('  Choose [1/2]: ')).trim();
+  rl.close();
+  return choice === '2' ? 'quick' : 'cloudflare';
+}
+
+// cloudflared login (interactive, opens browser or prints URL)
+async function ensureCloudflareLogin() {
+  if (isCloudflareLoggedIn()) return true;
+
+  log('Logging in to Cloudflare...');
+  log('A browser window will open (or a URL will be printed). Select your domain.\n');
+
+  const result = spawnSync('cloudflared', ['login'], { stdio: 'inherit' });
+  if (result.status !== 0 || !isCloudflareLoggedIn()) {
+    warn('Cloudflare login failed or was cancelled.');
+    return false;
+  }
+  ok('Cloudflare login successful.');
+  return true;
+}
+
+// Tunnel hostnames are always setup-<slug>.heylimbo.com
+const CF_TUNNEL_BASE_DOMAIN = 'heylimbo.com';
+
+// Create a named CF tunnel using cloudflared CLI (requires cert.pem from login)
+async function createNamedCfTunnel(port) {
+  const slug = crypto.randomBytes(4).toString('hex').slice(0, 7);
+  const tunnelName = 'limbo-setup-' + slug;
+  const hostname = 'setup-' + slug + '.' + CF_TUNNEL_BASE_DOMAIN;
+
+  try {
+    // 1. Create tunnel
+    spinnerWrite('Creating tunnel...');
+    const createResult = spawnSync('cloudflared', ['tunnel', 'create', tunnelName], {
+      stdio: 'pipe', encoding: 'utf8',
+    });
+    if (createResult.status !== 0) {
+      spinnerClear();
+      warn('Failed to create tunnel: ' + (createResult.stderr || '').trim());
+      return null;
+    }
+
+    // Extract tunnel ID from output ("Created tunnel <name> with id <uuid>")
+    const idMatch = (createResult.stdout + createResult.stderr).match(/with id ([0-9a-f-]+)/i);
+    if (!idMatch) {
+      spinnerClear();
+      warn('Could not parse tunnel ID from cloudflared output.');
+      return null;
+    }
+    const tunnelId = idMatch[1];
+
+    // 2. Route DNS
+    spinnerWrite('Configuring DNS...');
+    const dnsResult = spawnSync('cloudflared', ['tunnel', 'route', 'dns', tunnelName, hostname], {
+      stdio: 'pipe', encoding: 'utf8',
+    });
+    if (dnsResult.status !== 0) {
+      // Non-fatal: might already exist, or we can continue anyway
+      const stderr = (dnsResult.stderr || '').trim();
+      if (!stderr.includes('already exists')) {
+        warn('DNS routing warning: ' + stderr);
+      }
+    }
+
+    // 3. Write minimal config file for this tunnel
+    const cfCredPath = path.join(os.homedir(), '.cloudflared', tunnelId + '.json');
+    const tunnelConfig = path.join(LIMBO_DIR, 'tunnel-cloudflared.yml');
+    const configContent = [
+      'tunnel: ' + tunnelId,
+      'credentials-file: ' + cfCredPath,
+      'ingress:',
+      '  - hostname: ' + hostname,
+      '    service: http://localhost:' + port,
+      '  - service: http_status:404',
+      '',
+    ].join('\n');
+    fs.writeFileSync(tunnelConfig, configContent, { mode: 0o600 });
+
+    // 4. Run tunnel
+    const logFile = path.join(LIMBO_DIR, 'tunnel-setup.log');
+    const tunnelProc = spawn('cloudflared', [
+      'tunnel', '--config', tunnelConfig, 'run', tunnelName,
+    ], {
+      detached: true,
+      stdio: ['ignore', fs.openSync(logFile, 'w'), fs.openSync(logFile, 'a')],
+    });
+    tunnelProc.unref();
+
+    // Wait for connection
+    let connected = false;
+    for (let i = 0; i < 15; i++) {
+      spinnerWrite('Connecting tunnel...');
+      sleep(1000);
+      try {
+        const logs = fs.readFileSync(logFile, 'utf8');
+        if (logs.includes('Registered tunnel connection') || logs.includes('INF Registered')) {
+          connected = true;
+          break;
+        }
+      } catch {}
+    }
+    spinnerClear();
+
+    if (!connected) {
+      warn('Cloudflare tunnel did not connect in time.');
+      try { tunnelProc.kill(); } catch {}
+      spawnSync('cloudflared', ['tunnel', 'delete', '-f', tunnelName], { stdio: 'pipe' });
+      return null;
+    }
+
+    // Wait for DNS propagation (Chromium caches negative DNS lookups aggressively)
+    const https = require('https');
+    for (let i = 0; i < 15; i++) {
+      spinnerWrite('Waiting for DNS (' + (i + 1) + 's)...');
+      try {
+        await new Promise((resolve, reject) => {
+          const req = https.get('https://' + hostname + '/healthz', (res) => {
+            resolve(res.statusCode);
+          });
+          req.on('error', reject);
+          req.setTimeout(3000, () => { req.destroy(); reject(new Error('timeout')); });
+        });
+        break; // DNS resolved and tunnel responded
+      } catch {
+        sleep(1000);
+      }
+    }
+    spinnerClear();
+
+    // Save metadata for cleanup
+    const meta = { tunnelName, tunnelId, hostname, type: 'cloudflare-named' };
+    fs.writeFileSync(CF_TUNNEL_CONFIG, JSON.stringify(meta), { mode: 0o600 });
+
+    return {
+      type: 'cloudflare-named',
+      url: 'https://' + hostname,
+      pid: tunnelProc.pid,
+      logFile,
+      tunnelName,
+    };
+  } catch (err) {
+    spinnerClear();
+    warn('Cloudflare tunnel failed: ' + err.message);
+    return null;
+  }
+}
+
+// Fallback: localhost.run SSH tunnel (ephemeral, no install needed)
+async function createQuickTunnel(port) {
   try {
     const logFile = path.join(LIMBO_DIR, 'tunnel-setup.log');
-    // localhost.run provides instant HTTPS URLs via SSH reverse tunneling.
-    // No binary to install, no DNS propagation delay, no Chrome caching issues.
     const tunnelProc = spawn('ssh', [
       '-o', 'StrictHostKeyChecking=accept-new',
       '-o', 'ServerAliveInterval=30',
-      '-R', `80:localhost:${port}`,
+      '-R', '80:localhost:' + port,
       'nokey@localhost.run',
     ], {
       detached: true,
@@ -1122,7 +1329,6 @@ async function createSetupTunnel(port) {
     });
     tunnelProc.unref();
 
-    // localhost.run prints the URL almost instantly (no DNS propagation needed)
     let tunnelUrl = null;
     for (let i = 0; i < 10; i++) {
       spinnerWrite('Securing tunnel...');
@@ -1147,12 +1353,74 @@ async function createSetupTunnel(port) {
   }
 }
 
+// Interactive tunnel creation: prompts admin for choice
+async function createSetupTunnel(port) {
+  const hasCf = hasCloudflared();
+
+  // If cloudflared is available, offer the choice
+  if (hasCf) {
+    const choice = await promptTunnelChoice();
+
+    if (choice === 'cloudflare') {
+      const loggedIn = await ensureCloudflareLogin();
+      if (loggedIn) {
+        const tunnel = await createNamedCfTunnel(port);
+        if (tunnel) return tunnel;
+        warn('Falling back to quick tunnel...');
+      }
+    }
+  }
+
+  return createQuickTunnel(port);
+}
+
+// Clean up tunnel process and CF resources
 function teardownSetupTunnel(tunnel) {
   if (!tunnel) return;
   try { process.kill(tunnel.pid); } catch {}
   if (tunnel.logFile) try { fs.unlinkSync(tunnel.logFile); } catch {}
 }
 
+// Clean up leftover CF tunnels from previous runs
+function cleanupCfTunnel() {
+  try {
+    const meta = JSON.parse(fs.readFileSync(CF_TUNNEL_CONFIG, 'utf8'));
+    if (meta.tunnelName) {
+      spawnSync('cloudflared', ['tunnel', 'cleanup', meta.tunnelName], { stdio: 'pipe' });
+      spawnSync('cloudflared', ['tunnel', 'delete', '-f', meta.tunnelName], { stdio: 'pipe' });
+    }
+    fs.unlinkSync(CF_TUNNEL_CONFIG);
+    const tunnelConfig = path.join(LIMBO_DIR, 'tunnel-cloudflared.yml');
+    try { fs.unlinkSync(tunnelConfig); } catch {}
+  } catch {}
+}
+
+// Read a single env var from ~/.limbo/.env
+function loadEnvVar(name) {
+  try {
+    const content = fs.readFileSync(ENV_FILE, 'utf8');
+    const match = content.match(new RegExp('^' + name + '=(.+)$', 'm'));
+    return match ? match[1].trim() : null;
+  } catch { return null; }
+}
+
+// Append or update env vars in ~/.limbo/.env without overwriting existing ones
+function persistEnvVars(vars) {
+  try {
+    let content = '';
+    try { content = fs.readFileSync(ENV_FILE, 'utf8'); } catch {}
+    for (const [key, value] of Object.entries(vars)) {
+      const re = new RegExp('^' + key + '=.*$', 'm');
+      if (re.test(content)) {
+        content = content.replace(re, key + '=' + value);
+      } else {
+        content = content.trimEnd() + '\n' + key + '=' + value + '\n';
+      }
+    }
+    fs.writeFileSync(ENV_FILE, content, { mode: 0o600 });
+  } catch {}
+}
+
 function installGlobalAlias() {
   // Create a `limbo` shell wrapper so users don't have to type `npx limbo-ai` every time.
   // Tries /usr/local/bin first (macOS, Linux with sudo), falls back to ~/.local/bin (no sudo).
@@ -1569,6 +1837,9 @@ function writeMinimalEnv() {
 // ─── Commands ────────────────────────────────────────────────────────────────
 
 async function cmdStart() {
+  // Clean up any leftover CF tunnel from a previous setup run
+  cleanupCfTunnel();
+
   // ── Auto-install Docker if missing ────────────────────────────────────────
   if (!hasDocker()) {
     installDocker();
@@ -1613,7 +1884,7 @@ async function cmdStart() {
   const flagApiKey = parseFlag('--api-key');
   const flagModel = parseFlag('--model');
   const flagLang = parseFlag('--language') || 'en';
-  const flagTunnelDomain = parseFlag('--tunnel-domain');
+  // CF tunnel flags parsed by createSetupTunnel() via parseFlag() — no local var needed
 
   if (flagProvider) {
     const validProviders = ['openai', 'anthropic', 'openrouter'];
@@ -1705,9 +1976,9 @@ async function cmdStart() {
   // Extract wizard URL from container logs (polls briefly, no healthcheck needed)
   const wizardUrl = extractWizardUrl();
 
-  // On servers, try to create a public tunnel (non-blocking — show localhost/SSH first)
+  // Create a public tunnel (auto on servers, or with --tunnel flag)
   let tunnel = null;
-  if (isServerEnvironment()) {
+  if (isServerEnvironment() || process.argv.includes('--tunnel')) {
     tunnel = await createSetupTunnel(PORT);
   }
 
@@ -1970,7 +2241,7 @@ ${c.bold}Flags:${c.reset}
   --api-key <key>      API key for headless install
   --model <name>       Model name (optional, uses provider default)
   --language <code>    Language: en, es (default: en)
-  --tunnel-domain <d>  Admin: use branded subdomain for setup tunnel (e.g. limbo.tomasward.com)
+  --tunnel               Force tunnel creation prompt (even on local/non-server environments)
 
 ${c.bold}Config:${c.reset}
   limbo config voice --enable --api-key gsk_xxx     Enable voice transcription

package/config.toml.template

@@ -5,6 +5,9 @@
 default_provider = "${MODEL_PROVIDER}"
 default_model = "${MODEL_NAME}"
 
+[runtime]
+reasoning_effort = "${RUNTIME_REASONING_EFFORT}"
+
 [gateway]
 host = "127.0.0.1"
 port = ${LIMBO_PORT}
@@ -21,3 +24,4 @@ enabled = true
 name = "limbo-vault"
 command = "node"
 args = ["/app/mcp-server/index.js"]
+env = { ZEROCLAW_STATE_DIR = "${ZEROCLAW_STATE_DIR}", ZEROCLAW_WORKSPACE_DIR = "${ZEROCLAW_STATE_DIR}/workspace" }

package/docker-compose.test.yml

@@ -12,6 +12,11 @@ services:
     volumes:
       - limbo-test-data:/data
       - limbo-test-state:/home/limbo/.zeroclaw
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
     tmpfs:
       - /tmp:size=100M