OpenCode Sandbox Script

This bash script launches OpenCode within a sandbox environment using bubblewrap (bwrap), providing secure isolated execution.

What It Does

The script creates a minimal, secure sandbox by:

• Using bubblewrap to unshare all resources (processes, network, etc.)
• Setting up a restricted filesystem with only necessary read-write directories
• Mounting workspace directories for OpenCode project access
• Preserving user configuration and cache directories

Key Features

• Security: Runs OpenCode in an isolated environment
• Flexibility: Supports custom workspace directory bindings
• Persistence: Maintains user cache and configuration
• Simplicity: Single executable script with minimal configuration

Usage

Make the script executable and run it:

chmod +x opencode-sandbox
./opencode-sandbox

Special flags and arguments:

./opencode-sandbox --local-override
./opencode-sandbox your-project-args
./opencode-sandbox --help

The --local-override flag creates a symlink to ~/.local/bin/opencode that overrides the original binary. This is useful if you want to use this sandbox script as your primary opencode command.

Pass other arguments after the script to OpenCode:

./opencode-sandbox your-project-args

Environment Variables

OPENCODE_WORKSPACE_PATHS

Adds additional workspace directories to be mounted inside the sandbox.

Default: Empty (no additional directories)

Format: Colon-separated list of paths

Example:

# Mount multiple additional directories
export OPENCODE_WORKSPACE_PATHS="~/projects:/workspace:/home/user/docs"

# Or set directly with the script
OPENCODE_WORKSPACE_PATHS="~/projects:/workspace" ./opencode-sandbox

How it works:

1. The environment variable value is parsed for paths
2. Each path is checked to ensure it exists and is a directory
3. Valid directories are mounted read-write inside the sandbox
4. The current working directory is always included

Use cases:

• Access to multiple project directories
• Mount custom workspace locations
• Add shared directories for file operations

OPENCODE_WORKSPACE_READ_PATHS

Adds additional workspace directories to be mounted inside the sandbox as read-only.

Default: Empty (no additional directories)

Format: Colon-separated list of paths

Example:

# Mount multiple additional directories as read-only
export OPENCODE_WORKSPACE_READ_PATHS="/usr/local/lib:/opt/shared:/home/user/reference"

# Or set directly with the script
OPENCODE_WORKSPACE_READ_PATHS="/usr/local/lib:/opt/shared" ./opencode-sandbox

How it works:

1. The environment variable value is parsed for paths
2. Each path is checked to ensure it exists and is a directory
3. Valid directories are mounted read-only inside the sandbox
4. Non-existent or invalid paths are silently ignored

Use cases:

• Access reference data without risk of modification
• Mount shared libraries or dependencies
• Provide read-only access to system-wide resources
• Protect critical directories from accidental writes

OPENCODE_BINARY_PATH

Controls the location of the OpenCode binary to execute in normal mode (not when using --local-override).

Default: /usr/bin/opencode

Example:

export OPENCODE_BINARY_PATH="/usr/local/bin/opencode"
cd my-project
./opencode-sandbox  # Uses custom binary

Script Features

The script follows a modular approach:

1. Check for project config (.opencode-sandbox file)
2. Argument parsing for special flags
3. Local override setup (~/.local/bin/opencode symlink)
4. Workspace configuration (from environment variables)
5. Execute OpenCode: Launch the application in sandbox

--local-override Feature

The --local-override flag changes how the script behaves:

• Creates a symlink at ~/.local/bin/opencode pointing to this script
• Skips bubblewrap sandbox execution
• Makes this script the primary opencode command available system-wide
• Removes the --local-override flag from arguments passed to opencode

When to use:

• You want this sandbox script to be your main opencode command
• You want to bypass bubblewrap for performance
• You need consistent behavior across different environments

Example:

cd /path/to/repo
./opencode-sandbox --local-override
# Now you can run `opencode` from anywhere
opencode --help

Project Configuration File

Look for a .opencode-sandbox file in the current working directory that can be sourced to set project-specific configurations.

This file is automatically detected and sourced at the start of the script, allowing you to override environment variables and customize the script's behavior for specific projects.

Usage:

# After running the script once, you can create this file:
cd my-project
./opencode-sandbox

# Then create a configuration file for the project:
cat > .opencode-sandbox << 'EOF'
# Project-specific OpenCode sandbox configuration

# Override the binary location to a custom build
export OPENCODE_BINARY_PATH="/home/user/projects/opencode-bin"

# Add additional workspace directories specific to this project
export OPENCODE_WORKSPACE_PATHS="~/projects/data:/workspace/backups"

# Set custom cache directory
cache_dir="/tmp/custom-opencode-cache"
export XDG_CACHE_HOME="$cache_dir"
EOF

# After running the script from this directory, it will use the project config
./opencode-sandbox [your-project-args]

What can be configured:

• OPENCODE_BINARY_PATH: Custom location for the opencode binary
• OPENCODE_WORKSPACE_PATHS: Additional workspace directories (colon-separated)
• Any other environment variable used by the script
• Note: Variables set in .opencode-sandbox override command-line environment variables

Environment Variables

OPENCODE_BINARY_PATH

Controls the location of the OpenCode binary to execute in normal mode (not when using --local-override).

Default: /usr/bin/opencode

Example:

export OPENCODE_BINARY_PATH="/usr/local/bin/opencode"
cd my-project
./opencode-sandbox  # Uses custom binary

OPENCODE_WORKSPACE_PATHS

Adds additional workspace directories to be mounted inside the sandbox.

Default: Empty (no additional directories)

Format: Colon-separated list of paths

Example:

# Mount multiple additional directories
export OPENCODE_WORKSPACE_PATHS="~/projects:/workspace:/home/user/docs"

# Or set directly with the script
OPENCODE_WORKSPACE_PATHS="~/projects:/workspace" ./opencode-sandbox

How it works:

1. The environment variable value is parsed for paths
2. Each path is checked to ensure it exists and is a directory
3. Valid directories are mounted read-write inside the sandbox
4. The current working directory is always included

Use cases:

• Access to multiple project directories
• Mount custom workspace locations
• Add shared directories for file operations

Notes

• Requires bubblewrap (usually provided by the container runtime)
• Path separators must be absolute paths
• Non-existent or invalid paths in OPENCODE_WORKSPACE_PATH are silently ignored
• The sandbox always includes the current working directory