Latest revision as of 17:24, 23 February 2026

Beginner's Guide to OpenCode Isolation and Burner Workflows

Welcome! If you are using OpenCode (or similar AI coding agents), you are giving an AI the ability to run commands on your computer. While incredibly powerful, this comes with risks. A confused AI—or a malicious hidden instruction (prompt injection) in a downloaded file—could accidentally delete your personal files or mess up your system.

This guide teaches you how to use Distrobox to create "sandboxes" (isolated containers). By putting the AI in a sandbox, any damage it causes stays locked inside that box, keeping your real computer completely safe.

Key Concepts (Think of it like a Video Game)

Containers (The Sandbox): A mini, isolated operating system running inside your real computer.
Golden Image (The Master Save File): A perfectly set-up container with all the tools installed. We copy this every time we start a new project so we don't have to install things twice.
Save Points (Checkpoints): Just like saving your game before a boss fight, we can "commit" our container's state. If the AI breaks the code later, we can reload the save!
Burner Home: A special, restricted folder we give to the AI instead of letting it see your real Documents or Desktop folders.

1. Hardware Reality Check

Before we begin, AI agents need to "read" your code to understand it. The amount of code they can remember at once is called the Context Window. To process large context windows, your graphics card (GPU) needs memory, called VRAM.

Here is what you can expect based on your hardware:

Your GPU VRAM	Example Graphics Card	Context Window (Memory)	What this means for you
8GB	Radeon RX 7600	8k–16k	Good for small scripts, but might crash on large projects.
16GB	Radeon RX 9070 XT	~32k	The minimum recommended for a smooth AI agent experience.
20GB	Radeon RX 7900 XT	64k–80k	The "Sweet Spot." Handles multiple large files easily.
32GB+	Mac Studio / Pro GPUs	128k+	Can read entire massive codebases at once.

(Note: If you have a computer with "Unified Memory" like an Apple Silicon Mac or a Ryzen AI Max+, you can use system RAM for AI, which allows for huge memory but runs a bit slower).

2. Setting up the "Golden Image" (One-Time Setup)

You only need to do this section once! We are going to build our "Master Save File" that has all the programming tools the AI needs.

Step 2.1: Install Distrobox on your Host Computer

First, we need the software that makes the sandboxes. Run the command for your computer's operating system:

# If you use Debian or Ubuntu:
sudo apt install distrobox    

# If you use Fedora:
sudo dnf install distrobox    

# If you use Arch Linux:
yay -S distrobox

Step 2.2: Create the Base Sandbox

Now we create a brand new, empty sandbox named oc-base. We also tell it to use a fake home directory (~/sandbox-homes/oc-base) so it can't see your real personal files.

# 1. Create the folder that will act as the fake home
mkdir -p ~/sandbox-homes/oc-base

# 2. Build the sandbox using Ubuntu as the base system
distrobox create --name oc-base --image ubuntu:24.04 --home ~/sandbox-homes/oc-base

# 3. Step inside the sandbox!
distrobox enter oc-base

Step 2.3: Equip the Sandbox with Tools

Now that you are inside the sandbox, let's install the tools the AI needs to write and test code (like Node.js, Python, and Git).

# Download and install Node.js, Git, and Python
curl -fsSL [https://deb.nodesource.com/setup_lts.x](https://deb.nodesource.com/setup_lts.x) | sudo -E bash -
sudo apt install -y nodejs git python3

# Install the OpenCode AI software globally
npm install -g opencode-ai

# Run OpenCode once to set up your API keys and authenticate
opencode

Step 2.4: Create a Helper Script

To make starting projects easier later, we'll create a shortcut script. Still inside the sandbox, run these commands to create a file called opencode_isolation.sh:

# Create the project directory first
mkdir -p ~/project

# Create the script
cat << 'EOF' > ~/project/opencode_isolation.sh
#!/bin/bash
# This script starts OpenCode safely inside our current folder.
WORK_DIR="$(cd "$(dirname "$0")" && pwd)"

cd "$WORK_DIR"
echo "Starting OpenCode..."
echo "Working directory: $WORK_DIR"
echo ""

exec opencode "$@"
EOF

# Make the script executable (runnable)
chmod +x ~/project/opencode_isolation.sh

Step 2.5: Save the Master Sandbox

Now we step out of the sandbox and save it as our "Golden Image" template.

# 1. Leave the sandbox and return to your real computer
exit  

# 2. Turn off the sandbox
distrobox stop oc-base

# 3. Save it as a reusable template (image) named "oc-base:latest"
podman container commit oc-base localhost/oc-base:latest

# 4. Verify it was saved successfully
podman image ls

3. Protect Your Identity: The GitHub "Burner" Account

Important: Do NOT give the AI access to your personal GitHub account! If the AI gets confused, it might delete your repositories or leak your private code.

Go to GitHub and create a completely new, separate account (a "burner" account).
Generate a Personal Access Token for this new account.
Set the token to expire in 90 days.
Only give the token repo and workflow permissions.
Use this account and token when setting up git inside your sandboxes.

4. Daily Workflow: How to Use Your Sandboxes

Now that your Golden Image is ready, here is how you will actually work day-to-day. We use a naming convention with the date to keep things organized (e.g., oc-260216 means OpenCode project from Feb 16, 2026).

Scenario A: Starting a Brand New Project

We will copy the master save file to create a fresh workspace.

# On your main computer:
# 1. Make a folder for today's project
mkdir -p ~/sandbox-homes/oc-260216

# 2. Create a new sandbox cloned from your Golden Image
distrobox create --name oc-260216 --image localhost/oc-base:latest --home ~/sandbox-homes/oc-260216

# 3. Enter the new sandbox
distrobox enter oc-260216

# Inside the sandbox:
# 4. Navigate to the project folder and start the AI!
cd ~/project && ./opencode_isolation.sh

Scenario B: Saving Your Progress (Checkpoint)

Before you ask the AI to do a massive, complicated refactor, save your container! If the AI ruins the code, you can easily go back.

# On your main computer:
distrobox stop oc-260216
podman container commit oc-260216 localhost/oc-260216:latest

# Now you can enter again and safely let the AI work
distrobox enter oc-260216

Scenario C: Oh no! The AI broke everything! (Restoring a Checkpoint)

If you saved a checkpoint (like in Scenario B) and want to go back to it:

# On your main computer:
# 1. Delete the ruined sandbox
distrobox rm oc-260217 && rm -rf ~/sandbox-homes/oc-260217

# 2. Recreate it from your last good save point!
mkdir -p ~/sandbox-homes/oc-260217
distrobox create --name oc-260217 --image localhost/oc-260216:latest --home ~/sandbox-homes/oc-260217

5. Cleaning Up

Over time, these sandboxes will take up hard drive space. Here is how to clean them up when you are done with a project.

# See all your saved templates/images
podman image ls              

# Delete a specific saved image
podman image rm localhost/oc-260216:latest

# Delete a working sandbox and its fake home folder
distrobox rm oc-260216 && rm -rf ~/sandbox-homes/oc-260216

6. What is actually protected? (Isolation Coverage)

For transparency, here is exactly what this setup protects against:

System Area	Is it Protected?	Explanation
Your Personal Files	✅ Yes	The AI uses the fake `--home` folder and cannot see your real Documents or Desktop.
System Apps/Packages	✅ Yes	If the AI tries to install a virus via `apt-get`, it only installs inside the disposable sandbox.
Host Filesystem	⚠️ Partial	By default, the rest of your hard drive is readable. Advanced users can add `--additional-flags` to lock this down further.
Network/Internet	❌ No	The AI shares your computer's internet connection (it needs this to access the OpenCode API).

7. Common Beginner Issues (Troubleshooting)

"I get cgroup warnings when starting a container!"
- Fix: Ignore it! This is perfectly normal for sandboxes running without administrator privileges. The container will still work fine.
"My distrobox create command failed silently."
- Fix: Make sure you run the mkdir command to create the fake home folder before running distrobox create. If the folder doesn't exist, the creation will fail.
"Inside the container, where is my script?"
- Fix: Because we use a fake home, the $HOME variable points to ~/sandbox-homes/oc-base. Always use exact, absolute paths if your scripts seem to be getting lost.