axsandbox

Podman-based sandbox manager CLI for creating and managing ephemeral container sessions.

Requirements

• Node.js >= 22.19.0
• Podman (podman)
  • On macOS, podman machine must be initialized and running
  • When axsandbox exec passes env vars into the container (including TERM in TTY mode), it requires podman exec --env-file
  • Override binary path with AXSANDBOX_PODMAN_PATH=/path/to/podman
• jq (used in examples)
• POSIX shell (sh) for the example scripts

CLI conventions

• Output formats (for up, inspect, gc, validate): --format json|text (use json for pipelines; text for humans).
• stdout filtering: --stdout-filter jsonl enforces valid JSON Lines output by dropping non-JSON and empty lines; it requires non-TTY exec mode (--tty off, or leave --tty auto and pipe/redirect stdout), and errors if TTY is enabled.
• Prefer long flags (--format, --yes, --force) over short flags.
• Confirmations: --yes auto-confirms prompts; --force overrides safety checks. Both are optional and independent.

Sandbox images

When using axsandbox as the backend for axrun --sandbox, your container image must satisfy the image contract in docs/sandbox-image.md.

The alpine image in the quick start is fine for axsandbox exec, but it does not include axexec and is not suitable for end-to-end agent runs.

Reference image

A reference container image satisfying the contract in docs/sandbox-image.md is available:

# Pull a released image tag from registry (private; requires credentials)
podman pull registry.j4k.dev/axsandbox:<version>

# Or build locally
podman build -t axsandbox .

Use the latest GitHub release version (without a leading v) for <version>.

The reference image includes:

• Node.js >= 22.19.0 runtime
• axexec CLI
• All 5 agent CLIs: claude, codex, gemini, opencode, copilot
• Common dev tools: bash, git, curl, jq, openssh-client

Note: Agent CLIs are pinned in Containerfile defaults. Override via build args to update versions.

Building with specific versions

podman build \
  --build-arg AXEXEC_VERSION=1.7.0 \
  --build-arg AXINSTALL_VERSION=1.2.0 \
  -t axsandbox:custom .

Publishing

Container publishing is now part of CI/CD:

• Pushes to main run the Release workflow.
• If semantic-release creates a new version tag, CI builds and publishes a multi-arch image to registry.j4k.dev/axsandbox:<version>.

For manual publishing outside CI, use the script:

# Publish image tagged with local package.json version
./scripts/publish-image.sh

# Publish specific version
./scripts/publish-image.sh --version 1.2.0

# Dry run (build but don't push)
./scripts/publish-image.sh --dry-run

See scripts/publish-image.sh --help for more options.

Quick start

Show help:

npx -y axsandbox --help

Validate Podman:

npx -y axsandbox validate --format text

Create a session:

workdirHost="$(mktemp -d)"
cat > spec.json <<EOF
{
  "image": "docker.io/library/alpine:3.19",
  "workdirHost": "$workdirHost",
  "workdirContainer": "/workspace",
  "mounts": [],
  "network": "off",
  "tty": "off",
  "envPolicy": { "allow": [], "deny": [], "default": "deny" }
}
EOF

container="$(npx -y axsandbox up --spec-file ./spec.json --format text)"
echo "container=$container"

Note: Setting envPolicy.default to "allow" forwards all host environment variables (except those in deny) and can leak secrets. Prefer "deny" + an explicit allow list.

Run a command:

Note: axsandbox exec <container> operates on an existing container name and does not reload the spec used by up. It uses conservative defaults and does not forward host environment variables by default (except TERM when TTY is enabled).

npx -y axsandbox exec "$container" -- sh -lc 'echo hello'

Remove the session:

npx -y axsandbox down "$container" --yes --force

Examples (Pipelines)

Extract the container name for scripting:

npx -y axsandbox up --spec-file ./spec.json --format json | jq -r '.containerName'

Preview what gc would remove, then count candidates:

npx -y axsandbox gc --dry-run --format json | jq '.containers | length'

Inspect a session and extract fields using standard tools:

npx -y axsandbox inspect "$container" --format json | jq -r '.image // ""'

Filter command output to valid JSONL and post-process with jq:

npx -y axsandbox exec "$container" --stdout-filter jsonl -- sh -lc 'echo "{\"ok\":true}"' | jq -c '.'

Agent Rule

Add to your CLAUDE.md or AGENTS.md:

# Rule: `axsandbox` Usage

Run `npx -y axsandbox --help` to learn available options.

Use `axsandbox` to create/inspect/exec inside Podman sandbox sessions and capture script-friendly stdout/stderr for pipelines.

License

MIT