whzbox

whzbox is a Go CLI for Whizlabs cloud sandboxes. It creates, caches, lists, and destroys AWS, Azure, and GCP sandboxes.

AWS includes programmatic credentials for whzbox exec. Azure and GCP provide browser-console credentials only. Azure console login also requires a short-lived MFA code from whzbox mfa azure.

Install

Install from GitHub Releases, Homebrew, Scoop, or from source.

# Homebrew (macOS/Linux)
brew install meigma/tap/whzbox

# Scoop (Windows)
scoop bucket add meigma https://github.com/meigma/scoop-bucket
scoop install whzbox

# ghd (macOS/Linux releases produced by the current pipeline)
ghd install meigma/whzbox/whzbox

# Go
go install github.com/meigma/whzbox/cmd/whzbox@latest

Build from a checkout:

go build -o whzbox ./cmd/whzbox
./whzbox --help

Quick Start

whzbox login
whzbox create aws
whzbox exec aws -- aws sts get-caller-identity
whzbox destroy --yes

For a GCP console sandbox:

whzbox create gcp
# Open the displayed console URL and sign in with the displayed username and password.
whzbox destroy --yes

For an Azure console sandbox:

whzbox create azure
# Open the displayed console URL and sign in with the username and password.
# At the MFA prompt, select "Use a verification code".
whzbox mfa azure
# Enter the displayed MFA code.
whzbox destroy --yes

Common commands:

• whzbox create aws creates an AWS sandbox with console and programmatic credentials.
• whzbox create azure creates an Azure sandbox with console credentials and resource groups.
• whzbox create gcp creates a GCP sandbox with console credentials and project metadata.
• whzbox mfa azure prints a fresh Azure console MFA code without caching it.
• whzbox list shows cached sandboxes from local state.
• whzbox exec aws -- <command> runs a command with sandbox credentials injected.
• whzbox status shows the cached session.
• whzbox destroy tears down the active sandbox.

Run whzbox <command> --help for per-command flags.

Documentation

The root README stays intentionally short. The rendered site is at whzbox.meigma.dev, with source under docs/docs/:

• Documentation overview
• AI agent skill
• Tutorial: create, use, and destroy your first AWS sandbox
• How-to guides
• Command reference
• Explanation

A repo-local SKILL.md is available for AI agents that need a concise, task-oriented guide to using the CLI before drilling into the full docs.

A few behaviors that are easy to miss are documented in detail there:

• create aws, create azure, and create gcp can reuse an unexpired cached sandbox.
• Whizlabs permits one active sandbox, so destroy the current provider before creating another.
• exec supports AWS only. exec azure and exec gcp explain the console-only limitation.
• exec, list, and status read local state; they do not talk to Whizlabs.
• --json is implemented by create and list.

Preview the docs site locally:

cd docs
mise exec -- uv sync --locked
mise exec -- uv run --locked mkdocs serve

Development

Prerequisites:

• mise for the repository's locked toolchain

Common tasks:

mise install
mise exec -- moon run root:check

Repository settings are declared in .github/repository-settings.toml. Preview supported GitHub changes before applying them:

mise exec -- uv run .github/scripts/configure_github_repo.py plan --repo meigma/whzbox

Run the Whizlabs integration tests only when you have real credentials in a repo-local .env:

go test -tags integration -timeout 5m ./internal/adapters/whizlabs/...

Those tests read USERNAME and PASSWORD from .env.

License

Dual-licensed under Apache-2.0 or MIT.