Vagrant Claude Sandbox

A Vagrant plugin for running Claude Code in an isolated sandbox environment.

• Fast container-based sandbox using Docker
• Ubuntu 24.04 LTS with Node.js and git pre-installed
• Automatic Claude Code CLI installation
• Synced workspace folder and Claude config (plugins and skills work automatically)
• Customizable resources (memory, CPUs)
• Optional VirtualBox provider for full VM isolation

• Vagrant >= 2.2.0
• Docker (default provider)

vagrant plugin install vagrant-claude-sandbox

Create a Vagrantfile:

Vagrant.configure("2") do |config|
  config.claude_sandbox.apply_to!(config)
end

Start the sandbox:

vagrant up
vagrant claude  # Launch Claude CLI with Chrome integration

Access a normal shell:

vagrant ssh  # Regular shell session

Vagrant.configure("2") do |config|
  config.claude_sandbox.apply_to!(config) do |sandbox|
    sandbox.memory = 8192
    sandbox.cpus = 4
    sandbox.additional_packages = ["vim", "htop"]
  end
end

Mount additional directories using Vagrant's synced_folder directive:

Vagrant.configure("2") do |config|
  config.claude_sandbox.apply_to!(config) do |sandbox|
    sandbox.memory = 8192
    sandbox.cpus = 4
  end

  config.vm.synced_folder "~/Projects/my-project", "/my-project"
end

Note: The workspace (/agent-workspace) and Claude config (~/.claude/) are mounted automatically.

For full VM isolation or Docker-in-Docker capabilities:

Vagrant.configure("2") do |config|
  config.claude_sandbox.provider = "virtualbox"
  config.claude_sandbox.apply_to!(config)
end

When to use VirtualBox:

• You need Docker available inside the sandbox
• You need full VM isolation (kernel-level)
• You're running on a system without Docker

Prerequisites:

• VirtualBox >= 6.1

By default, the plugin uses Ubuntu's official mirror (http://ports.ubuntu.com/ubuntu-ports). If package updates are slow in your region, you can configure a faster mirror:

Vagrant.configure("2") do |config|
  # Choose a mirror close to your location for faster updates
  config.claude_sandbox.ubuntu_mirror = "http://ftp.jaist.ac.jp/pub/Linux/ubuntu-ports"  # Japan
  config.claude_sandbox.apply_to!(config)
end

Trusted mirrors for ARM (ubuntu-ports):

• Official Ubuntu: http://ports.ubuntu.com/ubuntu-ports (default, safest)
• JAIST (Japan): http://ftp.jaist.ac.jp/pub/Linux/ubuntu-ports (university mirror)
• Kakao (Korea): http://mirror.kakao.com/ubuntu-ports (major tech company)

Security note: Only use mirrors from trusted sources. The official Ubuntu mirror is always the safest option.

The plugin automatically starts a notification server when you run vagrant up, enabling desktop notifications from Claude running in the sandbox.

Setup:

1. Install notification support on your OS:

   • macOS: brew install terminal-notifier
   • Linux: apt install libnotify-bin (untested)

2. The notification server starts automatically with vagrant up and stops with vagrant halt or vagrant destroy.

Customization:

By default, notifications appear when Claude completes tasks, needs input, or encounters errors/warnings.

To customize notification behavior, copy the example config:

cp lib/vagrant-claude-sandbox/notification_config.yml.example ~/.vagrant-claude-sandbox/notification_config.yml

Then edit ~/.vagrant-claude-sandbox/notification_config.yml to configure which notification types to show, timeouts, sounds, etc.

Manual Control:

If needed, you can manually run the notification server:

bundle exec bin/vagrant-notify-server

The project includes comprehensive unit and integration tests:

# Install development dependencies
bundle install

# Run unit tests
bundle exec rake spec

# Run integration tests
./test-plugin.sh docker --skip-extended  # Quick test

# Run all tests
bundle exec rake test

See TESTING.md for detailed testing instructions.

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass: bundle exec rake test
5. Submit a pull request

This is now handled automatically by the plugin!

The plugin automatically detects and fixes PATH conflicts that could cause "Permission denied" errors with the Docker provider. If you have a directory named docker in your PATH before the actual Docker executable, the plugin will reorder your PATH to prioritize common Docker binary locations.

You should see a message during vagrant up if a conflict was detected and fixed:

Detected Docker PATH conflict - automatically reordered PATH

If you're still experiencing issues, you can manually fix the PATH as a fallback:

PATH=/usr/local/bin:$PATH vagrant up

Original idea by @emilburzo - blog post

MIT License - see LICENSE