🛡️ ShadowBox

Fearless Coding. Isolated Environments. One-Click Revert.

中文文档 | English

ShadowBox allows you to create instant, isolated, and disposable development environments ("Shadow Sessions") right inside VS Code. It uses Docker to sandbox your workspace, letting you experiment ("Vibe Code") without fear of breaking your local setup or installing messy global dependencies.

✨ Features

• 🔒 Total Isolation: Runs your workspace inside a Docker container.
• ⚡ Instant Sync: Files are bind-mounted for real-time editing, but changes are tracked.
• 🗑️ Disposable Sessions:
  • Discard $(trash): Experiment went wrong? One click to revert all file changes to their pre-session state.
  • Apply $(rocket): Success? One click to merge changes back to your real workspace.
• 🐳 Native Terminal Integration: Uses VS Code's native terminal connected directly to the container (docker exec).
• 🤖 Copilot Context: Copy optimized context prompts for AI coding with one click.

�️ Security & Isolation Model

ShadowBox differs from Dev Containers by focusing on lightweight, instant isolation:

• Extensions run on Host: Your VS Code extensions (like Copilot) run locally, keeping your theme/settings intact.
• Side Effects are Sandboxed:
  • File Edits: All changes are tracked. Session discard reverts files instantly.
  • Terminal Commands: The provided terminal is a docker exec session. Commands run by you or Copilot (via "Run in Terminal") execute inside the container, protecting your host OS.

Note: Always ensure Copilot sends commands to the ShadowBox Container terminal.

�🚀 Getting Started

Prerequisites

1. Docker: Ensure Docker Desktop or Docker Engine is installed and running.
2. VS Code: Version 1.96.0 or higher.

Usage Guide

1. Open your Project: Open any folder in VS Code.
2. Open ShadowBox: Click the ShadowBox icon (double-box symbol) in the Activity Bar.
3. Start a Session:
   • Click the Start Session $(beaker) button.
   • ShadowBox will automatically detect your language (Node, Python, Go, etc.) and launch a container.
   • VS Code will reload into Shadow Mode.
4. Experiment:
   • You are now in a container. The terminal is root in the container.
   • Install packages, run scripts, delete files — your host OS is untouched.
   • Tip: The Status Bar will turn Orange and show ShadowBox: Isolated.
5. Finish:
   • Apply Changes $(rocket): Keep what you built. Files are preserved.
   • Discard Session $(trash): DANGER ZONE (Safe). The container is destroyed, and your folder is reverted to exactly how it was before.

⚙️ Configuration

ShadowBox offers a hierarchical configuration system:

1. Docker Images

You can configure which Docker image to use for your session. ShadowBox resolves the image in this order:

1. Project Override (Highest): shadowbox.image in your workspace settings (.vscode/settings.json).
2. Language Defaults: Detects package.json (Node), requirements.txt (Python), etc., and uses the image mapped in shadowbox.languageImages.
3. Global Fallback: Uses shadowbox.defaultImage (Default: ubuntu:latest).

UI Access: Click on "Image: ..." or "Global Language Defaults" in the ShadowBox Sidebar to configure.

2. Ignored Files

Safety is key. You can prevent certain files from being monitored or synced.

• Auto-Inherit: .gitignore is always respected.
• Custom Config: Add extra patterns via the sidebar's "Ignored Files" menu.
• Core Protection: .git and .shadowbox_metadata.json are always protected.

🤖 AI Context

ShadowBox is designed for "Vibe Coding" with AI.

• Click Copy AI Context $(hubot) in the sidebar.
• Paste the prompt into Copilot/ChatGPT. It explains that the AI has full permission to run destructive commands because it is in a safe container.

⚠️ Notes

• Data Safety: "Discard" permanently reverts files to their pre-session state.
• Performance: Large projects may take a few seconds to initialize the safety backup.

License: MIT Publisher: LeeXN