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

# OpenCode

> Run the OpenCode terminal agent against a project on your host

This guide installs OpenCode in a microVM and opens its terminal UI in a project mounted from your host. OpenCode edits the source checkout directly while its tools and dependencies stay inside the sandbox.

## Run OpenCode

<Steps>
  <Step title="Start OpenCode">
    <Tooltip tip="Writable host-directory mounts are local-only. On microsandbox cloud, use the isolated-copy alternative and omit replace-on-create."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

    Replace `./my-project` with the project directory you want OpenCode to work on:

    <CodeGroup>
      ```sh macOS & Linux theme={null}
      msb run -t --name opencode-demo --replace \
        --cpus 2 --memory 2G --root-disk 4G \
        --mount-dir ./my-project:/workspace:rw \
        --workdir /workspace \
        node:24-bookworm-slim -- sh -lc '
          apt-get update &&
          apt-get install -y --no-install-recommends ca-certificates git &&
          npm install -g opencode-ai@1.18.4 &&
          exec opencode
        '
      ```

      ```powershell Windows theme={null}
      msb run -t --name opencode-demo --replace `
        --cpus 2 --memory 2G --root-disk 4G `
        --mount-dir ./my-project:/workspace:rw `
        --workdir /workspace `
        node:24-bookworm-slim -- sh -lc '
          apt-get update &&
          apt-get install -y --no-install-recommends ca-certificates git &&
          npm install -g opencode-ai@1.18.4 &&
          exec opencode
        '
      ```
    </CodeGroup>

    The first run downloads the package and may take a couple of minutes. OpenCode should render its prompt and offer `/connect` for provider setup. Its XDG configuration, provider connections, and session data live on the sandbox's 4 GiB root disk and remain available when the sandbox stops and starts.

    <Tip>
      For an isolated workspace, or when using microsandbox cloud, replace `--mount-dir ./my-project:/workspace:rw` with `--copy-dir ./my-project:/workspace`. To try the TUI without a project, use `--mkdir /workspace` instead.
    </Tip>
  </Step>

  <Step title="Start another session">
    After leaving OpenCode, return to the same sandbox and workspace with:

    ```sh theme={null}
    msb exec -t opencode-demo -- opencode
    ```
  </Step>

  <Step title="Verify the installation">
    Exit the TUI, then run:

    ```sh theme={null}
    msb exec opencode-demo -- opencode --version
    ```

    The pinned example prints `1.18.4`.
  </Step>

  <Step title="Review or export changes">
    With the default writable mount, changes are already in the host checkout. Review the diff from either side of the mount:

    ```sh theme={null}
    msb exec opencode-demo -- sh -lc 'cd /workspace && git status --short && git diff --stat && git diff'
    ```

    If you chose the isolated `--copy-dir` alternative, export a patch from the sandbox:

    ```sh theme={null}
    msb exec opencode-demo -- sh -lc 'cd /workspace && git add -N . && git diff --binary > /tmp/opencode.patch'
    ```

    Copy the patch to the host:

    ```sh theme={null}
    msb cp opencode-demo:/tmp/opencode.patch ./opencode.patch
    ```

    Check that it applies cleanly before applying it:

    ```sh theme={null}
    git apply --check ./opencode.patch
    ```
  </Step>

  <Step title="Clean up">
    Remove the sandbox:

    ```sh theme={null}
    msb rm -f opencode-demo
    ```

    Removing the sandbox also removes its provider connections, sessions, and OpenCode configuration. Changes made through the default workspace mount remain in the host checkout. Never copy an agent's entire home directory back to the host.
  </Step>
</Steps>

## Use OpenCode from any project

To launch OpenCode from whichever project folder you are in, install a reusable host command:

<CodeGroup>
  ```sh macOS & Linux theme={null}
  msb install --tmp --name opencode-project \
    --cpus 2 --memory 2G \
    --mount-dir ./:/workspace:rw --workdir /workspace \
    --mount-named opencode-config:/root/.config/opencode \
    --mount-named opencode-data:/root/.local/share/opencode \
    --mount-named opencode-state:/root/.local/state/opencode \
    node:24-bookworm-slim -- sh -lc 'apt-get update && apt-get install -y --no-install-recommends ca-certificates git && npm install -g opencode-ai@1.18.4 && exec opencode'
  ```

  ```powershell Windows theme={null}
  msb install --tmp --name opencode-project `
    --cpus 2 --memory 2G `
    --mount-dir ./:/workspace:rw --workdir /workspace `
    --mount-named opencode-config:/root/.config/opencode `
    --mount-named opencode-data:/root/.local/share/opencode `
    --mount-named opencode-state:/root/.local/state/opencode `
    node:24-bookworm-slim -- sh -lc 'apt-get update && apt-get install -y --no-install-recommends ca-certificates git && npm install -g opencode-ai@1.18.4 && exec opencode'
  ```
</CodeGroup>

Then run this from a project folder on your host:

```sh theme={null}
opencode-project
```

`--tmp` creates a fresh sandbox for each session and removes it on exit. The `./` mount uses the folder you launch `opencode-project` from. Keep it relative; passing a full path during installation fixes the command to that folder.

Project edits stay on your host. The named volumes keep OpenCode's configuration, provider connections, and session history across runs. Other sandbox changes are discarded, so this example installs OpenCode and its dependencies again on each launch.

Without `--tmp`, an installed command reuses the same sandbox and its original workspace mount. See [`msb install`](/cli/sandbox-commands#msb-install).

To remove the host command:

```sh theme={null}
msb uninstall opencode-project
```

The three named volumes remain until you [remove them explicitly](/cli/volume-commands#msb-volume-rm).

## Reference

* [OpenCode installation](https://opencode.ai/docs/)


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