sanduary

A secure development sandbox environment for AI agents - providing safe, isolated workspaces for AI coding assistants like Claude Code through Docker DevContainers.

Overview

sanduary (sanctuary + sandbox) creates disposable, secure development environments where AI agents can safely execute code, install packages, and perform development tasks without affecting your host system. Each session runs in an isolated Docker container that is automatically cleaned up when you exit.

Features

• Isolated Environments: Each session runs in a dedicated Docker DevContainer
• Dynamic Configuration: Supports project-specific DevContainer overrides
• Auto-Cleanup: Containers are automatically removed after session ends
• Git Integration: Seamlessly works with your existing Git repositories
• Customizable: Extend base configuration with override files
• Vulnerability Reduction: Generate DevContainer files on-demand instead of committing to Git

Installation

Global Installation (Recommended)

Install globally to use across multiple projects:

npm install -g sanduary

This allows any team member to generate their own DevContainer configuration without tracking potentially vulnerable configuration files in Git.

Project-Local Installation

For advanced use cases, install as a project dependency:

npm install --save-dev sanduary

Then add to your package.json:

{
  "scripts": {
    "postinstall": "sdy init"
  }
}

This automatically sets up the sandbox environment when developers run npm install, providing quick DevContainer setup without committing configuration files.

Quick Start

1. Initialize DevContainer Configuration

Navigate to your project directory and initialize the DevContainer files:

cd your-project
sdy init

This creates .devcontainer/ directory with base configuration files.

Important: Add .devcontainer/ to your .gitignore to keep configuration local:

# DevContainer - generated by sanduary
.devcontainer/

2. Start the Sandbox Environment

Launch the DevContainer (default command):

sdy run
# or simply
sdy

The container will:

• Build and start automatically
• Execute any postCreateCommand and postStartCommand from devcontainer.json
• Connect you to an interactive bash session
• Clean up automatically when you exit

Commands

| Command | Description | |---------|-------------| | sdy init | Initialize DevContainer configuration files in current project | | sdy run | Start the DevContainer sandbox (default) | | sdy | Alias for sdy run |

Configuration

Base Configuration

After running sdy init, you'll have:

.devcontainer/
├── devcontainer.base.json       # Base DevContainer settings
├── devcontainer.json            # Main configuration file
├── docker-compose.yml           # Docker Compose settings
├── Dockerfile                   # Container image definition
└── templates/
    ├── devcontainer.override.template.json
    └── docker-compose.override.template.yml

Note: These files should NOT be committed to Git. Each developer generates their own configuration via sdy init.

Override Files

Customize your sandbox environment by creating override files:

DevContainer Override

Create .devcontainer/devcontainer.override.json:

{
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "postCreateCommand": "npm install"
}

Docker Compose Override

Create .devcontainer/docker-compose.override.yml:

services:
  devcontainer:
    environment:
      - NODE_ENV=development
    ports:
      - "3000:3000"
    volumes:
      - ./custom-data:/data

Configuration Files

The following files are automatically created in your home directory:

• ~/.claude-sandbox.json - General sandbox settings
• ~/.claude-sandbox-credentials.json - Authentication credentials

Git Management Best Practices

What to Commit

✅ DO commit:

• package.json (with sanduary as dependency)
• .gitignore (with .devcontainer/ excluded)
• Project source code and assets

What NOT to Commit

❌ DO NOT commit:

• .devcontainer/ directory and its contents
• devcontainer.json
• docker-compose.yml
• Dockerfile

Why?

1. Security: DevContainer configurations can contain sensitive settings or expose vulnerabilities
2. Flexibility: Each developer can customize their environment without affecting others
3. Version Control: Configuration generation is handled by sanduary versions, not Git history

Sample .gitignore

# DevContainer - generated by sanduary
.devcontainer/

# Dependency directories
node_modules/

Workflow Examples

Team Collaboration

1. Project Setup (once per project):

# Add sanduary to project
npm install --save-dev sanduary

# Update .gitignore
echo ".devcontainer/" >> .gitignore

# Commit
git add package.json .gitignore
git commit -m "feat: add sanduary for DevContainer management"

2. New Developer Setup:

# Clone project
git clone <repo-url>
cd <project>

# Install dependencies (automatically runs sdy init via postinstall)
npm install

# Start sandbox
sdy

3. Existing Developer:

# Pull latest changes
git pull

# Update dependencies if needed
npm install

# Start sandbox
sdy

Global Installation Workflow

1. One-time Setup:

# Install globally
npm install -g sanduary

2. Per-project Usage:

cd your-project

# Initialize (only needed once per project)
sdy init

# Start sandbox (anytime)
sdy

How It Works

1. Dynamic Naming: Each session gets a unique project name (sandbox-XXXX)
2. Git-Aware: Automatically detects project root via Git
3. Docker Compose: Uses Docker Compose for container orchestration
4. Lifecycle Hooks: Executes postCreateCommand and postStartCommand from DevContainer config
5. Auto-Cleanup: Containers and volumes are removed on exit via cleanup trap

Use Cases

• AI Agent Sandboxing: Safe environment for Claude Code and similar AI assistants
• Dependency Testing: Test package installations without polluting host
• Code Experimentation: Try risky changes in isolated environment
• Multi-Project Development: Switch between different project configurations easily
• Onboarding: New team members get consistent development environments instantly

Requirements

• Docker Engine
• Node.js and npm (for installation)
• Git (for project detection)
• jq (for JSON parsing)

Environment Variables

The following environment variables are automatically set during execution:

• PROJECT_ROOT: Git repository root directory
• PROJECT_NAME: Unique sandbox instance name
• GIT_ORIGIN_URL: Set to /host-project when launched via sdy

License

ISC

Links

• GitHub Repository
• Report Issues