memeri

The Tunnel — what it does for you

Status: ✅ Current · Last reviewed: 2026-06-18

The Tunnel is a small CLI that runs on your machine and gives any MCP-compatible AI client local-system access — terminal commands, file reads/writes — without installing the full Claude Code plugin. See Choosing your setup tier for when you need it.

What you get

Run one command in the project folder you want the AI to access:

~/.memeri/start-tunnel.sh

The installer writes this launcher with your gateway URL + token baked in. The folder you run it from becomes the tunnel root — the only place the AI can read or write. (Full step-by-step in Connect Your AI → Installing the Tunnel.)

From that moment on, while the tunnel is running:

Capability Without tunnel With tunnel
AI reads/writes Memeri data (jobs, updates, intelligence) ✅ ✅
AI runs terminal commands locally ❌ ✅
AI reads / writes files on your filesystem ❌ ✅
Local-tool telemetry (file edits, bash) → Project timeline ❌ ✅
Memeri-specific cognition (resume, slash commands) ❌ ❌

The last one is plugin-only (Tier 3). Everything else, the tunnel does.

How it works

The tunnel is a long-running process. It maintains a WebSocket to the Memeri gateway. When the gateway routes a tool call (e.g. terminal_execute, file_read) for your project, the gateway sends it through the tunnel to your machine, executes, and returns the result.

It also watches Claude Code's local session JSONL log — if you have Claude Code open in the same shell — and forwards those tool events to the gateway as telemetry. So you get the same Project-timeline visibility as plugin users, without installing the plugin.

Who's it for

  • Cursor / Windsurf / Codex / ChatGPT users who want their AI to actually do work on their machine, not just give them code blocks
  • Claude Code users who don't want the full plugin (e.g. corporate-policy reasons, plugin marketplace unavailable)
  • Anyone with a non-Claude AI that supports MCP and wants Memeri to feel "wired in"

If you primarily use Claude Code, you usually don't need the tunnel — its MCP + user-level telemetry already give you local-tool visibility. (The plugin will be the most integrated option once it's out of private beta; until then, Claude Code's MCP + telemetry cover it.)

Security model

The tunnel is necessarily privileged — it executes commands on your machine on behalf of an AI. Memeri ships with these guardrails baked in:

Three command tiers

Every terminal_execute call is classified before running:

  • Safe — runs immediately. Read-only commands (ls, cat, git status, npm run …).
  • Destructive — pauses for in-chat user approval before running. rm -rf, git reset --hard, npm uninstall ….
  • Privileged — blocked outright. sudo, modifying ~/.ssh, system-level changes.

File access

  • All paths resolved against the project root you started the tunnel in
  • Path-traversal attempts (../../etc/passwd and friends) rejected
  • A built-in deny list covers obviously sensitive paths (.env files, .ssh/, .aws/)

Connection lifecycle

  • WebSocket auth requires your cb_* token at the start of the session
  • Token rotation invalidates active tunnel sessions; you'd reconnect
  • Closing the terminal that runs the tunnel ends the session (Ctrl+C); any in-flight processes are killed

What the tunnel can NOT do

  • Modify files outside the project root you started it in
  • Run as a different user
  • Execute privileged-tier commands (always blocked)
  • Persist any state on your machine beyond ~/.memeri/config.json (just your token + last project path)

Setup

# In the project folder you want the AI to access
~/.memeri/start-tunnel.sh

The launcher (written by the Connect-page installer) already has your gateway URL and token baked in, so there's nothing to configure — it connects on launch. Leave it running while you work; Ctrl+C revokes access.

Developing against a cloned repo without the installed wrapper? See Connect Your AI → Installing the Tunnel for the raw node packages/mcp-core/bin/codebridge-tunnel.js --api=… --token=… fallback.

Verifying

The tunnel logs its status. You'll see:

✓ Tunnel connected to gateway
✓ Watching folder: /path/to/your/project
✓ Local tool dispatcher ready

In the Memeri UI:

  • Connect page Service Status / Telemetry Health — the tunnel turns "Live" once it connects
  • Tools that route through the tunnel return _source: 'tunnel' in their response (vs 'railway' if they ran in the cloud sandbox instead)
  • If tool calls fail with mount paths (for example /home/dev/memeri-users/.../my-project), your connector session is not aligned to an active tunnel; reconnect both the tunnel and the connector, then retry

Disabling per-project telemetry

Same opt-out as the plugin: touch .claude/memeri-disabled in any project where you don't want telemetry forwarded.

When to NOT use the tunnel

  • You don't trust the AI to run shell commands — fair. Stick to MCP-only. The AI can still help by giving you commands you copy/paste.
  • You're working in a sensitive folder — pause the tunnel (Ctrl+C) or run it from a sandbox folder.
  • You have the Claude Code plugin already — the plugin gives you the local-tool path through a different mechanism. Running both is fine but adds no extra capability.

Cross-references

  • Choosing your setup tier — when MCP-only / Tunnel / Plugin is right for you
  • Connect Your AI → Installing the Tunnel — the full step-by-step
  • Concepts & Troubleshooting → Telemetry — Default-On & Opt-Out — the gating rules apply to tunnel telemetry too