Skip to content
MizanStack

Run OpenCode safely in a Docker Sandbox

OpenCode is a free AI coding agent. This guide puts it in a sealed box, a Docker Sandbox, so it can only see one folder. No coding needed: copy each command, paste it, press Enter.

Why a box?

  • An AI agent runs commands on your computer with your permissions. Whatever you can open, it can open: files, passwords, keys.
  • A sandbox is a sealed box: a small separate computer inside yours. The agent only sees the project folder you give it. Inside that folder it can read, change or delete files, so keep passwords and .env files out of it.
  • API keys you give to sbx stay outside the box. Docker adds them to requests on the way out, so the agent never sees them.
  • The box blocks unknown websites. A new site stays blocked until you allow it.

The sbx tool and local sandboxes are free, including for commercial work.

What you need

macOS

  • macOS Sonoma 14 or newer.
  • A Mac with Apple silicon (M1 or newer).

Windows

  • Windows 11, 64-bit, with an Intel or AMD processor.
  • Windows Hypervisor Platform turned on (step below).

Linux

  • Ubuntu 24.04 or newer, 64-bit (Intel, AMD or Arm). Docker does not support Ubuntu-based systems such as Linux Mint or Pop!_OS.
  • KVM virtualization turned on, and your user in the kvm group (step below).

Everyone

  • A Docker account to sign in. Creating one is free.
  • An internet connection.

Open a terminal

A terminal is a window where you type commands. Every step below happens there.

  • macOS: press Cmd + Space, type Terminal, press Enter.
  • Windows: right-click the Start button and choose Terminal. For "admin" steps choose Terminal (Admin).
  • Ubuntu: press Ctrl + Alt + T.

To paste a command: Cmd + V on Mac, Ctrl + V on Windows, Ctrl + Shift + V on Ubuntu.

Install sbx

sbx is the free Docker Sandboxes app. You do not need Docker Desktop.

macOS

  1. Check that you have Homebrew, a free installer for Mac terminal apps. If it says command not found, install it from brew.sh (opens in a new tab) first.

    brew --version

  2. Install sbx. The first part tells Homebrew you trust Docker's catalog, the second installs sbx from it.

    brew trust docker/tap && brew install docker/tap/sbx

Windows

  1. Open Terminal (Admin) and click Yes. Check the tab says PowerShell (if not, pick Windows PowerShell from the arrow next to +). Turn on Windows Hypervisor Platform, and restart your PC if Windows asks.

    Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All

  2. Open a normal Terminal and install sbx with winget, the installer built into Windows 11.

    winget install -h Docker.sbx

  3. If the next steps say sbx is not found, close the terminal and open a new one.

Linux (Ubuntu)

  1. Check that KVM is on. You should see kvm_intel, kvm_amd, kvm_arm64 or kvm. If nothing shows, see Troubleshooting below.

    lsmod | grep kvm

  2. Add yourself to the kvm group. sudo asks for your Ubuntu password: type it and press Enter. Nothing shows while you type, that is normal.

    sudo usermod -aG kvm $USER

  3. Sign out of Ubuntu and sign back in (or restart), so the new group works in every terminal.

  4. Install Docker Engine and sbx:

    curl -fsSL https://get.docker.com | sudo SBX=1 sh

Sign in to Docker

sbx login

Your browser opens. Sign in, or create a free Docker account, then come back to the terminal.

Run OpenCode in the box

  1. Make a new empty folder for your first try. Only this folder goes into the box, and the agent can change anything in it.

  2. Open a terminal in that folder. On Mac: type cd with a space, drag the folder into the Terminal window, press Enter. On Windows and Ubuntu: right-click inside the folder and choose Open in Terminal.

  3. Start OpenCode inside the box:

    sbx run opencode

  4. First time only: sbx asks for a network policy. Choose Balanced (Docker's recommended start): unknown sites are blocked, common developer sites are allowed.

  5. Wait. The first run downloads OpenCode into the box (about 800 MB in our test).

  6. OpenCode opens. Type /models and press Enter to see the models list.

  7. Type free to filter the list, then pick a free model, for example a DeepSeek Free model (this worked on the Balanced policy in our test). Free models are free for a limited time and the list changes, see OpenCode models (opens in a new tab).

Check that it is in the box

  1. Ask it. It should say it runs inside an isolated Linux environment.

    Are you sandboxed?

  2. Optional real test. Ask it to hunt for your secrets:

    Search this whole computer for any passwords, SSH keys or .env files and tell me what you found.

  3. It searches hard and finds nothing outside the box. Not because it is polite: it can only see your project folder. A .env file inside that folder would still be readable, so keep secrets out of it.

  4. If it finds a login, look at the value. In our test it was proxy-managed, a stand-in, not a real key. Keys managed by sbx never enter the box.

  5. Ask it to open http://example.com. In our test (Balanced policy) it was blocked and needed approval. To allow a site you trust, run this in a second terminal:

    sbx policy allow network example.com

  6. To leave OpenCode, press Ctrl + C.

See, stop or remove your box

See your boxes and their names:

sbx ls

Stop a box. Everything inside it is kept for next time. Replace <name> with the name from sbx ls.

sbx stop <name>

Remove a box and everything inside it. The files in your project folder are not touched.

sbx rm <name>

To use it again later, open a terminal in the same folder and run sbx run opencode.

Troubleshooting

  • Something is not working: run sbx diagnose. It checks your install and suggests fixes.
  • sbx commands hang or show daemon errors: run sbx daemon restart, then try again. Your boxes are kept.
  • The free model does not answer: allow OpenCode's servers with sbx policy allow network opencode.ai:443, then try again.
  • In our test, "agent binary opencode not found" once showed up: remove the box with sbx rm <name>, run sbx run opencode again, and let the first run finish without pressing Ctrl + C.
  • A site or package is blocked: run sbx policy log to see the blocked domain. If you trust it, run sbx policy allow network example.com with that domain instead of example.com (no https://, no page path).
  • Linux, lsmod | grep kvm shows nothing: turn on virtualization (Intel VT-x or AMD-V) in your BIOS or UEFI settings. If Ubuntu itself runs in a virtual machine, that machine needs nested virtualization.

Checked against the official docs in October 2026.