Skip to content

feat(microsandbox): run the MCP runner inside the sandbox, switched from the web app - #632

Merged
adeelahmad merged 2 commits into
mainfrom
claude/project-thread-ks9sah
Oct 18, 2026
Merged

adeelahmad merged 2 commits into
mainfrom
claude/project-thread-ks9sah

Conversation

@adeelahmad

Copy link
Copy Markdown
Owner

Requested by Adeel · project thread

Description

Before: on a microsandbox install, the Run the MCP runner on this machine switch failed with "mcp runs in Docker; this install runs in a microsandbox", so MCP servers that run as a program (npx, uvx) couldn't be used there.

After: the same switch works. The 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, lens's alone), Node and uv reached through read-only bind mounts, listening on the sandbox's localhost only. The upgrade agent 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, starting it again if it stops. Without an agent, the switch shows the .env line to write instead of a Docker line.

How: microsandbox/mcp.sh (sourced by run.sh) holds the user and folder setup, the bind mounts and the loop; the agent's services action takes the microsandbox branch for mcp only; the runner takes LENS_MCP_BIND and stops its servers on SIGTERM; run.sh also keeps uvx next to uv for servers from PyPI.

Motivation and Context

Follows #304 (the runner, Docker only) and #506 (the switch). Adeel's rule: every setting in the web app, on Docker and microsandbox alike.

Steps to reproduce (if appropriate):

  • microsandbox/test-mcp.sh (run in the sandbox's image) checks the loop: starts as mcp once .env names the profile, with the volume closed to it; started again after it stops; stopped when the profile goes; and the real runner answering on localhost with its token where Lens reads it, 401 without the token.
  • packaging/host/test-services.sh case 9: in a microsandbox the agent changes .env only and runs no Docker.
  • The microsandbox install job runs both scripts, then end to end: switches the runner on through the agent, checks it runs as mcp, that mcp can't list /data, lists the tools of @modelcontextprotocol/server-memory through Lens's own client, and switches it off.
  • tests/api/test_services.py: the line shown without an agent in a microsandbox.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (make hooks checks it on commit).
  • I added or updated tests.
  • My change requires documentation updates, and I have updated docs/ accordingly.
  • Users need more than the title to understand it, so I wrote it under ## Unreleased in CHANGELOG.md.

Done questions (AGENTS.md)

  • Goal: the runner on microsandbox, switched from the web app; merged on green CI.
  • Agents: the same PUT /api/v1/admin/services/mcp and MCP set_service.
  • Zero setup: the switch does it; no .env edit or reinstall.
  • Fewest clicks: one switch, as on Docker.
  • Configurable: no new setting; COMPOSE_PROFILES as before.
  • Light: off by default; nothing runs until switched on.
  • Private and secure: the runner's user has no way into the volume; localhost only; token-gated; threat model row updated.
  • Cost: n/a, no model calls; mcp.list/mcp.call in the ledger as before.
  • User decides: admins switch it; defaults unchanged.
  • Upgrades: n/a, no stored-data change; an existing sandbox install gets the loop at its next start (the volume's mode changes to 750, lens's own).
  • Honest: docs say what runs where; Cloudron and NAS packages still listed as not yet.
  • Tests, docs (assistant.md, microsandbox.md, updates.md, threat model, CHANGELOG, DEVLOG); no generated files.
  • Open: standard library runner, MCP; nothing new.
  • Reported in the project thread; refine-later in DEVLOG (packages lost at an update, no memory/process limits on the process).
  • Reuse: the existing agent, switch and runner; only the sandbox side is new.

Generated by Claude Code

…rom 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CsyA2Kuhsnhzz2HjkD3zED
…th the microsandbox variant

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CsyA2Kuhsnhzz2HjkD3zED
@adeelahmad
adeelahmad merged commit 317cc6f into main Oct 18, 2026
22 checks passed
@adeelahmad
adeelahmad deleted the claude/project-thread-ks9sah branch October 18, 2026 16:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants