# Opp Repl Sandbox

> Run opp_repl, simulations, and its MCP server under bubblewrap (bwrap) filesystem isolation with opp_sandbox. Sources are mounted read-only, the working directory read-write; a /.opp_sandbox sentinel lets the MCP server skip bearer-token auth inside the jail. Linux only. Load when running untrusted models, exposing execute_python to an agent more safely, or reproducing clean-environment builds.

- Skill: `tabgab/opp-repl-sandbox` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tabgab/opp-repl-sandbox`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tabgab/opp-repl-sandbox/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tabgab (https://skillmd.com/u/tabgab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tabgab/opp-repl-sandbox

---


# Sandboxed execution (opp_sandbox)

`opp_sandbox` wraps a command in a **bubblewrap** (`bwrap`)
container: read-only system + sources, a writable working
directory, dropped capabilities.  Qtenv GUI still works.  It is the
recommended way to expose `execute_python` to an autonomous agent
with reduced blast radius.

Upstream reference:
https://github.com/omnetpp/opp_repl/blob/main/doc/mcp_server.md
(the "Running inside opp_sandbox" section)

## Requirements

- **Linux** with `bubblewrap` (`bwrap`) installed
  (`sudo apt install bubblewrap`).  Not available on macOS.

## Usage

    opp_sandbox [options] [--] <command> [args...]

| Option                  | Meaning                                              |
|-------------------------|------------------------------------------------------|
| `-m, --mount DIR ...`   | Mount additional directories **read-only**           |
| `-w, --writable DIR ...`| Mount additional directories **read-write**          |
| `-h, --help`            | Print help                                           |
| `--`                    | End of options; everything after is the command      |

Example — a sandboxed REPL with the MCP server, no token needed:

    opp_sandbox -w ~/workspace -- \
        opp_repl --load "opp/*.opp" --mcp-port 9966

## Why the MCP server needs no token inside the sandbox

`opp_sandbox` bind-mounts a read-only sentinel at `/.opp_sandbox`.
opp_repl detects it (`is_running_in_sandbox()`) and **waives the
bearer-token requirement** for the MCP server — bubblewrap isolation
substitutes for auth.  Outside the sandbox, TCP MCP still requires
`--mcp-token-hash` or `--mcp-bypass-token-hash-check` (see
`opp-repl-mcp-server`).

## Overlays + sandbox

`fuse-overlayfs` mounts must be created **before** entering the
sandbox (the jail restricts FUSE).  Pre-mount with `opp_mount`, run
inside the sandbox, then `opp_unmount` afterwards:

    opp_mount "~/workspace/opp/*.opp"
    opp_sandbox -w ~/workspace -- opp_repl --load "opp/*.opp" --mcp-socket
    opp_unmount

See `opp-repl-overlay-builds` for the overlay mechanics.

## Pitfalls

- Linux-only.  On macOS there is no bubblewrap — rely on the Unix
  socket transport's `0600` permissions and a venv instead.
- Anything the sandboxed command must write (results, build output,
  overlay roots) needs an explicit `-w` mount, or you'll get
  read-only-filesystem errors.
- The sandbox isolates the filesystem, not the network; don't treat
  it as a full security boundary for hostile code.

## See also

- `opp-repl-mcp-server` — auth model the sandbox interacts with.
- `opp-repl-overlay-builds` — `opp_mount` / `opp_unmount` pre-mounting.
- `opp-repl-shared-terminal` — a different way to share one live REPL.