axsandbox

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

Requirements

- 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

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. Some commands may require both.

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.

$3

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

``bash


Pull from registry (private; requires credentials)

podman pull registry.j4k.dev/axsandbox-image:latest

Or build locally

podman build -t axsandbox-image .
`

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-client

Note: 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.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
`

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" }
}
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 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 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