> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Use JetBrains with a sandboxed agent

> Run OpenCode in a sandbox and chat with it from your JetBrains IDE

Keep your JetBrains IDE on your computer and run OpenCode inside a microsandbox. The IDE connects through [ACP](https://www.jetbrains.com/help/ai-assistant/acp.html), a protocol for talking to coding agents. No microsandbox IDE plugin is needed.

<Tooltip tip="Requires microsandbox v0.7.5 or later for streaming communication with the agent."><span className="msb-badge-version" tabIndex={0} aria-label="Requires microsandbox v0.7.5 or later"><Icon icon="circle-info" size={11} /> ≥0.7.5</span></Tooltip>

You need JetBrains AI Assistant.

<Steps>
  <Step title="Create a sandbox">
    Start with a small test project. Run these commands on your computer:

    ```bash theme={null}
    mkdir -p "$HOME/jetbrains-acp-demo"
    cd "$HOME/jetbrains-acp-demo"
    git init
    REPO_PATH="$(pwd -P)"

    msb create --name jetbrains-agent -c 2 -m 4G \
      -v "$REPO_PATH:$REPO_PATH" \
      -v jetbrains-agent-home:/root \
      -w "$REPO_PATH" node:22-bookworm </dev/null

    msb exec jetbrains-agent --no-tty -- \
      npm install -g opencode-ai@1.18.32 </dev/null

    msb exec jetbrains-agent --no-tty -- sh -c \
      'mkdir -p "$HOME/.config/opencode" && printf "%s\n" "{\"model\": \"opencode/mimo-v2.5-free\"}" > "$HOME/.config/opencode/opencode.json"' </dev/null
    ```

    The last command writes OpenCode's configuration to `~/.config/opencode/opencode.json` inside the sandbox. OpenCode loads this file on its own, so nothing about the model needs to live in the IDE's configuration. Edit it there, or copy in an existing `opencode.json` or `opencode.jsonc`, when you need more than a model name.

    Open this project in JetBrains using the same absolute path. The project must have the same path inside and outside the sandbox so the agent can find it.

    The project folder is shared: changes the agent makes also appear on your computer. The `jetbrains-agent-home` volume saves the agent's settings and login. Keep your host home directory unmounted.
  </Step>

  <Step title="Connect the agent">
    In **AI Chat > Add Custom Agent**, open `~/.jetbrains/acp.json` and add the configuration below. If the file already has agents, merge the entries instead of replacing it.

    Replace `/absolute/path/to/msb` with the output of:

    ```bash theme={null}
    command -v msb
    ```

    ```json theme={null}
    {
      "default_mcp_settings": {
        "use_idea_mcp": false,
        "use_custom_mcp": false
      },
      "agent_servers": {
        "OpenCode in microsandbox": {
          "command": "/absolute/path/to/msb",
          "args": [
            "exec", "jetbrains-agent", "--stream",
            "--", "opencode", "acp"
          ]
        }
      }
    }
    ```

    Keep `--stream`: it lets the IDE and agent exchange messages while the agent runs. Do not replace it with `--no-tty` or disconnect its stdin.

    `msb exec` runs as the sandbox's default user and sets `HOME` to that user's home directory. If your OpenCode configuration belongs to a different user, add `"-u", "<user>"` before `"--"`.

    The two MCP settings disable IDE and custom MCP tools, which may run outside the sandbox. These defaults also affect other agents that inherit them. Check that your sandbox agent does not override either setting to `true`.
  </Step>

  <Step title="Try it in AI Chat">
    Select **OpenCode in microsandbox** and send:

    > Create hello.txt, run ls and uname -s, then read hello.txt back to me.

    Check that `hello.txt` appears in your project and the shell reports `Linux`.

    The example model was used with test data. Before opening a real project, choose a provider and model approved for your data, log in inside the sandbox, and replace the model name in the sandbox's `opencode.json`:

    ```bash theme={null}
    msb exec jetbrains-agent -- opencode auth login
    ```

    Your login is saved in the sandbox's home volume. Do not commit credentials.
  </Step>
</Steps>

## Work on more than one project

`agent_servers` is an object keyed by the name shown in AI Chat, so it takes any number of named entries. It cannot be an array. You have two ways to cover several projects.

**One sandbox for all projects.** The IDE sends each project's path to the agent when a chat starts, so a single entry works for every project that is mounted at its host path. Mounts are set when the sandbox is created, so add one `-v` per project:

```bash theme={null}
REPO_A="$(cd /path/to/repo-a && pwd -P)"
REPO_B="$(cd /path/to/repo-b && pwd -P)"

msb create --name jetbrains-agent -c 2 -m 4G \
  -v "$REPO_A:$REPO_A" \
  -v "$REPO_B:$REPO_B" \
  -v jetbrains-agent-home:/root \
  -w "$REPO_A" node:22-bookworm </dev/null
```

The agent can reach every mounted project, whichever one the IDE has open. A project-level `opencode.json` still applies only to its own project.

A parent directory mounted at its host path, such as `-v "$HOME/Dev:$HOME/Dev"`, covers every project under it with one mount. The agent can then reach everything in that directory.

**One sandbox per project.** Create a sandbox for each project and add one entry per sandbox. The entries differ only in the sandbox name:

```json theme={null}
{
  "agent_servers": {
    "OpenCode: repo-a": {
      "command": "/absolute/path/to/msb",
      "args": ["exec", "agent-repo-a", "--stream", "--", "opencode", "acp"]
    },
    "OpenCode: repo-b": {
      "command": "/absolute/path/to/msb",
      "args": ["exec", "agent-repo-b", "--stream", "--", "opencode", "acp"]
    }
  }
}
```

Use this when projects must not see each other's files.

In scripted tests, one OpenCode 1.18.32 process kept a separate working directory and project configuration for each session. Opening several projects from the JetBrains GUI has not been verified.

## Share settings across entries

JetBrains supports `env` only inside an agent entry; there is no global `env`. Keep shared settings in the sandbox so there is nothing to copy:

* OpenCode settings go in the sandbox's `~/.config/opencode/opencode.json`.
* Environment variables go on the sandbox: pass `-e KEY=value` to `msb create`. To change one on a running sandbox, run `msb modify jetbrains-agent -e KEY=value --restart` to apply it now, or use `--next-start` to save it for the next start.

## What the sandbox protects

The agent can edit the shared project. ACP also allows agents to ask the IDE to read files or run commands on the host, so running an agent in a sandbox does not automatically keep every tool inside it. The MCP settings above do not disable those ACP requests. Review any MCP servers configured in the agent, too.

Do not mount `~/.jetbrains` into the sandbox. The IDE reads `acp.json` on your computer, and the agent does not need it. That file sets the commands the IDE runs on the host, so an agent that can write to it can change what runs outside the sandbox.

Scripted tests of OpenCode 1.18.32 kept file and shell operations inside the sandbox and could not read an unmounted host file. Recheck this behavior when changing agents or versions. The JetBrains GUI flow has not been verified, and the IDE can still send project context to the model.

## Other options

<AccordionGroup>
  <Accordion title="Override OpenCode settings for one entry">
    `OPENCODE_CONFIG_CONTENT` holds OpenCode configuration as a JSON string and takes precedence over the configuration files. Use it when one entry needs a different setting, such as a second entry with another model:

    ```json theme={null}
    {
      "args": [
        "exec", "jetbrains-agent", "--stream",
        "-e", "OPENCODE_CONFIG_CONTENT",
        "--", "opencode", "acp"
      ],
      "env": {
        "OPENCODE_CONFIG_CONTENT": "{\"model\":\"opencode/mimo-v2.5-free\"}"
      }
    }
    ```

    The `-e` flag forwards the variable into the sandbox. To load a configuration file from a non-default path instead, forward a path with `"-e", "OPENCODE_CONFIG=/path/in/sandbox/opencode.json"`.
  </Accordion>

  <Accordion title="Use Claude Code instead">
    Install the adapter and Claude Code in the same sandbox, then log in:

    ```bash theme={null}
    msb exec jetbrains-agent --no-tty -- npm install -g \
      @agentclientprotocol/claude-agent-acp@0.81.2 \
      @anthropic-ai/claude-code@2.1.282 </dev/null
    msb exec jetbrains-agent -- claude auth login
    ```

    Complete the browser login and paste the returned code into the guest terminal if prompted.

    Add an entry under `agent_servers` with the same `command` path and these arguments:

    ```json theme={null}
    {
      "args": ["exec", "jetbrains-agent", "--stream", "--", "claude-agent-acp"]
    }
    ```

    Keep both MCP settings `false`. The adapter initialized in scripted testing, but authenticated prompts and isolation remain unverified. Its [changelog](https://github.com/agentclientprotocol/claude-agent-acp/blob/v0.81.2/CHANGELOG.md#0180) says version 0.18.0 switched to built-in Claude tools; older adapters may behave differently.

    If using an API key, add `"-e", "ANTHROPIC_API_KEY"` before `"--"` to pass it into the sandbox. Values in `acp.json`'s `env` only reach the host subprocess unless explicitly forwarded. Prefer the saved guest login to putting keys in this file.
  </Accordion>

  <Accordion title="Connect through SSH instead">
    Authorize your public key:

    ```bash theme={null}
    msb ssh authorize --file ~/.ssh/id_ed25519.pub
    ```

    Add this to `~/.ssh/config`, replacing the `msb` path:

    ```sshconfig theme={null}
    Host jetbrains-agent.msb
      User root
      IdentityFile ~/.ssh/id_ed25519
      IdentitiesOnly yes
      ProxyCommand /absolute/path/to/msb ssh serve jetbrains-agent --stdio
    ```

    Verify the host key on first connection. In JetBrains Gateway, enable parsing of `~/.ssh/config` and select this host.

    SSH commands and SFTP were tested. Gateway backend installation and IDE startup remain untested. See [SSH](/sandboxes/ssh#proxycommand) and [Gateway setup](https://www.jetbrains.com/help/idea/remote-development-a.html).
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.