Jump to content

Opencode isolation and burner workflow 260216: Difference between revisions

From Game in the Brain Wiki
← Older edit
VisualWikitext
Add HOST/DISTROBOX labels, remove BoxBuddy, expand golden image and cloning sections
No edit summary
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
= OpenCode "Burner" Workflow & Hardware Reality Check =


This guide establishes a '''Distrobox-based isolation workflow''' for running OpenCode. This prevents AI agents from accidentally modifying your host system files and allows you to "nuke" the environment if it gets corrupted or compromised.
= 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.


== Command Context ==
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.


Every command in this guide is prefixed with where it must be run:
== 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 <code>Documents</code> or <code>Desktop</code> 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:
{| class="wikitable"
{| class="wikitable"
!Your GPU VRAM
!Example Graphics Card
!Context Window (Memory)
!What this means for you
|-
|-
! Prefix !! Meaning
|'''8GB'''
|Radeon RX 7600
|8k–16k
|Good for small scripts, but might crash on large projects.
|-
|-
| <code>'''[HOST]'''</code> || Run this in a terminal on your normal Linux desktop, outside any container
|'''16GB'''
|Radeon RX 9070 XT
|~32k
|The minimum recommended for a smooth AI agent experience.
|-
|-
| <code>'''[DISTROBOX]'''</code> || Run this inside the Distrobox container after entering it
|'''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).''


== Part 1: The "Burner" Philosophy ==
== 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.


'''The Goal:''' Run OpenCode in a disposable container (<code>opencode-burner</code>) that shares ''only'' specific project folders, not your entire home directory.
=== 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:
<code># 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</code>            


'''Simpler than Claude Code:'''
=== Step 2.2: Create the Base Sandbox ===
This workflow is significantly more streamlined than typical Claude Code isolation setups. We rely on '''Distrobox Custom Homes''' instead of Firejail for stability.
Now we create a brand new, empty sandbox named <code>oc-base</code>. We also tell it to use a fake home directory (<code>~/sandbox-homes/oc-base</code>) so it can't see your real personal files.
<code># 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</code>


'''No Re-Authentication Loop:''' Unlike Claude, which often forces you to re-login via browser or copy keys every session, this container '''persists''' your "Burner Identity" (Git credentials & Configs).
=== 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).
<code># Download and install Node.js, Git, and Python
curl -fsSL <nowiki>[https://deb.nodesource.com/setup_lts.x]</nowiki>(<nowiki>https://deb.nodesource.com/setup_lts.x</nowiki>) | 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</code> 


'''Zero Boot Time:''' Distrobox shares your host kernel. There is no VM overhead; it launches instantly.
=== 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 <code>opencode_isolation.sh</code>:
<code># 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</code>


'''One-Step Launch:''' You don't need to manually start a Docker daemon, attach a shell, and then run a binary. The launcher script handles the context switch automatically.
=== Step 2.5: Save the Master Sandbox ===
Now we step out of the sandbox and save it as our "Golden Image" template.
<code># 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</code> 


'''The Loop:'''
== 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.


'''Spin up''' a fresh Ubuntu container with a '''Custom Home'''.
# 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 <code>repo</code> and <code>workflow</code> permissions.
# Use ''this'' account and token when setting up git inside your sandboxes.


'''Inject''' the necessary tools (NodeJS, Git, OpenCode CLI).
== 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., <code>oc-260216</code> means OpenCode project from Feb 16, 2026).


'''Mount''' only the target project.
=== Scenario A: Starting a Brand New Project ===
We will copy the master save file to create a fresh workspace.
<code># 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</code>


'''Burn it''' (delete the container) when the project is done or the environment gets messy.
=== 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.
<code># 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</code>


== Part 2: The Hardware Reality (VRAM is the Limit) ==
=== 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:
<code># 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</code>


Running local coding agents requires massive '''Context Windows'''. Codebases are large. The standard 4k or 8k context is useless for an agent reading multiple files.
== 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.
'''The Golden Rule:''' You need at least '''32k Context''' for a usable agent.
<code># See all your saved templates/images
 
podman image ls             
=== GPU Tier List (Discrete VRAM) ===
# 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</code>


== 6. What is actually protected? (Isolation Coverage) ==
For transparency, here is exactly what this setup protects against:
{| class="wikitable"
{| class="wikitable"
! GPU Class !! VRAM !! Price (PHP) !! Practical Limit !! Verdict
!System Area
!Is it Protected?
!Explanation
|-
|-
| '''RX 7600''' || '''8 GB''' || ~₱18,000 || '''8k - 16k'''<br />''(32k Unstable)'' || '''Entry Level.'''<br />8GB is the hard floor. You can run a 7B model, but 32k context "sometimes works" and often crashes (OOM) because the OS + Model leaves almost no room for the cache.
|'''Your Personal Files'''
|✅ Yes
|The AI uses the fake <code>--home</code> folder and cannot see your real Documents or Desktop.
|-
|-
| '''RX 9070 XT''' || '''16 GB''' || ~₱50,000 || '''64k (Unstable)''' || '''The Danger Zone.'''<br />16GB is tight. You ''can'' force a '''64k context''', but it '''requires creating a custom <code>Modelfile</code>''' and is unstable. The model weights (~5GB) + OS (~4GB) leave little room for the KV cache. Expect OOM crashes.
|'''System Apps/Packages'''
|✅ Yes
|If the AI tries to install a virus via <code>apt-get</code>, it only installs inside the disposable sandbox.
|-
|-
| '''RX 7900 XT''' || '''20 GB''' || ~₱80,000 || '''64k - 80k''' || '''The Sweet Spot.'''<br />That extra 4GB VRAM is crucial. It creates enough headroom to run a quantized 7B or 14B model with a healthy 64k context window comfortably.
|'''Host Filesystem'''
|⚠️ Partial
|By default, the rest of your hard drive is readable. Advanced users can add <code>--additional-flags</code> to lock this down further.
|-
|-
| '''Workstation'''<br />(e.g., W7800/R9700) || '''32 GB''' || High || '''128k+''' || '''The AI King.'''<br />Required if you want to run full 128k context locally. 32GB VRAM allows for uncompressed cache or running larger parameters (e.g., 32B models) with decent context.
|'''Network/Internet'''
|❌ No
|The AI shares your computer's internet connection (it needs this to access the OpenCode API).
|}
|}


=== Unified Memory & Workstation Architectures (Massive Capacity, Slower Speed) ===
== 7. Common Beginner Issues (Troubleshooting) ==
 
Use these if you need to run Huge Models (70B, 405B) that won't fit on any consumer GPU.
 
'''Trade-off:''' While capacity is massive, Tokens Per Second (T/s) is significantly lower (slower generation) compared to the Discrete GPUs above due to lower memory bandwidth.
 
{| class="wikitable"
! System / Chip !! RAM (Unified) !! Est. Cost (PHP) !! Capability !! Verdict
|-
| '''AMD Ryzen AI Max+ PRO 395'''<br />''(Strix Halo)'' || '''128 GB'''<br />''(allocates ~112GB to AI)'' || '''~₱135,000'''<br />''(Framework/MiniPC)'' || '''Llama 3 70B @ Q8'''<br />'''DeepSeek V2 Lite''' || '''The Compact Beast.'''<br />Allows running 70B models comfortably. Excellent value for capacity, but slower inference than a dGPU.
|-
| '''Apple Mac Studio'''<br />''(M3/M4 Ultra)'' || '''Up to 512 GB''' || '''~₱400,000 - ₱600,000+'''<br />''(Max Config)'' || '''Llama 3 405B @ Q4'''<br />'''DeepSeek V3 671B''' || '''The Whale.'''<br />One of the few ways to run "Frontier" models locally. Extremely expensive and slower generation speeds, but unparalleled privacy for massive models.
|}
 
=== Recommended High-Context Models ===
Select the model that fits your GPU tier.
 
'''7-8 Billion Parameter Models (Best for 12GB - 16GB VRAM)'''
 
'''Qwen2.5-Coder-7B-Instruct:''' The current gold standard. Supports up to '''128k natively'''. Excellent for bug fixing and large codebase understanding on consumer hardware.
 
'''YaRN-Mistral-7b-64k:''' Specifically configured for '''64k context''' using the YaRN extension method. Benchmarks show stable perplexity at long lengths.
 
'''OpenCodeReasoning-Nemotron-7B:''' Supports '''64k context'''. Excels specifically at reasoning tasks for code generation.
 
'''14-16 Billion Parameter Models (Best for 20GB - 24GB VRAM)'''
 
'''Qwen2.5-Coder-14B-Instruct:''' The heavy hitter. Supports '''128k natively'''. Provides significantly more capacity for complex, multi-file project analysis and agentic workflows than the 7B version.
 
'''DeepCoder-14B-Preview:''' Supports '''64k context'''. Uses reinforcement learning to achieve performance comparable to much larger proprietary models.
 
=== The "DeepSeek V3" Alternative ===
Before spending ₱80k on hardware, consider the '''DeepSeek API'''.
 
'''Context:''' 64k (Output) / 128k (Input) natively.
 
'''Intelligence:''' DeepSeek V3 (671B MoE) is vastly smarter than any local Qwen 7B/14B.
 
'''Cost:''' ~₱7.80 ($0.14) per '''1 Million''' tokens.
 
'''Strategy:''' Use '''Local 7B''' for small, private edits. Use '''DeepSeek V3''' for "Build" agent tasks requiring long context.
 
== Part 3: GitHub Burner Identity ==
 
Agents need to pull/push code. Do not give them your main GitHub credentials (SSH keys) that have access to your private company/client repos.
 
'''The Strategy:'''
 
Start by testing with your main account (carefully) to verify the tool works.
 
'''IMMEDIATELY''' switch to a Burner GitHub Account for daily agentic work.
 
'''Generating a Token (PAT):'''
You cannot use a simple password for Git over HTTPS. You need a Personal Access Token.
 
Log in to your '''Burner GitHub Account'''.
 
Click your '''Profile Picture''' (top right) → '''Settings'''.
 
Scroll to the very bottom left sidebar → '''Developer settings'''.
 
Click '''Personal access tokens''' → '''Tokens (classic)'''.
 
Click '''Generate new token (classic)'''.
 
#* ''Note:'' You may be asked for 2FA or Email authentication.
 
'''Scopes:''' Select <code>repo</code> (Full control of private repositories) and <code>workflow</code>.
 
'''Expiration:''' Set to '''90 days'''. (This is fine; we want these to expire so we don't leave loose ends).
 
'''Copy the token immediately.''' You will not see it again.
 
'''Inside the Burner Container:'''
When OpenCode asks for Git authentication, use your Burner Username and paste this Token as the password.
 
== Part 4: Setup Instructions ==
 
=== Step 1: Install Distrobox ===
 
'''[HOST]'''
 
<syntaxhighlight lang="bash">
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh
</syntaxhighlight>
 
=== Step 2: Create the Burner Container ===
 
'''[HOST]'''
 
We create a container with a '''custom home directory'''. This is the key isolation step.
 
On your host, this folder will be <code>~/opencode_burner_data</code>.
 
Inside the container, this folder will be seen as <code>/home/username</code>.
 
The AI '''cannot''' see your real SSH keys or Documents because they literally do not exist in this folder.
 
<syntaxhighlight lang="bash">
# Create the storage folder on your host first
mkdir -p ~/opencode_burner_data
 
# Create the container mapped to this folder
distrobox create --name opencode-burner --image ubuntu:24.04 --home ~/opencode_burner_data
</syntaxhighlight>
 
=== Step 3: Enter the Container ===
 
'''[HOST]''' Run this to step inside. Your prompt will change.
 
<syntaxhighlight lang="bash">
distrobox enter opencode-burner
</syntaxhighlight>
 
=== Step 4: Install Dependencies ===
 
'''[DISTROBOX]'''
 
<syntaxhighlight lang="bash">
sudo apt update && sudo apt install -y nodejs npm git build-essential python3
</syntaxhighlight>
 
=== Step 5: Install OpenCode ===
 
'''[DISTROBOX]'''
 
<syntaxhighlight lang="bash">
sudo npm install -g opencode-ai
</syntaxhighlight>
 
=== Step 6: Configure OpenCode ===
 
'''[DISTROBOX]'''
 
<syntaxhighlight lang="bash">
mkdir -p ~/.config/opencode
nano ~/.config/opencode/opencode.json
</syntaxhighlight>
 
'''Nano Shortcuts to Clear File:'''
If the file already has content, use this sequence to clear it quickly:
 
<code>Alt</code> + <code>＼</code> : Go to the very first line (Top).
 
<code>Alt</code> + <code>A</code> : 'Mark' the text (Start selection).
 
<code>Alt</code> + <code>/</code> : Go to the very last line (End).
 
<code>Ctrl</code> + <code>K</code> : Cut/Remove the selected text.
 
'''Paste the Configuration:'''
 
<syntaxhighlight lang="json">
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama Local",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      },
      "models": {
        "qwen2.5-coder:7b": { "name": "Qwen 2.5 Coder (7B)" }
      }
    },
    "deepseek": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DeepSeek API",
      "options": {
        "baseURL": "https://api.deepseek.com/v1",
        "apiKey": "sk-YOUR_API_KEY"
      },
      "models": {
        "deepseek-chat": { "name": "DeepSeek V3 (Fast & Smart)" },
        "deepseek-reasoner": { "name": "DeepSeek R1 (Thinking Model)" }
      }
    }
  }
}
</syntaxhighlight>
 
'''Save and Exit:''' <code>Ctrl+O</code> → Enter → <code>Ctrl+X</code>
 
=== Step 7: Create Workspace ===
 
'''[DISTROBOX]'''
 
<syntaxhighlight lang="bash">
mkdir -p ~/opencode_workspace
cd ~/opencode_workspace
</syntaxhighlight>
 
=== Step 8: Launch OpenCode ===
 
'''[DISTROBOX]'''
 
Because we isolated the entire home directory in Step 2, we don't need complex Firejail commands. The AI is already in a padded cell.
 
<syntaxhighlight lang="bash">
opencode
</syntaxhighlight>
 
=== Step 9: Save as a Golden Image ===
 
Once the container is fully configured, save it as a reusable '''golden image''' so future sessions start pre-installed without repeating Steps 4–7.
 
'''[DISTROBOX]''' Exit the container first:
 
<syntaxhighlight lang="bash">
exit
</syntaxhighlight>
 
Your prompt should return to the host (e.g., <code>justin@hostname</code>).
 
'''[HOST]''' Stop the container:
 
<syntaxhighlight lang="bash">
distrobox stop opencode-burner
</syntaxhighlight>
 
'''[HOST]''' Commit the container state to a named Podman image:
 
<syntaxhighlight lang="bash">
podman commit opencode-burner localhost/opencode-golden:latest
</syntaxhighlight>
 
'''[HOST]''' Verify the image was created:
 
<syntaxhighlight lang="bash">
podman image ls | grep opencode-golden
</syntaxhighlight>
 
You should see output like:
 
<pre>
localhost/opencode-golden  latest  a1b2c3d4e5f6  2 minutes ago  1.1 GB
</pre>
 
== Part 5: Starting Sessions from the Golden Image ==
 
Each new working session creates a throwaway container from the golden image. When the session ends, delete the container — leaving no trace.
 
=== Single Session ===
 
'''[HOST]''' Create a new session container:
 
<syntaxhighlight lang="bash">
mkdir -p ~/opencode_burner_data_session1
distrobox create --name opencode-session-1 --image localhost/opencode-golden:latest --home ~/opencode_burner_data_session1
</syntaxhighlight>
 
'''[HOST]''' Enter it:
 
<syntaxhighlight lang="bash">
distrobox enter opencode-session-1
</syntaxhighlight>
 
'''[DISTROBOX]''' Start working immediately — everything is pre-installed:
 
<syntaxhighlight lang="bash">
cd ~/opencode_workspace
opencode
</syntaxhighlight>
 
'''[HOST]''' When the session is done, delete the container and its data:
 
<syntaxhighlight lang="bash">
distrobox rm opencode-session-1
rm -rf ~/opencode_burner_data_session1
</syntaxhighlight>
 
=== Multiple Parallel Sessions (Cloning) ===
 
Run several independent sessions at the same time from the same golden image:
 
'''[HOST]'''
 
<syntaxhighlight lang="bash">
mkdir -p ~/opencode_burner_data_{A,B,C}
 
distrobox create --name opencode-session-A --image localhost/opencode-golden:latest --home ~/opencode_burner_data_A
distrobox create --name opencode-session-B --image localhost/opencode-golden:latest --home ~/opencode_burner_data_B
distrobox create --name opencode-session-C --image localhost/opencode-golden:latest --home ~/opencode_burner_data_C
</syntaxhighlight>
 
Each container is completely independent. Changes in session A do not affect B or C.
 
'''[HOST]''' List all containers:
 
<syntaxhighlight lang="bash">
distrobox list
</syntaxhighlight>
 
'''[HOST]''' Clean up all sessions when done:
 
<syntaxhighlight lang="bash">
distrobox rm opencode-session-A opencode-session-B opencode-session-C
rm -rf ~/opencode_burner_data_{A,B,C}
</syntaxhighlight>
 
=== Updating the Golden Image ===
 
'''[HOST]''' Create a temporary update container:
 
<syntaxhighlight lang="bash">
distrobox create --name opencode-update --image localhost/opencode-golden:latest
distrobox enter opencode-update
</syntaxhighlight>
 
'''[DISTROBOX]''' Make your changes:
 
<syntaxhighlight lang="bash">
sudo npm update -g opencode-ai
</syntaxhighlight>
 
'''[DISTROBOX]''' Exit:
 
<syntaxhighlight lang="bash">
exit
</syntaxhighlight>
 
'''[HOST]''' Commit and clean up:
 
<syntaxhighlight lang="bash">
distrobox stop opencode-update
podman commit opencode-update localhost/opencode-golden:latest
distrobox rm opencode-update
</syntaxhighlight>
 
== Part 6: Automated Launcher (Optional) ==
 
If you get tired of typing <code>distrobox enter</code> every time, you can use the <code>launch_burner.sh</code> script (provided separately) from your '''[HOST]''' terminal. It handles the context switching automatically.
 
== Troubleshooting ==
 
=== "Failed to mount /sys" or Immediate Exit ===
If you try to run Firejail inside Distrobox, you may see:
 
<pre>
Warning: failed to mount /sys
Child process initialized in 91.91 ms
(Prompt returns immediately)
</pre>
 
'''Cause:''' This is a "Nest Isolation" conflict. Firejail is trying to create a sandbox inside a container that has already virtualized the system files.
'''Fix:''' Use the <code>--home</code> custom directory method (Part 4, Step 2). This creates a container where the ''entire'' home directory is separate, so you don't need Firejail to protect your files—they simply aren't there.
 
=== "WARN: failed to kill all processes / cgroup not exist" ===
When stopping a container, you may see this warning:
 
<pre>
WARN[0000] failed to kill all processes... error="cgroup not exist"
opencode-burner
</pre>
 
'''Verdict:''' It worked. This is a common warning in rootless containers where Distrobox cannot access system-level cgroups to force-kill background processes. The container name printed on the last line confirms it stopped successfully.
 
== See Also ==


* [[Claude_Code_Isolation_and_Burner_Workflow_260211]] — Claude Code version of this workflow with Firejail
* '''"I get cgroup warnings when starting a container!"'''
* [[Creating_a_Distrobox_from_a_Golden_Image]] — Detailed golden image reference
** ''Fix:'' Ignore it! This is perfectly normal for sandboxes running without administrator privileges. The container will still work fine.
* '''"My <code>distrobox create</code> command failed silently."'''
** ''Fix:'' Make sure you run the <code>mkdir</code> command to create the fake home folder ''before'' running <code>distrobox create</code>. 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 <code>$HOME</code> variable points to <code>~/sandbox-homes/oc-base</code>. Always use exact, absolute paths if your scripts seem to be getting lost.

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.

  1. Go to GitHub and create a completely new, separate account (a "burner" account).
  2. Generate a Personal Access Token for this new account.
  3. Set the token to expire in 90 days.
  4. Only give the token repo and workflow permissions.
  5. 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.
Retrieved from "http://wiki.gi7b.org/index.php?title=Opencode_isolation_and_burner_workflow_260216&oldid=198"