Junie Sandbox

This project provides a sandboxed environment for running the JetBrains Junie agent using Docker, ensuring isolated and secure code execution.

How it works

The project utilizes a run.sh script to manage a Docker-based sandbox. It builds an image that includes the Junie agent and necessary development tools. When executed, it mounts your local workspace into the container, allowing Junie to work on your code in a controlled environment. It supports both Agent Control Protocol (ACP) mode for IDE integration and a standalone CLI mode.

Usage

1. Installation

Clone the repository:

git clone https://github.com/studio-b12/junie-sandbox.git
cd junie-sandbox

2. Authentication

To use Junie, you need to provide an API key. You can retrieve your token at https://junie.jetbrains.com/tokens.

Configuration via Secrets File

By default, the script looks for an environment file at $XDG_CONFIG_HOME/junie-sandbox/secrets.env (or ~/.config/junie-sandbox/secrets.env if XDG_CONFIG_HOME is not set).

Create this file and define the JUNIE_API_KEY environment variable:

JUNIE_API_KEY=your_api_key_here

Configuration via Command Line

Alternatively, you can pass an environment file containing your secrets using the -e or --env flag:

./run.sh --env path/to/secrets.env

3. Building the Image

Build the default sandbox image:

./run.sh --build --no-run

Customizing the Build

• Specify a base image:

  ./run.sh --build <base-image> --no-run

• Define a custom image name:

  ./run.sh --build <base-image> --image junie-sandbox:custom --no-run

A preconfigured buildbox image containing Go, Rust, Node.js, Python 3, and Task is available in base/buildbox.Dockerfile.

4. Building Base Images

The base/ directory contains Dockerfiles for various development environments. You can use the build-base-image.sh script to build these images:

./build-base-image.sh <image-name>

For example, to build the buildbox image:

./build-base-image.sh buildbox

5. Execution

The run.sh script supports two primary execution modes:

• ACP Mode (Default): Starts the agent using the Agent Control Protocol over STDIO, enabling seamless integration with IDEs.
• CLI Mode: Runs the agent in a standalone interactive terminal:

  ./run.sh --cli

Advanced Options

• Mount additional volumes: Use -m or --mount to map local files or directories into the sandbox:

  ./run.sh --mount /host/path:/container/path:ro

  The format is SRC[:DST[:MODE]]. If omitted, DST defaults to SRC and MODE defaults to rw.

• Network Proxy: Restrict egress traffic through a Squid proxy using -p or --proxy:

  ./run.sh --proxy proxy/squid.conf

  This builds and runs a sidecar proxy container. The provided proxy/squid.conf demonstrates a whitelist approach, allowing only specific domains (e.g., LLM APIs and package registries).

Persistence and Privacy

Configuration and Persistence

In CLI mode (--cli), the script automatically mounts the ${HOME}/.junie directory from your host into the container if it exists. This ensures that your Junie configuration, history, and settings are preserved between sessions.

Privacy

By default, the sandbox environment is configured to disable anonymous statistics sharing (shareAnonymousStatistics: false) by pre-seeding the .junie/settings.json file during the image build.

Configuration Examples

Add the following configurations to use the script with your favorite Editors or IDEs:

Zed

Open the Command Panel with Ctrl+Shift+P, enter zed: open settings file and press enter.

Add the following entry to the agent_servers section:

{
  "agent_servers": {
    "junie-sandbox": {
      "type": "custom",
      "command": "<dir-to-the-repo>/run.sh",
      // Optional args for the script
      "args": ["--image", "junie-sandbox:buildbox"],
      "env": {}
    }
  }
}

JetBrains IDEs

Open the AI Chat Window -> Click on the Three Dots in the top right corner -> "Add custom agent". This creates and opens a settings file where you can add the following configuration:

{
  "default_mcp_settings": {},
  "agent_servers": {
    "Junie Sandboxed": {
      "command": "<dir-to-the-repo>/run.sh",
      // Optional args for the script
      "args": ["--image", "junie-sandbox:buildbox"],
      "env": {}
    }
  }
}

---

Licensed under the BSD-3-Clause License. No AI-agents were hurt during the development of this project.