Initial release: local sandbox MCP server for Apple Containers

Author: bird

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -q
+
+      - name: Compile check
+        run: python -m compileall sandbox_mcp_server.py tests
+
+  package:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build backend
+        run: python -m pip install --upgrade pip build hatchling
+
+      - name: Build package
+        run: python -m build

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+dist/
+PLAN.md

CLAUDE.md

@@ -0,0 +1,41 @@
+# sandbox-mcp
+
+MCP server for Apple Container sandboxes. Single-file Python server (`sandbox_mcp_server.py`, ~2850 lines) using FastMCP.
+
+## Project structure
+
+```
+sandbox_mcp_server.py   # Everything: Sandbox class, SandboxManager, 32 MCP tools
+pyproject.toml          # uv/hatchling packaging, entry point: sandbox-mcp
+Containerfile.mcp-dev   # Alpine 3.23 image with Python/Node/Go/Rust
+tests/                  # pytest test suite
+```
+
+## Key patterns
+
+- **Shell quoting**: Always use `_sq(value)` for any user-provided string interpolated into shell commands. Never use f-string quotes.
+- **Env key validation**: Use `_validate_env_key(key)` before any env var operations.
+- **Audit logging**: Pass `audit=False` for internal/diagnostic commands to keep the audit log clean.
+- **Port forwarding**: Uses `container exec -i <name> nc` proxy, NOT `-p` flag (broken in Apple Containers v0.9.0).
+- **Profile tuple**: `_get_profile()` returns `(cpus, memory, virtualization)` — 3-tuple, unpack accordingly.
+
+## Running
+
+```bash
+uv run sandbox-mcp              # stdio mode (for MCP clients)
+python3 sandbox_mcp_server.py   # also works
+```
+
+## Testing
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Adding a new tool
+
+1. Add manager method to `SandboxManager` class
+2. Add `@mcp_server.tool()` function that calls the manager method
+3. Update the docstring tool list at the top of the file
+4. Add to permissions in `~/.claude/settings.local.json`
+5. Run tests

Containerfile.mcp-dev

@@ -0,0 +1,40 @@
+FROM alpine:3.23
+
+# Core build tools
+RUN apk add --no-cache \
+    build-base \
+    cmake \
+    git \
+    curl \
+    wget \
+    jq \
+    tar \
+    gzip \
+    unzip \
+    openssh-client \
+    ca-certificates
+
+# Python
+RUN apk add --no-cache \
+    python3 \
+    py3-pip \
+    py3-setuptools \
+    py3-wheel \
+    py3-virtualenv
+
+# Node.js
+RUN apk add --no-cache \
+    nodejs \
+    npm
+
+# Go
+RUN apk add --no-cache go
+
+# Rust
+RUN apk add --no-cache \
+    rust \
+    cargo
+
+# Create workspace
+RUN mkdir -p /workspace
+WORKDIR /workspace

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bird
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.