Justinaquino at 04:13, 9 March 2026

2026-03-09T04:13:35Z

← Older revision		Revision as of 04:13, 9 March 2026
Line 227:		Line 227:
	* '''"Inside the container, where is my script?"'''		* '''"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.		** ''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.


			== Step 1: Open Your Terminal ==
			Open your preferred terminal application on your system (Terminal on macOS/Linux, or WSL/Git Bash on Windows).

			== Step 2: Ensure the Configuration Directory Exists ==
			Before creating or editing the file, make sure the <code>opencode</code> folder exists inside your <code>~/.config</code> directory. Run this command:

			Bash<syntaxhighlight lang="bash">
			mkdir -p ~/.config/opencode
			</syntaxhighlight>

			== Step 3: Open the Configuration File in a Text Editor ==
			You can use any terminal text editor you are comfortable with (like <code>nano</code> or <code>vim</code>), or a visual editor like VS Code. To use <code>nano</code>, type:

			Bash<syntaxhighlight lang="bash">
			nano ~/.config/opencode/opencode.json
			</syntaxhighlight>

			== Step 4: Paste Your Sanitized Configuration ==
			Copy the code block below. It contains your exact configuration, but the sensitive API keys have been safely swapped out for <code>YOUR_OPENCODE_API_KEY_HERE</code> and <code>YOUR_DEEPSEEK_API_KEY_HERE</code>.

			JSON<syntaxhighlight lang="json">
			{
			"$schema": "https://opencode.ai/config.json",
			"provider": {
			"opencode": {
			"name": "OpenCode AI",
			"options": {
			"apiKey": "YOUR_OPENCODE_API_KEY_HERE"
			}
			},
			"ollama": {
			"npm": "@ai-sdk/openai-compatible",
			"name": "Ollama Local",
			"options": {
			"baseURL": "http://127.0.0.1:11434/v1"
			},
			"models": {
			"hf.co/Qwen/Qwen2.5-Coder-7B-Instruct-GGUF:latest": {
			"name": "Qwen 2.5 Coder (7B) - High Precision Coding"
			},
			"granite4:latest": {
			"name": "IBM Granite 4 - Enterprise General Purpose"
			},
			"hf.co/bartowski/Qwen2.5-3B-Instruct-GGUF:Q4_K_M": {
			"name": "Qwen 2.5 Instruct (3B) - Fast Chat & Reasoning"
			},
			"qwen2.5-3b-32k:latest": {
			"name": "Qwen 2.5 (3B) - Long Context (32k)"
			},
			"qwen2.5:14b": {
			"name": "Qwen 2.5 (14B) - Heavyweight Reasoning"
			},
			"llama3.2:latest": {
			"name": "Llama 3.2 (3B) - Meta Generalist"
			},
			"llama3.2:3b": {
			"name": "Llama 3.2 (3B) - Meta Generalist (Alt Tag)"
			},
			"qwen3:0.6b": {
			"name": "Qwen 3 (0.6B) - Tiny/Fast Helper"
			},
			"qwen3-vl:2b": {
			"name": "Qwen 3 Vision (2B) - Multi-modal/Images"
			},
			"granite3.3:2b": {
			"name": "IBM Granite 3.3 (2B) - Lightweight/Efficient"
			},
			"grammar-check:latest": {
			"name": "Utility: Grammar & Style Correction"
			}
			}
			},
			"deepseek": {
			"npm": "@ai-sdk/openai-compatible",
			"name": "DeepSeek API",
			"options": {
			"baseURL": "https://api.deepseek.com/v1",
			"apiKey": "YOUR_DEEPSEEK_API_KEY_HERE"
			},
			"models": {
			"deepseek-chat": {
			"name": "DeepSeek V3 (Fast & Smart)"
			},
			"deepseek-reasoner": {
			"name": "DeepSeek R1 (Thinking Model)"
			}
			}
			}
			}
			}
			</syntaxhighlight>

			== Step 5: Replace Placeholders and Save ==

			* Replace <code>"YOUR_OPENCODE_API_KEY_HERE"</code> and <code>"YOUR_DEEPSEEK_API_KEY_HERE"</code> with your newly rotated, secure API keys.
			* If using <code>nano</code>, press '''Ctrl + O''', hit '''Enter''' to save, and then press '''Ctrl + X''' to exit.
			* Restart OpenCode so it can read the updated configuration file.

Justinaquino: Imported from gi7b wiki

2026-03-06T10:07:26Z

Imported from gi7b wiki

New page

= 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 <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"
!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:<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

=== Step 2.2: Create the Base Sandbox ===
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. <syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

=== 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).<syntaxhighlight lang="bash">
# Download and install Node.js, Git, and Python
curl -fsSL 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
</syntaxhighlight>

=== 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>:<syntaxhighlight lang="bash">
#in the Distrobox Container
mkdir -p ~/project
cd ~/project
</syntaxhighlight>Create the activation Script in the /project directory<syntaxhighlight lang="bash">
nano opencode_isolation.sh
</syntaxhighlight>Copy paste this code<syntaxhighlight lang="sh">
#!/bin/bash
# =============================================================================
# opencode_isolation.sh
# Launcher script for OpenCode inside a Distrobox container.
#
# Place this script strictly inside your project workspace folder.
# It will lock the AI's context to the folder it is launched from.
# =============================================================================

# 1. Find the exact folder this script is currently sitting in
WORK_DIR="$(cd "$(dirname "$0")" && pwd)"

# 2. Lock the terminal to this directory
cd "$WORK_DIR"

# 3. Print a security check to the screen
echo "Starting OpenCode Burner Session..."
echo "Locked to working directory: $WORK_DIR"
echo "Host isolation layer: Active via Distrobox --home"
echo "------------------------------------------------"

# 4. Launch OpenCode, replacing this bash process cleanly
exec opencode "$@"
</syntaxhighlight>Give permission to run it<syntaxhighlight lang="bash">
chmod +x opencode_isolation.sh
</syntaxhighlight>

=== Step 2.5: Save the Master Sandbox ===
Now we step out of the sandbox and save it as our "Golden Image" template.<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

== 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 <code>repo</code> and <code>workflow</code> 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., <code>oc-260216</code> 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.<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

=== 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.<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

=== 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:<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

== 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.<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

== 6. What is actually protected? (Isolation Coverage) ==
For transparency, here is exactly what this setup protects against:
{| class="wikitable"
!System Area
!Is it Protected?
!Explanation
|-
|'''Your Personal Files'''
|✅ Yes
|The AI uses the fake <code>--home</code> folder and cannot see your real Documents or Desktop.
|-
|'''System Apps/Packages'''
|✅ Yes
|If the AI tries to install a virus via <code>apt-get</code>, it only installs inside the disposable sandbox.
|-
|'''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.
|-
|'''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 <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.

Opencode isolation and burner workflow 260216 - Revision history

Justinaquino at 04:13, 9 March 2026

Justinaquino: Imported from gi7b wiki