From c50552ea8d79c396ee5a63e8dbd593b2f5baef06 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 16:02:57 +0000 Subject: [PATCH 1/2] feat(microsandbox): run the MCP runner inside the sandbox, switched from the web app In a microsandbox install the MCP runner is a process inside the sandbox rather than a container: as a user of its own, mcp, with the volume that holds the database and the archive closed to it (mode 750), Node and uv through read-only bind mounts, on the sandbox's localhost only. The upgrade agent's services switch adds mcp to COMPOSE_PROFILES in .env and nothing else there; the sandbox reads .env every few seconds and starts or stops the runner to match (microsandbox/mcp.sh, test-mcp.sh). The runner stops its servers on SIGTERM and takes LENS_MCP_BIND. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01CsyA2Kuhsnhzz2HjkD3zED --- .github/workflows/install.yml | 35 ++++++ CHANGELOG.md | 6 ++ DEVLOG.md | 9 +- docs/assistant.md | 10 +- docs/microsandbox.md | 6 +- docs/updates.md | 4 +- fastapi_backend/app/domain/services.py | 10 +- fastapi_backend/tests/api/test_services.py | 11 ++ mcp-runner/runner.py | 19 +++- microsandbox/mcp.sh | 74 +++++++++++++ microsandbox/run.sh | 23 +++- microsandbox/test-mcp.sh | 118 +++++++++++++++++++++ packaging/host/lens-upgrade.sh | 17 ++- packaging/host/test-services.sh | 11 ++ threat-model.md | 2 +- 15 files changed, 337 insertions(+), 18 deletions(-) create mode 100644 microsandbox/mcp.sh create mode 100644 microsandbox/test-mcp.sh diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index cfeb7d097..42a5165d8 100644 --- a/.github/workflows/install.yml +++ b/.github/workflows/install.yml @@ -370,6 +370,11 @@ jobs: ls -l /dev/kvm if [ -r /dev/kvm ] && [ -w /dev/kvm ]; then echo "this runner's user can already use KVM"; exit 1; fi + - name: The sandbox's scripts, tested apart (the MCP runner's loop, and the agent's services action) + run: | + docker run --rm -v "$PWD:/lens:ro" python:3.12-slim-trixie sh /lens/microsandbox/test-mcp.sh + sh packaging/host/test-services.sh + - name: Install (as a user would, piped into sh) run: | sh < install.sh | tee install.log @@ -438,6 +443,36 @@ jobs: grep -q '^LENS_TARGET=lean$' "$LENS_DIR/.env" || { echo "the run without LENS_TARGET changed the edition"; exit 1; } curl -fsS -o /dev/null "$(cat setup-url)" + - name: The MCP runner, switched on from the web app, runs inside the sandbox as its own user, and off again + run: | + export PATH="$HOME/.local/bin:$HOME/.microsandbox/bin:$PATH" + ctl="$LENS_DIR/.lens-control" + # what the web app's switch writes (services.py): the agent adds mcp to COMPOSE_PROFILES in .env + turn() { + printf 'id=mcp-%s\naction=services\nprofile=mcp\nturn=%s\n' "$1" "$1" >"$ctl/inbox/.upgrade.ci" && mv "$ctl/inbox/.upgrade.ci" "$ctl/inbox/upgrade" + for _ in $(seq 60); do grep -qx "id=mcp-$1" "$ctl/services-status" 2>/dev/null && grep -qE '^state=(done|failed)$' "$ctl/services-status" && break; sleep 2; done + cat "$ctl/services-status" + grep -qx 'state=done' "$ctl/services-status" + } + turn on + grep -q '^COMPOSE_PROFILES=mcp$' "$LENS_DIR/.env" + for _ in $(seq 30); do msb exec lens -- curl -fsS http://127.0.0.1:8090/health && break; sleep 2; done + msb exec lens -- curl -fsS http://127.0.0.1:8090/health | grep -q '"ok": true' + # as the mcp user, with the volume closed to it, and its token where Lens reads it + # shellcheck disable=SC2016 # expanded in the sandbox + msb exec lens -- sh -c 'for p in /proc/[0-9]*; do tr "\0" " " <"$p/cmdline" 2>/dev/null | grep -q lens-mcp-runner.py && stat -c %U "$p"; done' | grep -qx mcp + if msb exec lens -- setpriv --reuid mcp --regid mcp --clear-groups -- ls /data; then echo "the volume is open to the mcp user"; exit 1; fi + msb exec lens -- setpriv --reuid lens --regid lens --init-groups -- test -s /var/lib/lens-mcp-key/token + # and a server from npm runs in it, through Lens's own client + msb exec lens -- setpriv --reuid lens --regid lens --init-groups -- \ + env LENS_MCP_RUNNER_URL=http://127.0.0.1:8090 LENS_MCP_TOKEN_FILE=/var/lib/lens-mcp-key/token \ + PYTHONPATH=/data/.lens/backend /data/.lens/venv/bin/python -c 'from app.domain import mcp_client; t = mcp_client.Session({"command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory@2026.8.31"]}).tools(); assert any(x["name"] == "create_entities" for x in t), t; print(len(t), "tools")' + turn off + grep -q '^COMPOSE_PROFILES=' "$LENS_DIR/.env" && { echo "the profile is still in .env"; exit 1; } + for _ in $(seq 30); do msb exec lens -- curl -fsS -o /dev/null http://127.0.0.1:8090/health || break; sleep 2; done + if msb exec lens -- curl -fsS -o /dev/null http://127.0.0.1:8090/health; then echo "the runner still answers"; exit 1; fi + curl -fsS -o /dev/null "$(cat setup-url)" + - name: The full edition installs Chromium the first time Lens needs it, and again at each start run: | export PATH="$HOME/.local/bin:$HOME/.microsandbox/bin:$PATH" diff --git a/CHANGELOG.md b/CHANGELOG.md index e2c6d40b5..4d741fb92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are versioned together. +## Unreleased + +### Features + +- **microsandbox:** the MCP runner runs inside the sandbox, turned on and off from the web app like Docker's; it runs as a user of its own with the database and the archive closed to it + ## 0.16.0 October 18, 2026 {id="0.16.0"} ### Features diff --git a/DEVLOG.md b/DEVLOG.md index 06813caca..892a10002 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -188,9 +188,12 @@ plugin's stdio servers come along when an admin installs it. They run in the MCP `mcp` Compose profile), a container with none of Lens's data or keys, reached over HTTP with a token on a volume only it and the backend share. Recorded in the threat model. -Refine later: turn the runner on from Settings through the machine agent, as monitoring does, instead of -`COMPOSE_PROFILES=mcp` in `.env`; the runner on installs that don't use Docker (microsandbox, Cloudron, NAS packages); -plugin servers that run a program from the plugin's own folder; an egress allow-list for the runner's network. +Refine later: ~~turn the runner on from Settings through the machine agent~~ (done, the services switch); +~~the runner in a microsandbox~~ (done 2026-10-18: a process as the `mcp` user inside the sandbox, `microsandbox/mcp.sh`); +the runner on Cloudron and NAS packages; in a microsandbox, keeping the servers' packages across an update (they're on +the sandbox's disk, fetched again after it's replaced) and limits on the runner's memory and processes (the container +has them; a cgroup for the process would); plugin servers that run a program from the plugin's own folder; an egress +allow-list for the runner's network. ## 2026-10-10 · Pasted transcripts fetch no speech model diff --git a/docs/assistant.md b/docs/assistant.md index 765c87be2..03a4f6499 100644 --- a/docs/assistant.md +++ b/docs/assistant.md @@ -932,7 +932,15 @@ as an unprivileged user with every capability dropped, a read-only image and mem network only with Lens's backend (and the internet, which `npx` and `uvx` need to fetch the servers). Each server gets an empty folder as its home and only the environment its extension gives it; Lens talks to the runner over HTTP with a token the runner writes to a volume only the two share. A server starts on first use, stays up while it's used, -and stops after 15 idle minutes. Installs that don't run on Docker don't have the runner yet. +and stops after 15 idle minutes. + +In a [microsandbox](microsandbox.md) install the same switch works, and the runner is a process inside the sandbox +rather than a container: it runs as a user of its own, `mcp`, with the volume that holds the database and the archive +closed to it, with Lens's Node and uv reached through read-only mounts, listening on the sandbox's localhost only +(`microsandbox/mcp.sh`). The agent adds `mcp` to `COMPOSE_PROFILES` in `.env` and nothing else; the sandbox reads +`.env` every few seconds and starts or stops the runner to match, so the servers' packages come and go with the +sandbox (they're fetched again after an update). Other installs that don't run on Docker (Cloudron, NAS packages) +don't have the runner yet. ### The browser diff --git a/docs/microsandbox.md b/docs/microsandbox.md index 583e38cc2..b8c97e051 100644 --- a/docs/microsandbox.md +++ b/docs/microsandbox.md @@ -43,6 +43,8 @@ do: 3. Builds the backend and the web app from the code, read-only at `/lens`. It builds again only when the code changes. The web app is built on the sandbox's own disk, and only what it builds is kept in the volume. 4. Runs SurrealDB, the API, a job worker and the web app, and restarts any of them that stops. +5. Runs the [MCP runner](assistant.md#the-mcp-runner) while `COMPOSE_PROFILES` in `.env` names `mcp`, as the switch + in the web app sets it: a process as its own user, `mcp`, with the volume closed to it, on the sandbox's localhost. The database, the archive, the builds and the downloaded packages are in the named volume `lens-data`, which outlives the sandbox. A sandbox that is started again boots without running Lens, so Lens always starts in a fresh one: @@ -124,8 +126,8 @@ again for a few seconds, then moves what is left to `/data/.lens/trash` and goes ## Not yet -- **Matterbridge, Fedora and OpenSearch.** The opt-in Compose services don't run in the sandbox yet. Use Docker for - these. +- **Matterbridge, Fedora, OpenSearch, the browser, the code sandbox's gateway and monitoring.** The opt-in Compose + services other than the MCP runner don't run in the sandbox yet. Use Docker for these. - **Prebuilt images.** Each machine builds Lens itself, as `install.sh` does with Docker. Published images would make the first start quicker. - **Moving an install.** A Docker install doesn't move into a sandbox yet: its database and archive stay in Docker's diff --git a/docs/updates.md b/docs/updates.md index 72eebbfeb..9a2be2d89 100644 --- a/docs/updates.md +++ b/docs/updates.md @@ -68,7 +68,9 @@ profiles are fixed in the agent: `mcp` (the MCP runner), `browser` (the browser [code sandbox](assistant.md#the-gateway)'s gateway, its certificates and the client's key), `monitoring` ([Charts and history](prometheus.md#prometheus-and-grafana-ready-made): Prometheus, node-exporter and Grafana) and `mesh` ([Nodes and the mesh](mesh.md#on-this-machine): Nebula on the primary); it refuses any other. It reports in `services-status` and `services.log`. A request from an older Lens, with -`monitoring=on` or `off` and no profile, still works. +`monitoring=on` or `off` and no profile, still works. In a [microsandbox](microsandbox.md) install only `mcp` can be +turned: the agent changes `.env`, and the sandbox, which reads it every few seconds, starts or stops the runner inside +itself ([The MCP runner](assistant.md#the-mcp-runner)); the other profiles are refused there. With no agent (Lens wasn't installed with install.sh, the machine has neither systemd nor launchd, or install.sh ran with `LENS_UPGRADE_AGENT=0`), the API gives the one line to run on the machine instead (`manual`). diff --git a/fastapi_backend/app/domain/services.py b/fastapi_backend/app/domain/services.py index 121108a30..96f4d8d92 100644 --- a/fastapi_backend/app/domain/services.py +++ b/fastapi_backend/app/domain/services.py @@ -71,9 +71,15 @@ def _put(db, profile, run): def manual(profile): - """The line to run on the machine when there is no agent.""" + """The line to run on the machine when there is no agent (in a microsandbox, where the runner is a process the + sandbox starts as .env says, the setting to write instead: microsandbox/mcp.sh).""" where = os.environ.get("LENS_HOST_DIR") or "" - cd = f"cd {where} && " if where and updates.REF.match(where.lstrip("/~")) else "" + ok = bool(where and updates.REF.match(where.lstrip("/~"))) + if os.environ.get("LENS_BACKEND") == "microsandbox": + if profile != "mcp": + return f"this install runs in a microsandbox, where the {PROFILES[profile][0].lower()} doesn't run yet" + return f"add COMPOSE_PROFILES=mcp to {where + '/' if ok else ''}.env (the sandbox picks it up by itself)" + cd = f"cd {where} && " if ok else "" return f"{cd}docker compose -f docker-compose.prod.yml --profile {profile} up -d" diff --git a/fastapi_backend/tests/api/test_services.py b/fastapi_backend/tests/api/test_services.py index 5e75856e3..9d7d6bdd0 100644 --- a/fastapi_backend/tests/api/test_services.py +++ b/fastapi_backend/tests/api/test_services.py @@ -88,6 +88,17 @@ def test_monitoring_through_the_same_switch(client, db, control): assert client.get("/api/v1/admin/monitoring", headers=h).json()["on"] is True +def test_in_a_microsandbox_the_runner_is_a_setting_in_env(client, db, monkeypatch): + """The sandbox starts the runner itself as COMPOSE_PROFILES says (microsandbox/mcp.sh): without an agent, the + line to run is that setting; the other profiles don't run there.""" + monkeypatch.delenv("LENS_CONTROL_DIR", raising=False) + monkeypatch.setenv("LENS_BACKEND", "microsandbox") + monkeypatch.setenv("LENS_HOST_DIR", "/home/pi/lens") + h = admin(client, db) + assert of(client, h, "mcp")["manual"] == "add COMPOSE_PROFILES=mcp to /home/pi/lens/.env (the sandbox picks it up by itself)" + assert of(client, h, "browser")["manual"] == "this install runs in a microsandbox, where the browser doesn't run yet" + + def test_no_agent_shows_the_line_to_run(client, db, monkeypatch): monkeypatch.delenv("LENS_CONTROL_DIR", raising=False) h = admin(client, db) diff --git a/mcp-runner/runner.py b/mcp-runner/runner.py index 54b36f06c..61c0465fb 100644 --- a/mcp-runner/runner.py +++ b/mcp-runner/runner.py @@ -28,6 +28,7 @@ import re import secrets import shutil +import signal import subprocess import sys import threading @@ -38,6 +39,9 @@ HOME = os.environ.get("LENS_MCP_HOME", "/data") TOKEN_FILE = os.environ.get("LENS_MCP_TOKEN_FILE", "/key/token") PORT = int(os.environ.get("LENS_MCP_PORT", "8090")) +BIND = os.environ.get( + "LENS_MCP_BIND", "0.0.0.0" +) # 127.0.0.1 where Lens is on the same machine (a microsandbox) START_SECONDS = 180 # a first `npx -y` downloads the server CALL_SECONDS = 120 IDLE = 900 @@ -358,7 +362,7 @@ def do_POST(self): def serve(port=PORT, token=None): """The runner on `port` (0: any); returns the server (its .token, .server_address).""" - srv = ThreadingHTTPServer(("0.0.0.0", port), Handler) + srv = ThreadingHTTPServer((BIND, port), Handler) srv.daemon_threads = True srv.token = token or secrets.token_urlsafe(32) return srv @@ -372,7 +376,18 @@ def main(): f.write(srv.token) os.replace(tmp, TOKEN_FILE) threading.Thread(target=reap, daemon=True).start() - print(f"MCP runner on :{PORT}", flush=True) + + def quit( + *_, + ): # stopped (docker stop, or the sandbox's loop): the servers go with it + with LOCK: + for s in SERVERS.values(): + with s.lock: + s.stop() + sys.exit(0) + + signal.signal(signal.SIGTERM, quit) + print(f"MCP runner on {BIND}:{PORT}", flush=True) srv.serve_forever() diff --git a/microsandbox/mcp.sh b/microsandbox/mcp.sh new file mode 100644 index 000000000..4861fcfa2 --- /dev/null +++ b/microsandbox/mcp.sh @@ -0,0 +1,74 @@ +# The MCP runner in a microsandbox (docs/assistant.md "The MCP runner", docs/microsandbox.md), sourced by run.sh, +# which defines log(), CODE and OPT. Root only. test-mcp.sh tests it. +# +# With Docker the runner is a container of its own (mcp-runner/, the `mcp` Compose profile). Here it's a process in +# the sandbox as a user of its own, mcp, with the volume closed to it (/data is lens's alone, mode 750), so the servers +# it runs (the npx and uvx packages an admin named) see none of Lens's data, keys or database. Lens's Node and uv are +# given to it through read-only bind mounts, so it needn't see the volume they're kept in. It listens on the sandbox's +# localhost only, and writes its token where Lens reads it. +# +# It runs while COMPOSE_PROFILES in .env names mcp, the same setting as with Docker, which the machine's upgrade agent +# turns from the web app (packaging/host/lens-upgrade.sh: in a microsandbox it changes .env and nothing else). +# mcp_loop reads .env every few seconds (the install folder is mounted read-only, so the change shows at once), +# starts the runner, starts it again if it stopped, and stops it when the profile goes. + +MCP_HOME=/var/lib/lens-mcp # the servers' homes and caches: the sandbox's own disk, like the web app's build +MCP_KEY=/var/lib/lens-mcp-key # the token the runner writes and Lens reads +MCP_RUNNER=/var/lib/lens-mcp-runner.py +MCP_TOOLS=/opt/lens-mcp # Node and uv, mounted from the volume +MCP_PORT=8090 + +# mcp_wanted: whether .env's COMPOSE_PROFILES names mcp, read each time (the agent rewrites .env while Lens runs) +mcp_wanted() { + sed -n 's/^COMPOSE_PROFILES=//p' "$CODE/.env" 2>/dev/null | head -1 | tr ',' '\n' | grep -qx mcp +} + +# mcp_prepare: the user, its folders and a copy of the runner (/lens may be mounted with the host's permissions) +mcp_prepare() { + id mcp >/dev/null 2>&1 || useradd --system --no-create-home --shell /usr/sbin/nologin mcp + mkdir -p "$MCP_HOME" "$MCP_KEY" "$MCP_TOOLS/node" "$MCP_TOOLS/bin" + chown mcp:mcp "$MCP_HOME" "$MCP_KEY" + chmod 700 "$MCP_HOME" && chmod 755 "$MCP_KEY" + cp "$CODE/mcp-runner/runner.py" "$MCP_RUNNER" && chmod 644 "$MCP_RUNNER" +} + +# mcp_tools: Node and uv for the runner, as read-only bind mounts (a way to them without a way into the volume) +mcp_tools() { + for t in node bin; do + mountpoint -q "$MCP_TOOLS/$t" || mount --bind -o ro "$OPT/$t" "$MCP_TOOLS/$t" || return 1 + done +} + +# mcp_run: the runner, as the mcp user with only the environment named here (the test stands in for it) +mcp_run() { + exec setpriv --reuid mcp --regid mcp --clear-groups -- env -i \ + PATH="$MCP_TOOLS/node/bin:$MCP_TOOLS/bin:/usr/local/bin:/usr/bin:/bin" HOME="$MCP_HOME" LANG=C.UTF-8 \ + LENS_MCP_HOME="$MCP_HOME" LENS_MCP_TOKEN_FILE="$MCP_KEY/token" LENS_MCP_BIND=127.0.0.1 LENS_MCP_PORT="$MCP_PORT" \ + python3 "$MCP_RUNNER" +} + +# mcp_loop: the runner on while COMPOSE_PROFILES names mcp, off when it doesn't, until the sandbox stops +mcp_loop() { + child="" + trap 'if [ -n "$child" ]; then kill "$child" 2>/dev/null; wait "$child" 2>/dev/null; fi; exit 0' TERM + while :; do + if [ -n "$child" ] && ! kill -0 "$child" 2>/dev/null; then + wait "$child" 2>/dev/null || true + child="" + if mcp_wanted; then log "The MCP runner stopped; starting it again in 5 seconds"; fi + fi + if mcp_wanted; then + if [ -z "$child" ]; then + log "Starting the MCP runner (COMPOSE_PROFILES names mcp)..." + (cd "$MCP_HOME" && mcp_run) & + child=$! + fi + elif [ -n "$child" ]; then + log "Stopping the MCP runner (COMPOSE_PROFILES no longer names mcp)" + kill "$child" 2>/dev/null || true + wait "$child" 2>/dev/null || true + child="" + fi + sleep 5 + done +} diff --git a/microsandbox/run.sh b/microsandbox/run.sh index fc8c54ef9..694cb6abd 100755 --- a/microsandbox/run.sh +++ b/microsandbox/run.sh @@ -108,10 +108,10 @@ if [ ! -x "$OPT/node/bin/node" ]; then tar -xJf "/tmp/lens/$file" -C "$OPT/node" --strip-components 1 rm "/tmp/lens/$file" fi -if [ ! -x "$OPT/bin/uv" ]; then +if [ ! -x "$OPT/bin/uv" ] || [ ! -x "$OPT/bin/uvx" ]; then # uvx: the MCP runner's, for servers from PyPI log "Getting uv..." python3 -m pip install -q --no-cache-dir --target /tmp/lens/uv "uv>=0.8,<0.9" - cp /tmp/lens/uv/bin/uv "$OPT/bin/uv" && rm -rf /tmp/lens/uv + cp /tmp/lens/uv/bin/uv /tmp/lens/uv/bin/uvx "$OPT/bin/" && rm -rf /tmp/lens/uv fi # --- Build: the backend and the web app, again only when the code changed (the edition doesn't change them) ------- @@ -153,8 +153,10 @@ if [ "$(cat "$OPT/build-id" 2>/dev/null)" != "$build_id" ]; then chown -R lens:lens "$OPT/web" echo "$build_id" >"$OPT/build-id" fi -# the archive is the volume itself (data_dir: /data, as in the containers); the database is a folder in it +# the archive is the volume itself (data_dir: /data, as in the containers); the database is a folder in it, and the +# volume is lens's alone: the MCP runner's user (mcp.sh) has no way in chown lens:lens "$DATA" +chmod 750 "$DATA" || true chown -R lens:lens "$DATA/surreal" # public resolvers stood in for the downloads: this machine's again if they answer now, so names on its network resolve @@ -180,6 +182,8 @@ mkdir -p "$DATA/.cache" && chown lens:lens "$DATA/.cache" [ -d /control ] && export LENS_CONTROL_DIR=/control LENS_HOST_DIR="${LENS_DIR:-}" # the archive in the volume, as /data in the containers; the config file the backend image ships export ARCHIVE_CONFIG="$OPT/backend/docker/archive.yaml" +# the MCP runner (mcp.sh), where Lens reaches it and reads its token while it runs +export LENS_MCP_RUNNER_URL=http://127.0.0.1:8090 LENS_MCP_TOKEN_FILE=/var/lib/lens-mcp-key/token # model servers on the host machine (Ollama, LM Studio) under the name the Docker setup uses for them too if ! grep -q host.docker.internal /etc/hosts; then @@ -242,6 +246,19 @@ if [ "$TARGET" = full ]; then export LENS_PROGRAMS="$PROGRAMS" fi +# --- The MCP runner: on while COMPOSE_PROFILES names mcp, as the web app's switch sets it (docs/assistant.md) ---- +# shellcheck source=SCRIPTDIR/mcp.sh +. "$CODE/microsandbox/mcp.sh" +if mcp_prepare && mcp_tools; then + ( + set +e # a runner that stops is started again, and the loop goes on + mcp_loop + ) & + pids="$pids $!" +else + log "The MCP runner can't run in this sandbox (its user or tools couldn't be set up); MCP servers that are programs won't" +fi + log "Starting the database..." keep surrealdb "$DATA" surreal start --log info --bind 127.0.0.1:8001 --user "$SURREAL_USER" --pass "$SURREAL_PASS" \ "surrealkv:$DATA/surreal/lens.db" diff --git a/microsandbox/test-mcp.sh b/microsandbox/test-mcp.sh new file mode 100644 index 000000000..824de02e4 --- /dev/null +++ b/microsandbox/test-mcp.sh @@ -0,0 +1,118 @@ +#!/bin/sh +# Tests mcp.sh: the MCP runner started as the mcp user while COMPOSE_PROFILES in .env names mcp, started again when it +# stops, stopped when the profile goes, with the volume closed to it. Run it as root in the image run.sh runs in: +# +# docker run --rm -v "$PWD:/lens:ro" python:3.12-slim-trixie sh /lens/microsandbox/test-mcp.sh +set -eu + +here="$(cd "$(dirname "$0")" && pwd)" +work="$(mktemp -d)" && chmod 755 "$work" +loop="" +finish() { + [ -z "$loop" ] || kill "$loop" 2>/dev/null || true + wait 2>/dev/null || true + rm -rf "$work" +} +trap finish EXIT + +log() { printf '[lens] %s\n' "$*" | tee -a "$work/log"; } +fail() { + printf 'FAIL: %s\n' "$*" >&2 + exit 1 +} +ok() { printf 'ok: %s\n' "$*"; } +# wait_until COMMAND...: until it succeeds, for 20 seconds at most +wait_until() { + i=0 + until "$@"; do + i=$((i + 1)) + [ "$i" -lt 100 ] || return 1 + sleep 0.2 + done +} +said() { grep -c "$1" "$work/log" || true; } + +# the install folder, as the sandbox sees it: .env (the profile off) and the runner's code; the volume, lens's alone +CODE="$work/lens" OPT="$work/data/.lens" +mkdir -p "$CODE/mcp-runner" "$OPT/node/bin" "$OPT/bin" "$work/data/surreal" +cp "$here/../mcp-runner/runner.py" "$CODE/mcp-runner/" +echo "COMPOSE_PROFILES=matterbridge" >"$CODE/.env" +echo secret >"$work/data/surreal/lens.db" +chmod 750 "$work/data" + +# shellcheck source=SCRIPTDIR/mcp.sh +. "$here/mcp.sh" +MCP_HOME="$work/mcp-home" MCP_KEY="$work/mcp-key" MCP_RUNNER="$work/runner.py" MCP_TOOLS="$work/tools" MCP_PORT=18090 +mcp_prepare || fail "mcp_prepare" +id mcp >/dev/null || fail "no mcp user" +[ "$(stat -c %U:%a "$MCP_HOME")" = mcp:700 ] || fail "the runner's home is $(stat -c %U:%a "$MCP_HOME")" + +# 1. A stand-in runner: writes who it is and whether the volume is open to it, then waits +cat >"$work/fake-runner.sh" </dev/null 2>&1; then saw=open; else saw=closed; fi +echo "\$(id -un) \$saw \$HOME \$\$" >>"\$HOME/ran" +exec sleep 300 +EOF +chmod 644 "$work/fake-runner.sh" +mcp_run() { exec setpriv --reuid mcp --regid mcp --clear-groups -- env -i HOME="$MCP_HOME" sh "$work/fake-runner.sh"; } +( + set +e + mcp_loop +) & +loop=$! +sleep 1 +[ ! -f "$MCP_HOME/ran" ] || fail "it started with the profile off" + +sed -i 's/^COMPOSE_PROFILES=.*/COMPOSE_PROFILES=matterbridge,mcp/' "$CODE/.env" +wait_until test -f "$MCP_HOME/ran" || fail "the runner didn't start once .env named mcp" +read -r user saw home pid <"$MCP_HOME/ran" +[ "$user" = mcp ] || fail "it ran as $user" +[ "$saw" = closed ] || fail "the volume is open to the mcp user" +[ "$home" = "$MCP_HOME" ] || fail "its home is $home" +ok "the runner starts as the mcp user once COMPOSE_PROFILES names mcp, with the volume closed to it" + +# 2. Stopped, it's started again +kill "$pid" +ran_twice() { test "$(wc -l <"$MCP_HOME/ran")" -ge 2; } +wait_until ran_twice || fail "it wasn't started again" +[ "$(said 'starting it again')" -ge 1 ] || fail "the log doesn't say it was started again" +ok "a runner that stops is started again" + +# 3. The profile taken out of .env stops it +pid="$(tail -n 1 "$MCP_HOME/ran" | cut -d' ' -f4)" +sed -i 's/^COMPOSE_PROFILES=.*/COMPOSE_PROFILES=matterbridge/' "$CODE/.env" +wait_until sh -c "! kill -0 $pid 2>/dev/null" || fail "it still runs with the profile off" +sleep 6 +[ "$(wc -l <"$MCP_HOME/ran")" = 2 ] || fail "it was started again with the profile off" +ok "the profile taken out of .env stops the runner" +kill "$loop" && wait "$loop" 2>/dev/null || true +loop="" + +# 4. The real runner, as mcp_run runs it: it answers on the sandbox's localhost, and its token is where Lens reads it +unset -f mcp_run +# shellcheck source=SCRIPTDIR/mcp.sh +. "$here/mcp.sh" +MCP_HOME="$work/mcp-home" MCP_KEY="$work/mcp-key" MCP_RUNNER="$work/runner.py" MCP_TOOLS="$work/tools" MCP_PORT=18090 +sed -i 's/^COMPOSE_PROFILES=.*/COMPOSE_PROFILES=mcp/' "$CODE/.env" +( + set +e + mcp_loop +) & +loop=$! +health() { + python3 -c 'import sys, urllib.request; sys.exit(0 if b"ok" in urllib.request.urlopen("http://127.0.0.1:18090/health", timeout=2).read() else 1)' 2>/dev/null +} +wait_until health || fail "the runner doesn't answer on 127.0.0.1:18090: $(cat "$work/log")" +wait_until test -s "$MCP_KEY/token" || fail "no token" +[ "$(stat -c %U:%a "$MCP_KEY/token")" = mcp:644 ] || fail "the token is $(stat -c %U:%a "$MCP_KEY/token")" +# and refuses anyone without the token +code="$(python3 -c 'import urllib.request, urllib.error +try: urllib.request.urlopen(urllib.request.Request("http://127.0.0.1:18090/servers/x", data=b"{}", method="PUT"), timeout=2); print(200) +except urllib.error.HTTPError as e: print(e.code)')" +[ "$code" = 401 ] || fail "without the token it answered $code" +kill "$loop" && wait "$loop" 2>/dev/null || true +loop="" +not_health() { ! health; } +wait_until not_health || fail "the runner outlived the loop" +ok "the real runner answers on localhost with its token where Lens reads it, and stops with the loop" diff --git a/packaging/host/lens-upgrade.sh b/packaging/host/lens-upgrade.sh index a8eae7f73..57dbf5be6 100755 --- a/packaging/host/lens-upgrade.sh +++ b/packaging/host/lens-upgrade.sh @@ -18,7 +18,8 @@ # adds or removes the profile in COMPOSE_PROFILES in .env and starts or stops that profile's containers, those named in # services_of below and nothing else, and says how it went in .lens-control/services-status. A request from before # profiles, monitoring=on|off, is the monitoring profile. It comes in the same file as an upgrade, the one every agent -# watches. +# watches. In a microsandbox install only the MCP runner can be turned: it runs inside the sandbox, which watches +# COMPOSE_PROFILES in .env (microsandbox/mcp.sh), so the agent changes .env and nothing else. set -eu umask 022 # the containers read the status and the log @@ -66,9 +67,15 @@ services() { return 0 ;; esac + # In a microsandbox there are no containers to start: only the MCP runner runs there, inside the sandbox, which + # starts or stops it as COMPOSE_PROFILES in .env says (microsandbox/mcp.sh); the other profiles are Docker's + sandbox=0 if [ "$(env_of LENS_BACKEND)" = microsandbox ]; then - sstatus failed "finished_at=$(now)" "code=2" "error=$profile runs in Docker; this install runs in a microsandbox" - return 0 + if [ "$profile" != mcp ]; then + sstatus failed "finished_at=$(now)" "code=2" "error=$profile runs in Docker; this install runs in a microsandbox" + return 0 + fi + sandbox=1 fi sstatus running # the other profiles stay as they are @@ -79,6 +86,10 @@ services() { [ -z "$profiles" ] || echo "COMPOSE_PROFILES=$profiles" >>"$DIR/.env.tmp" cat "$DIR/.env.tmp" >"$DIR/.env" && rm -f "$DIR/.env.tmp" fi + if [ "$sandbox" = 1 ]; then + sstatus "done" "finished_at=$(now)" "code=0" + return 0 + fi if docker compose version >/dev/null 2>&1; then compose="docker compose"; else compose="docker-compose"; fi files="-f docker-compose.prod.yml" [ "$(env_of LENS_HTTPS)" = 1 ] && files="$files -f docker-compose.https.yml" diff --git a/packaging/host/test-services.sh b/packaging/host/test-services.sh index 92e67b064..9e441c734 100644 --- a/packaging/host/test-services.sh +++ b/packaging/host/test-services.sh @@ -105,3 +105,14 @@ case "$(said error)" in *"runs in Docker"*) ;; *) fail "it said: $(said error)" [ "$(wc -l <"$work/calls")" = "$calls" ] || fail "a refused request ran docker: $(last)" [ "$(profiles)" = matterbridge,monitoring ] || fail "a refused request changed COMPOSE_PROFILES: $(profiles)" ok "unknown profiles, other turns and microsandbox installs are refused, with nothing run" + +# 9. In a microsandbox the MCP runner is turned on and off through .env alone: the sandbox watches COMPOSE_PROFILES +# (microsandbox/mcp.sh), and Docker isn't run +ask id=m4 action=services profile=mcp turn=on +[ "$(said state)" = "done" ] && [ "$(said profile)" = mcp ] || fail "status: $(cat "$inst/.lens-control/services-status")" +[ "$(profiles)" = matterbridge,monitoring,mcp ] || fail "COMPOSE_PROFILES is $(profiles)" +ask id=m5 action=services profile=mcp turn=off +[ "$(said state)" = "done" ] && [ "$(profiles)" = matterbridge,monitoring ] || fail "COMPOSE_PROFILES is $(profiles)" +[ "$(wc -l <"$work/calls")" = "$calls" ] || fail "a microsandbox install ran docker: $(last)" +grep -qx 'LENS_BACKEND=microsandbox' "$inst/.env" || fail "the rest of .env went" +ok "in a microsandbox the MCP runner is turned on and off in .env, with nothing run" diff --git a/threat-model.md b/threat-model.md index 8860976a8..859eca68d 100644 --- a/threat-model.md +++ b/threat-model.md @@ -501,7 +501,7 @@ third-party source; dependencies come from `uv.lock`, the pnpm lockfile and cont | Real-ESRGAN general x4v3 (`enhance.image_engine` `realesrgan`, opt-in) | enlarging and cleaning up low quality pictures before they're read; the ONNX model is fetched at a pinned revision and checked against its SHA-256, and runs in ONNX Runtime on the CPU in fixed tiles of pictures Lens has already opened and size-checked | upstream for ONNX Runtime and the model's output; a model file that passes unchecked is in model | *(documented, docs/enhance.md "fetched the first time the step runs with it chosen")* | | Optional ML extras (whisper, pyannote, speechbrain, insightface, doctr) | model inference; some fetch weights on their own | upstream | *(inferred, Q19)* | | StyleTTS2 service (`styletts2/`, opt-in Compose profile) and macOS `say` | text to speech; StyleTTS2 fetches its weights from Hugging Face and GitHub on first use and listens only on the Compose network; `say` gets the text on stdin, never as arguments | upstream for the model and synthesis; the argument handling in model | *(maintainer, 2026-10)* | -| MCP runner (`mcp-runner/`, opt-in Compose profile) and the stdio MCP servers admins add (usually `npx` or `uvx` packages) | running those servers away from Lens: a container with none of Lens's data, keys or database, a non-root user, every capability dropped, `no-new-privileges`, a read-only image, memory and process limits, a network shared only with the backend (plus the internet to fetch packages), an empty home and only its extension's environment per server, and a bearer token on a volume only the two share | upstream for the servers and the packages they fetch (an admin's choice, trusted input, §1.3); the runner's isolation and token check in model | *(documented, docs/assistant.md "The MCP runner")* | +| MCP runner (`mcp-runner/`, opt-in Compose profile) and the stdio MCP servers admins add (usually `npx` or `uvx` packages) | running those servers away from Lens: a container with none of Lens's data, keys or database, a non-root user, every capability dropped, `no-new-privileges`, a read-only image, memory and process limits, a network shared only with the backend (plus the internet to fetch packages), an empty home and only its extension's environment per server, and a bearer token on a volume only the two share; in a microsandbox a process as its own user `mcp` inside the sandbox, with the volume (database, archive) mode 750 and lens's, Node and uv through read-only bind mounts, a home on the sandbox's disk, the sandbox's localhost only (`microsandbox/mcp.sh`, `microsandbox/test-mcp.sh`) | upstream for the servers and the packages they fetch (an admin's choice, trusted input, §1.3); the runner's isolation and token check in model | *(documented, docs/assistant.md "The MCP runner")* | | NVIDIA OpenShell gateway (opt-in; `sandbox.gateway`) and its Python SDK (`sandbox` extra, Apache-2.0) | running the assistant's code apart from Lens: an unprivileged user with no capabilities, Landlock on files, seccomp, and egress only as the sandbox's policy allows, enforced by its supervisor; the gateway holds the container runtime (the Docker socket with its Docker driver), so whoever it lets in can start containers | upstream for the sandbox's isolation and the gateway's own access control (mutual TLS); the policy Lens asks for (P-SANDBOX), and in the `sandbox` profile the gateway's container, its certificates and where its port is published (§1.6) in model; a gateway an admin runs elsewhere is theirs to keep on a network only Lens reaches | *(documented, docs/assistant.md "Code sandbox")* | | The browser (`mcr.microsoft.com/playwright/mcp`, pinned, opt-in Compose profile `browser`) and its proxy `browser-proxy` (`netguard.py` on its own) | running a headless Chromium the assistant drives over MCP away from Lens: a container with none of Lens's data, keys or database, every capability dropped, `no-new-privileges`, a read-only image, memory and process limits, its profile in memory only, a network shared only with the backend and worker and marked internal, and answering only to the `Host` `browser:8931`; its only way out is `browser-proxy`, which reaches public addresses on ports 80 and 443 only, with a byte budget per connection; its `browser_run_code_unsafe` tool starts switched off | upstream for Chromium and Playwright MCP (a pinned image, trusted input, §1.9); the container's isolation and the proxy's checks in model; one browser, with its cookies and open pages, is shared by everyone whose assistant uses it | *(documented, docs/assistant.md "The browser")* | | Lens's prebuilt images (`ghcr.io//lens-backend`, `lens-frontend`; opt-in `LENS_IMAGES=pull`) | the API, worker and web app a pulling install runs, built by images.yml from the release tag with the repository's `GITHUB_TOKEN` and pulled over TLS by version tag; a tag can be pushed again by whoever can write to the repository's packages, as the code itself can be changed by whoever can push to it | the build in model (it builds the tag's Dockerfiles, nothing else); GHCR and the registry's TLS upstream; integrity beyond HTTPS and the publisher is disclaimed as for other downloads (N-DOWNLOADS) | *(documented, docs/deployment.md "Prebuilt images")* | From e90c456e3502bfcb9a659c03a87ab47df1706d27 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 16:06:48 +0000 Subject: [PATCH 2/2] docs(threat-model): the MCP runner in the YAML's dependency table, with the microsandbox variant Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01CsyA2Kuhsnhzz2HjkD3zED --- threat-model.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/threat-model.yaml b/threat-model.yaml index 45432b11c..43bc900ca 100644 --- a/threat-model.yaml +++ b/threat-model.yaml @@ -1238,6 +1238,15 @@ dependencies: covered_here: false violation_disposition: "OUT-OF-MODEL: dependency-contract" provenance: {kind: inferred, question_id: Q19} + - name: "MCP runner (mcp-runner/, opt-in Compose profile mcp; in a microsandbox a process inside the sandbox) and the stdio MCP servers admins add (npx, uvx packages)" + relied_on_for: "running those servers away from Lens: with Docker a container with none of Lens's data, keys or database, a non-root user, every capability dropped, no-new-privileges, a read-only image, memory and process limits, a network shared only with the backend, an empty home and only its extension's environment per server, a bearer token on a volume only the two share; in a microsandbox a process as its own user mcp with the volume (database, archive) mode 750 and lens's, Node and uv through read-only bind mounts, a home on the sandbox's disk, the sandbox's localhost only" + relied_on_properties: [container-isolation] + caller_obligations_acknowledged: [] + adversary_capabilities_forwarded: [supply-parsed-bytes] + outputs_consumed: [tool results, passed to the model as outside text] + covered_here: false + violation_disposition: "OUT-OF-MODEL: dependency-contract" + provenance: {kind: documented, source: 'docs/assistant.md "The MCP runner"; microsandbox/mcp.sh, microsandbox/test-mcp.sh'} - name: "Lens's prebuilt images (ghcr.io//lens-backend, lens-frontend; opt-in LENS_IMAGES=pull)" relied_on_for: "the API, worker and web app a pulling install runs, built by images.yml from the release tag with GITHUB_TOKEN and pulled over TLS by version tag" relied_on_properties: [build-toolchain-integrity]