The AI can be pretty unpredictable about what it does via the MCP tools, and that's why many AI assistants would ask for a user confirmation before using tools with potentially harmful side effects. If you don't want to always review the commands or if you simply want a better safety by default, it is wise to limit those side effects more or less to only the intended cases. Running the nREPL in an isolated, containerized environment is a way to achieve this.

Sandboxing is only required for the nREPL evaluation environment. The bash and clojure_eval tools execute within the attached nREPL environment, which means sandboxing your project's nREPL process is sufficient—there's no need to sandbox the MCP server separately.

Beyond just sandboxing an unpredictable AI, adopting a containerized development environment offers substantial benefits for individual developers and teams:

• Reproducibility: A containerized environment ensures that every team member uses the exact same development setup, from the OS libraries to the language runtime and tooling versions. This eliminates the classic "but it works on my machine" problem, creating a consistent experience for everyone.
• Reduced Friction with CI/CD: When your development environment is a container, it can be the same environment used by your Continuous Integration (CI) tooling. This alignment dramatically reduces friction and ensures that code that runs locally will also run in the pipeline.
• Evolving and Branch-Specific Toolchains: Containers make it easy to manage and evolve your development toolchain. You can test new tools or versions in an isolated environment without affecting your host machine. This also allows for powerful workflows like using branch-specific tooling; for instance, you could add a static site generator to a docs branch to build documentation, without that tool being present in the main development environment.
• Supply Chain Security: By isolating the development environment, you create a barrier against a subgroup of supply chain attacks. A compromised dependency would be contained within the sandbox, unable to access or exfiltrate data from your broader host system.

In essence, while the initial motivation might be to safely manage an AI, adopting a containerized workflow brings a host of modern development practices that enhance security, collaboration, and consistency.

There are different solutions for this problem, and Docker is only one of them. You might consider other container platforms like Podman.

On macOS and Windows, container platforms require a Linux virtual machine (VM) to run. This means you have two layers of abstraction: the guest VM on your developer machine, and the containers running inside that VM. For some, it might be a more straightforward approach to not use containers at all and instead use a lightweight VM directly as the sandboxed environment.

However, this guide will focus on Containers as it is a very common and well-documented solution in the industry.

When using Docker, there are two primary approaches to sandboxing your Clojure development environment in the context of an MCP server like ClojureMCP. One is keeping the MCP server outside of the container, the other is running both the nREPL server and the MCP server inside the container.

The main rationale on choosing one over the other is path equivalence, which is required for Clojure MCP to be able to access the files on the correct paths. If you run Clojure MCP outside of the container, the paths to the files would need to be equivalent to the paths to the files inside the container. You can achieve this by mounting the directories of the host filesystem to equivalent places in the container filesystem.

If that's not a way to go, you can use the second approach and embed the Clojure MCP server into the container.

This is the most straightforward and common approach. The core idea is to run your Clojure project's nREPL server inside a container, while your development tool (ClojureMCP, VS Code, Emacs) and the MCP server run directly on your host machine.

ClojureMCP is designed so that you only need to sandbox the nREPL process to contain the execution of AI-generated code. Your editor and the ClojureMCP server connect to the containerized nREPL via a published port. This guide focuses primarily on this method.

• Running nrepl in a container

The key reason for this approach is to guarantee path consistency. Especially if you already have an established container it may be easier to bring clojure-mcp into the container.

• Running both mcp server and nrepl in a container