Podman-based sandbox manager CLI for creating and managing ephemeral container sessions
npm install axsandboxPodman-based sandbox manager CLI for creating and managing ephemeral container sessions.
- Node.js >= 22.14.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
- 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. Some commands may require both.
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.
A reference container image satisfying the contract in docs/sandbox-image.md is available:
``bashPull from registry (private; requires credentials)
podman pull registry.j4k.dev/axsandbox-image:latest
The reference image includes:
- Node.js >= 22.14.0 runtime
-
axexec CLI
- All 5 agent CLIs: claude, codex, gemini, opencode, copilot
- Common dev tools: bash, git, curl, jq, openssh-clientNote: Agent CLIs are pinned in
Containerfile defaults. Override via build args to update versions.$3
`bash
podman build \
--build-arg AXEXEC_VERSION=1.7.0 \
--build-arg AXINSTALL_VERSION=1.2.0 \
-t axsandbox-image:custom .
`$3
Use the provided script to build and publish multi-arch images to the registry:
`bash
Publish image tagged with local package.json version
./scripts/publish-image.shPublish specific version
./scripts/publish-image.sh --version 1.2.0Dry run (build but don't push)
./scripts/publish-image.sh --dry-run
`Publishing from CI (GitHub Actions) is intentionally not implemented yet. For now we publish manually to keep the release process simple and avoid CI registry credential/tooling setup.
See
scripts/publish-image.sh --help for more options.Quick start
Show help:
`bash
npx -y axsandbox --help
`Validate Podman:
`bash
npx -y axsandbox validate --format text
`Create a session:
`bash
workdirHost="$(mktemp -d)"
cat > spec.json < {
"image": "docker.io/library/alpine:3.19",
"workdirHost": "$workdirHost",
"workdirContainer": "/workspace",
"mounts": [],
"network": "off",
"tty": "off",
"envPolicy": { "allow": [], "deny": [], "default": "deny" }
}
EOFcontainer="$(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 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).`bash
npx -y axsandbox exec "$container" -- sh -lc 'echo hello'
`Remove the session:
`bash
npx -y axsandbox down "$container" --yes --force
`Examples (Pipelines)
Extract the container name for scripting:
`bash
npx -y axsandbox up --spec-file ./spec.json --format json | jq -r '.containerName'
`Preview what
gc would remove, then count candidates:`bash
npx -y axsandbox gc --dry-run --format json | jq '.containers | length'
`Inspect a session and extract fields using standard tools:
`bash
npx -y axsandbox inspect "$container" --format json | jq -r '.image // ""'
`Filter command output to valid JSONL and post-process with
jq:`bash
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:`markdown
Rule:
axsandbox UsageRun
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.
``MIT