> ## 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
    ```

    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",
            "-e", "OPENCODE_CONFIG_CONTENT",
            "--", "opencode", "acp"
          ],
          "env": {
            "OPENCODE_CONFIG_CONTENT": "{\"model\":\"opencode/mimo-v2.5-free\"}"
          }
        }
      }
    }
    ```

    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.

    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 configuration:

    ```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>

## 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.

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="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>