ON
Code Execution

Onyx MCP Server for Secure Multi-language Docker Sandboxes

Run secure multi-language code in Docker sandboxes with Onyx MCP server, integrating with Claude Desktop and other MCP clients for safe executable AI workflows.

View on GitHub

Overview

Onyx is an MCP (Model Context Protocol) server that executes arbitrary code inside tightly constrained Docker sandboxes. It exposes a single MCP tool (run_code) that MCP-capable clients — such as Claude Desktop — can call to compile and run source code across multiple languages. The goal is to let AI assistants and other MCP clients execute user-supplied programs while minimizing risk from untrusted code.

The server enforces sandboxing primitives by running language runtimes in containers with networking disabled, read-only filesystems, temporary writable mounts, limited CPU/memory/process counts, and non-root user execution. This makes Onyx a practical building block for executable AI workflows, test harnesses, and interactive code evaluation directly from an LLM interface.

Features

  • Multi-language execution:
    • Python, Java, C, C++, JavaScript (Node.js), Rust
  • Strong Docker sandboxing:
    • Disabled network (–network none)
    • Read-only filesystem with tmpfs for writable workspace
    • Bounded CPU, memory, and process limits
    • Non-root process inside container (user 1000:1000)
  • MCP protocol integration:
    • Implements a run_code tool that MCP clients can call
  • Logging:
    • Execution logs written to stderr (safely surfaced by MCP clients)
  • CI-friendly:
    • Executor tests and GitHub Actions CI included in the project

Supported runtimes

LanguageDocker image
Pythonpython:3.11
Javaopenjdk:17
C / C++gcc:12
JavaScript / Node.jsnode:20
Rustrust:1.72

Installation / Configuration

Prerequisites:

  • Go 1.20+
  • Docker Desktop (macOS/Windows) or Docker Engine (Linux)

Verify prerequisites:

go version
docker --version

Pre-pull language images (recommended to avoid cold-start delays):

docker pull python:3.11
docker pull openjdk:17
docker pull gcc:12
docker pull node:20
docker pull rust:1.72

Build & run the server:

# Run directly (development)
go run ./cmd/server/main.go

# Build binary (recommended for desktop integration)
go build -o sandbox_server ./cmd/server/main.go
./sandbox_server

Configuring Claude Desktop (example):

  1. Open Claude Desktop config (Windows PowerShell example):
code $env:AppData\Claude\claude_desktop_config.json
  1. Add Onyx as an MCP server entry:
{
  "mcpServers": {
    "onyx": {
      "command": "C:\\path\\to\\sandbox_server.exe",
      "args": []
    }
  }
}
  1. Restart Claude Desktop. The run_code tool should be available to use within Claude.

Available Tools / Resources

  • run_code (MCP tool): Executes provided source code with a language tag and returns execution output, exit status, and logs.
  • Project layout (high level):
    • cmd/server/main.go — server entrypoint and tool registration
    • internal/executor/* — language-specific executors
    • internal/model — request/response types and executor interfaces
    • .github/workflows/ci.yml — CI for executor tests

Logs are written to stderr; MCP clients will not mix execution traces into model context inadvertently.

Extending to New Languages

To add a new runtime:

  1. Choose a Docker image (e.g., golang:1.22).
  2. Implement an executor in internal/executor/.go:
    • Provide an Execute method that copies code into /workspace, compiles/interprets, and runs it.
  3. Register the executor in cmd/server/main.go to map the language string to your executor.
  4. Add unit tests under internal/executor and update CI to pull the new image.

    5. Use Cases

    • Interactive coding in an LLM chat: Ask Claude (or another MCP-aware model) to write and run a Python snippet, get output and debug logs.
    • Education and tutorials: Run short code examples for students across different languages without exposing the host.
    • Test harness for AI-generated code: Automatically compile/run candidate patches produced by a model and capture results.
    • CI and fuzzing: Use the sandboxed executors in automated pipelines to run untrusted test cases safely.

    Security notes

    Onyx reduces attack surface by containerizing execution with network disabled and resource limits, but it does not replace a full security review for high-risk environments. Use additional host-level hardening, limit available Docker images, and run the server on isolated hosts for stronger guarantees.

    Repository and source: https://github.com/avd1729/Onyx

    Tags:claudecode-executiondockermcpsandbox