OpenCode CLI Container Wrapper

The goal of this project is to provide a standalone, containerized version of the OpenCode CLI that feels transparent to the user. It allows you to run OpenCode without polluting your host system's global npm packages, while maintaining access to your projects and persistent data.

The solution uses a "transparent wrapper" strategy with focused isolation:

1. Containerized Environment: The tool runs inside a lightweight node:20-slim container.

2. Granular Helper Script (opencode):

   • Auto-Build: Automatically builds the container image (opencode-cli) if it's missing.
   • Focused Mounting:
     • Workdir: Mounts $PWD to $PWD so you can run it anywhere.
     • Persistence: Maps Host XDG directories to specific container paths:
       • XDG_DATA_HOME/opencode -> /data
       • XDG_CACHE_HOME/opencode -> /cache
     • Clean Home: Uses the container's native /home/node as HOME to avoid permission conflicts, ensuring a stable runtime environment.
   • User Mapping: Uses --userns=keep-id (Podman) to ensure file ownership on the host remains correct (your user, not root).

3. Lifecycle Management:

   • install.sh: Deploys the wrapper to ~/.local/share/opencode-cli.
   • uninstall.sh: Removes the installation and cleans up the Docker image.

To install the wrapper permanently:

1. Run the install script:

   ./install.sh

2. Ensure ~/.local/bin is in your PATH.

Run opencode as if it were a local binary:

# Initialize OpenCode
opencode /init

# Run the agent
opencode

To remove the tool and the container image:

# Run the uninstall script from the source directory
./uninstall.sh

# OR from the install location (if installed)
~/.local/share/opencode-cli/uninstall.sh

When you run opencode:

1. It checks for the opencode-cli image.
2. If missing, it triggers a podman build using the embedded Containerfile.
3. It runs the container with:
   • HOME=/home/node (Internal container home)
   • XDG_DATA_HOME=/data (Mapped from host)
   • XDG_CACHE_HOME=/cache (Mapped from host)
   • PWD mapped nicely. This ensures user data persists across runs (server connections, history), but temporary config files generated during runtime do not clutter your host home directory.