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 --
doctorandrecovercommands 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
| Requirement | Version |
|---|---|
| Python | 3.12+ |
| NVIDIA OpenShell | latest |
| OS | macOS or Linux |
Installation
Install from PyPI:
pip install sandboxctl
Or install with uv:
uv tool install sandboxctl
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
| Command | Description |
|---|---|
sandboxctl create --profile <name> |
Create a sandbox from a profile |
sandboxctl open <name> |
Open a sandbox in VS Code, Claude Code, or shell |
sandboxctl restart <name> |
Delete and recreate a sandbox (with data loss warning) |
sandboxctl delete <name> |
Delete a sandbox |
Inspection
| Command | Description |
|---|---|
sandboxctl list |
List profiles and running sandboxes |
sandboxctl status |
Show gateway and sandbox status |
sandboxctl validate <name> |
Run validation tests inside a sandbox |
Health & Recovery
| Command | Description |
|---|---|
sandboxctl doctor [name] |
Diagnose sandbox health, credentials, and profile readiness |
sandboxctl doctor --fix [name] |
Re-inject credentials and CA bundles into running sandboxes |
sandboxctl recover [name] |
Recover stopped sandboxes after host reboot or podman restart |
Context Management
| Command | Description |
|---|---|
sandboxctl backup [name] |
Back up Claude context (memory, settings) from a sandbox |
sandboxctl restore <name> |
Restore Claude context into a sandbox |
Setup & Maintenance
| Command | Description |
|---|---|
sandboxctl setup |
First-time setup: prerequisites, SSH key, credentials, providers, shell completion, bundled skills |
sandboxctl upgrade |
Upgrade OpenShell (detects Homebrew/pip, advises gateway restart) |
sandboxctl init <name> |
Create a new profile skeleton |
sandboxctl config init |
Create default configuration file |
sandboxctl config show |
Show current configuration |
sandboxctl config path |
Print config file path |
sandboxctl --version |
Show version and exit |
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
1 maintainer
Release files for sandboxctl 1.20.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sandboxctl-1.20.0.tar.gz | 128.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sandboxctl-1.20.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 200.8 kB
Release files / sandboxctl-1.20.0.tar.gz
| Download URL | sandboxctl-1.20.0.tar.gz |
|---|---|
| Size | 128.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f26877efc798aa4a10282836a2d1357d4e202f5fc9d48d06917c4b90cce4693
|
|
BLAKE2b-256 checksum How to use checksums |
2317772e17a82a34ca4d861e3cee84b73f63394bdf8217d056b6b958dd603bbf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logRelease files / sandboxctl-1.20.0-py3-none-any.whl
| Download URL | sandboxctl-1.20.0-py3-none-any.whl |
|---|---|
| Size | 72.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e5072e9c0abb745e0faa9aa08d7e66f85fea986bbd0e2c58d7affa5308971073
|
|
BLAKE2b-256 checksum How to use checksums |
0f2ee3ce27ba4b842d774b30c3491963628f7d307d4c18427eae688119901f50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency log
