Running Pi Coding Agent for Java Development in Docker Sandbox

Docker Sandboxes provide isolated microVM environments for AI coding agents. Every sandbox has its own Docker daemon, filesystem, and network, so an agent can build containers, install packages, run development tools, and modify files inside an isolated environment.

Pi is a minimal terminal coding harness with support for TypeScript extensions, skills, prompt templates, themes, and packages.

This setup is intended specifically for Java development. It combines Pi with Docker Sandboxes and adds a reusable Java development environment.

Docker Sandboxes currently do not include a ready-made Pi template, so we can create one.

Install Docker Sandboxes

Install sbx with Homebrew and authenticate:

brew install docker/tap/sbx
sbx login

Add MCP secrets

Store both API keys as Docker Sandbox secrets:

sbx secret set-custom -g \
  --host mcp.tavily.com \
  --env TAVILY_API_KEY \
  --value "<YOUR_TAVILY_API_KEY>"

sbx secret set-custom -g \
  --host mcp.context7.com \
  --env CONTEXT7_API_KEY \
  --value "<YOUR_CONTEXT7_API_KEY>"

Pi authentication is handled separately through the browser using a Codex subscription, so there is no OpenAI API key in this setup, but it can be easily added as a secret.

Create the Dockerfile

In short, the sandbox will include:

• Java 21
• Gradle 8.5
• SDKMAN
• Pi Coding Agent
• OpenSpec
• Playwright
• MCP support for Pi
• Context7
• grep.app
• Tavily
• common command-line utilities required by the development toolchain

This gives Pi a complete Java development environment together with documentation search, source-code search, web research, browser automation, and MCP integration out of the box.

FROM docker/sandbox-templates:shell

USER root

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        curl \
        unzip \
        zip \
        ca-certificates \
    && rm -rf /var/lib/apt/lists/*

RUN npm install -g --ignore-scripts \
    @earendil-works/pi-coding-agent

ENV SDKMAN_DIR=/root/.sdkman

RUN curl -fsSL https://get.sdkman.io | bash \
    && bash -c '\
        source /root/.sdkman/bin/sdkman-init.sh && \
        sdk install java 21.0.10-tem && \
        sdk install gradle 8.5 \
    '

ENV JAVA_HOME=/root/.sdkman/candidates/java/current
ENV GRADLE_HOME=/root/.sdkman/candidates/gradle/current
ENV PATH="${JAVA_HOME}/bin:${GRADLE_HOME}/bin:${PATH}"

RUN npm install -g \
    @fission-ai/openspec@latest \
    @playwright/cli@latest

RUN npx playwright install-deps

USER agent
WORKDIR /home/agent

RUN pi install npm:pi-mcp-adapter

RUN mkdir -p /home/agent/.config/mcp

COPY --chown=agent:agent mcp.json /home/agent/.config/mcp/mcp.json

Configure MCP servers

Create mcp.json next to the Dockerfile:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
      }
    },
    "gh_grep": {
      "url": "https://mcp.grep.app"
    },
    "tavily": {
      "url": "https://mcp.tavily.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TAVILY_API_KEY}"
      }
    }
  }
}

The configuration gives Pi access to three MCP services:

• Context7 for Java library, framework, and API documentation
• grep.app for searching public source code and Java implementation examples
• Tavily for web search and research

The credentials are injected through the sandbox secrets configured earlier.

Build and publish the sandbox template

Build the image and push it to a registry:

docker build -t <your-login>/pi-template --push .

Create the sandbox

Create a named sandbox from the new template and start Pi:

sbx run --name pi --template <your-login>/pi-template shell -- -c pi

The sandbox now has a persistent Java development environment based on the custom image.

Inside Pi, complete the browser-based Codex authentication flow when prompted.

Sandbox persistence

The project directory is mounted from the host, so source code changes survive sandbox recreation. Sandbox-local state (Pi configuration, caches, and manually installed tools) exists only inside the sandbox unless explicitly persisted. Keep important project data in the mounted repository and use the Docker image for reproducible tooling.

Network access control

For a more restrictive setup, you can configure the sandbox with networking: deny all. This blocks all outbound connections by default.

Then allow only the hosts required for the agent workflow using a whitelist:

sbx policy init deny-all
sbx policy allow network "api.tavily.com,grep.app,mcp.context7.com,api.openai.com,auth.openai.com,chatgpt.com"

Start Pi again later

After the sandbox has been created, launch Pi with:

sbx run --name pi shell -- -c pi

The --template argument is only needed when creating the sandbox from the custom template.

Result

Pi can inspect and modify Java projects, run Gradle builds and tests, install additional tooling, use Docker, execute browser-based workflows, and access the configured MCP servers.

Java 21 and Gradle are available out of the box, while SDKMAN makes it straightforward to switch to another Java or Gradle version when a project requires a different toolchain.

The host system remains outside the agent's working environment, while the sandbox can be reused across future Java coding sessions.