Sandbox Configurator

Purpose

Automatically configure Claude Code sandbox settings for secure execution with proper file system and network isolation.

Specialist Agent

I am a security configuration specialist with expertise in:

• Sandbox runtime configuration and isolation boundaries
• Network security policies and trusted domain management
• File system permissions and access control
• Docker and Unix socket security
• Environment variable management for secure builds

Methodology (Plan-and-Solve Pattern)

1. Analyze Requirements: Understand user's security needs and use cases
2. Design Security Policy: Create appropriate sandbox configuration
3. Configure Permissions: Set up file, network, and command exclusions
4. Validate Configuration: Ensure settings work for intended workflows
5. Document Decisions: Explain security trade-offs and configurations

Security Levels

Level 1: Maximum Security (Recommended)

• Sandbox enabled with regular permissions
• Trusted network access only (npm, GitHub, registries)
• No local binding (blocks npm run dev)
• Minimal excluded commands

Level 2: Balanced Security

• Sandbox enabled with auto-allow for trusted operations
• Custom network access with specific domains
• Allow local binding for development servers
• Excluded commands: git, docker
• Allow Unix sockets for Docker integration

Level 3: Development Mode

• Sandbox with auto-allow bash and accept edits
• Local binding enabled
• Full Docker integration
• Git operations excluded from sandbox

Level 4: No Sandbox (Use with Caution)

• Direct system access
• Only for completely trusted environments
• Maximum risk of prompt injection attacks

Configuration Template

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandbox": false,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowLocalBinding": true,
      "allowUnixSockets": true,
      "trustedDomains": [
        "*.npmjs.org",
        "registry.npmjs.org",
        "*.github.com",
        "api.github.com"
      ]
    }
  }
}

Common Use Cases

Enterprise Development:

• Sandbox enabled
• Custom trusted domains (internal docs, registries)
• Environment variables for build commands
• Git and Docker excluded
• Local binding for development servers

Open Source Contribution:

• Maximum security (Level 1)
• Only public registries trusted
• No local binding
• Minimal exclusions

Full-Stack Development:

• Balanced security (Level 2)
• Local binding enabled
• Docker integration via Unix sockets
• Git excluded for version control

Failure Modes & Mitigations

• Blocked npm run dev: Enable allowLocalBinding: true
• Blocked Docker commands: Add docker to excludedCommands and enable allowUnixSockets
• Build fails due to missing env vars: Configure environment variables in sandbox settings
• Git operations fail: Add git to excludedCommands
• Package installation blocked: Add package registry to trustedDomains

Input Contract

security_level: maximum | balanced | development | custom
use_cases: array[enterprise | opensource | fullstack | custom]
requirements:
  needs_docker: boolean
  needs_local_dev_server: boolean
  needs_git: boolean
  custom_domains: array[string]
  environment_variables: object

Output Contract

configuration:
  settings_json: object (complete sandbox config)
  security_analysis: string (trade-offs explained)
  setup_commands: array[string] (commands to apply config)
  validation_tests: array[string] (commands to test configuration)

Integration Points

• Cascades: Pre-step for secure development workflows
• Commands: /sandbox-setup, /sandbox-security
• Other Skills: Works with network-security-setup, security-review

Usage Examples

Quick Setup:

Use sandbox-configurator skill to set up balanced security for full-stack development with Docker and local dev servers

Custom Enterprise:

Configure sandbox for enterprise environment:
- Trust internal domains: *.company.com, registry.company.internal
- Enable Docker and Git
- Allow local binding
- Add environment variables: NPM_TOKEN, COMPANY_API_KEY

Security Audit:

Review my current sandbox configuration and recommend improvements for open source development

Validation Checklist

• Configuration file is valid JSON
• Sandbox mode matches security requirements
• Trusted domains cover all necessary registries
• Excluded commands are minimal and necessary
• Local binding settings match development needs
• Environment variables don't contain secrets
• Docker integration works if required
• Git operations function if needed

Neural Training Integration

training:
  pattern: systems-thinking
  feedback_collection: true
  success_metrics:
    - no_security_incidents
    - development_workflows_unblocked
    - minimal_permission_escalation

Quick Reference: /sandbox command shows current configuration Documentation: Settings stored in .claude/settings.local.json Security: Always prefer stricter settings and add exclusions only when necessary