sandboxctl

Safe, isolated sandboxes for using LLMs with minimal guardrails to maximize developer productivity.

Experimental. sandboxctl is under active development. Commands, configuration, and behavior may change between releases.

Features

• Isolated sandboxes -- each sandbox runs in its own OpenShell container with a dedicated filesystem and toolchain.
• Profile system -- define reusable sandbox configurations (repos, extensions, settings) as declarative profiles.
• Cross-platform credentials -- OS keychain integration for GitHub and GitLab tokens on macOS and Linux.
• Scoped Git tokens -- per-sandbox token injection so credentials never leak across projects.
• Health checks and auto-recovery -- doctor and recover commands detect drift and repair common issues automatically.
• Claude context management -- backup and restore Claude Code memory, settings, and projects across sandbox lifecycle.
• Bundled skills -- ships sandbox-specific Claude Code skills (network debugging, policy linting) installed automatically during setup.
• CLI lifecycle management -- create, open, list, backup, restore, delete, and upgrade sandboxes from a single tool.

Prerequisites

Installation

Install from PyPI:

pip install sandboxctl

Or install with uv:

uv tool install sandboxctl

Optional: OpenShell SDK backend

Non-interactive gateway operations (script execution, delete) can run against the gateway through the openshell Python SDK instead of shelling out to the openshell CLI. Install the extra to enable it (falls back to the CLI automatically when unavailable):

pip install sandboxctl[sdk]

Force the legacy CLI path at any time (diagnostics/rollback):

export SANDBOXCTL_OPENSHELL_BACKEND=cli   # default: auto

For development:

git clone https://github.com/butler54/sandboxctl.git
cd sandboxctl
make dev

Quickstart

# 1. Run first-time setup (prerequisites, SSH key, credentials, providers, shell completion)
sandboxctl setup

# 2. Review and customize your config
$EDITOR "$(sandboxctl config path)"

# 3. Create a new profile skeleton
sandboxctl init my-project

# 4. Edit the profile to add repos, extensions, and settings
$EDITOR ~/.config/sandboxctl/profiles/my-project.toml

# 5. Create a sandbox from the profile
sandboxctl create --profile my-project

# 6. Open the sandbox in VS Code + Claude Code
sandboxctl open my-project

Configuration

sandboxctl uses an XDG-compliant TOML configuration file, typically located at ~/.config/sandboxctl/config.toml. Run sandboxctl config init to generate the default template:

[identity]
# user_name = "Your Name"
# user_email = "you@example.com"

[defaults]
# model = "claude-sonnet-4-20250514"
# theme = "dark"
# zoom = -1

[providers]
# provider = "anthropic"                  # "anthropic" (default) or "vertex"
# anthropic_api_key = ""                  # API key for direct Anthropic access
# vertex_project_id = ""                  # Google Cloud project (vertex only)
# vertex_region = "global"               # Vertex AI region (vertex only)

[paths]
# ssh_key = "~/.ssh/sandboxctl_ed25519"
# ca_bundle = ""

[keychain]
# github_service = "sandboxctl-github-token"
# gitlab_service = "sandboxctl-gitlab-token"

All values can also be set via environment variables with the SANDBOXCTL_ prefix (e.g., SANDBOXCTL_IDENTITY__USER_NAME).

Profiles

Profiles are TOML files under ~/.config/sandboxctl/profiles/ that describe a sandbox environment. Run sandboxctl init <name> to scaffold a new profile, then customize the generated file with your repositories, container settings, and SSH configuration.

Commands

Lifecycle

Inspection

Health & Recovery

Context Management

Setup & Maintenance

Shell Completion

Shell completion is installed automatically during sandboxctl setup. To install or update manually:

sandboxctl --install-completion

Supports bash, zsh, fish, and PowerShell.

Development

This project uses uv for dependency management and ruff for linting and formatting.

make dev       # Install in dev mode with all dependencies
make lint      # Check code style (ruff check + format check)
make format    # Auto-format code
make test      # Run tests with coverage
make clean     # Remove build artifacts

Tests run with pytest and require no external services. Integration tests that need a running OpenShell instance are marked with @pytest.mark.integration and skipped by default in CI.

License

Apache-2.0