🐳 Docker Sandbox Guide

The Docker Sandbox is the gold standard for safely executing AI-generated code within HelseCLI. It ensures that the AI can't accidentally damage your host system.

⚙️ Prerequisites

• Docker Desktop (Windows/Mac) or Docker Engine (Linux) must be installed and running.
• Your user must have permissions to run docker commands without sudo (on Linux).

🚀 Configuration

Enable the Docker sandbox in your .env file:

HELSE_SANDBOX_TYPE=docker

🏗️ How it Works

1. Initialization: When HelseCLI starts, it checks for the existence of the helse-sandbox image. If missing, it will pull or build it.
2. Mounting: HelseCLI mounts your current project directory as a read-only or read-write volume inside the container (depending on the task).
3. Execution: The code is sent to the container, executed in a clean environment, and the output is streamed back to your terminal.
4. Cleanup: After the task is done, the container is stopped and removed (unless configured otherwise).

🛠️ Customizing the Environment

You can provide your own Dockerfile to add custom libraries or system dependencies to the sandbox.

Create a sandbox.Dockerfile in your root:

FROM python:3.11-slim
RUN apt-get update && apt-get install -y git curl
COPY requirements.txt .
RUN pip install -r requirements.txt

HelseCLI will detect this file and build a custom sandbox image for your project.

💡 Why Use Docker?

• Isolation: Prevent scripts from accessing your SSH keys, env files (outside the project), or system binaries.
• Reproducibility: Ensure the code runs the same way for you as it would for another developer.
• Library Management: Install complex dependencies like numpy or torch without cluttering your host machine.

🛡️ Troubleshooting

• "Docker not found": Ensure Docker Desktop is running.
• Permission Denied: Run sudo usermod -aG docker $USER (Linux) and restart your session.
• Slow Startup: The first time you use a specific image, it may take a minute to pull. Subsequent runs will be near-instant.