axrun

AI agent runner CLI. Runs AI coding agents through a unified interface.

Installation

npm install -g axrun

Usage

# Run a prompt with an agent
axrun --agent claude "Add error handling to auth.ts"
axrun -a codex "Fix the bug in main.ts"
axrun -a gemini "Refactor the utils module"
axrun -a opencode --provider anthropic "Add logging"
axrun -a copilot "Write tests"

# Specify a model
axrun -a claude --model opus "Review this PR"
axrun -a gemini --model gemini-2.5-pro "Refactor utils"
axrun -a opencode --provider anthropic --model claude-sonnet-4 "Add tests"

# Set permissions
axrun -a claude --allow 'read,glob,bash:git *' "Check git history"

# Output normalized JSONL event stream
axrun -a claude -f jsonl "Add tests" | jq 'select(.type == "tool.call")'

# Run inside external sandbox (Podman)
# Note: No host env vars are passed through for isolation; credentials are injected via --vault-credential or AX_*_CREDENTIALS
axrun -a claude --sandbox --sandbox-image <sandbox-image> "Review this PR"

# List available agents
axrun --list-agents

Options

-a, --agent <id>           Agent to use (claude, codex, copilot, gemini, opencode)
-p, --prompt <text>        Prompt text (alternative to positional argument)
-m, --model <model>        Model to use (agent-specific)
--provider <provider>      Provider for OpenCode: anthropic, openai, google (google = gemini models)
--allow <perms>            Permission rules to allow (comma-separated)
--deny <perms>             Permission rules to deny (comma-separated)
--sandbox                  Run axexec inside an external sandbox (Podman container via axsandbox; requires --sandbox-image)
--sandbox-image <image>    Sandbox image (must include axexec; required with --sandbox)
--sandbox-include <dir>    Include host directory (repeatable, mounted read-only at /include/<name>)
--sandbox-mount <spec>     Bind mount mapping <host>:<container>[:ro|rw] (repeatable, default ro)
--sandbox-persist          Keep sandbox container running after the run
--vault-credential <name>  Fetch credentials from vault (requires AXVAULT or AXVAULT_URL+AXVAULT_API_KEY)
--preserve-github-sha      Keep GITHUB_SHA env var (Gemini excludes by default)
-f, --format <fmt>         Output format: jsonl, tsv (sandbox default: jsonl)
--raw-log <file>           Write raw agent JSONL output to file (use relative paths with --sandbox)
--debug                    Enable debug mode (logs unknown events)
--verbose                  Show agent stderr output
--list-agents              List available agents
-V, --version              Show version number
--help                     Show help

Supported Agents

axrun supports: claude, codex, gemini, opencode, copilot.

Canonical references:

• Agent/package metadata: axshared (axshared/README.md)
• Credential environment variable mapping: axauth/README.md

OpenCode note: use --provider to specify provider (anthropic, openai, google).

CI/CD Usage

Using Vault (Recommended)

Fetch credentials from a centralized vault server:

axrun --agent claude --vault-credential ci-oauth-token "Review this PR"

Required: Set AXVAULT env var with vault URL and API key as JSON:

{ "url": "https://vault.example.com", "apiKey": "axv_sk_..." }

See axvault for vault setup.

Using Credential Environment Variables

For CI/CD pipelines without vault, credentials can be passed via environment variables: Canonical variable names are documented in axauth/README.md.

# Export credentials locally (one-time setup)
axauth export --agent claude --output creds.json --no-password

# Store as repository secret (e.g., AX_CLAUDE_CREDENTIALS)

# axrun auto-detects and installs credentials
axrun --agent claude --prompt "Review this PR"

For Claude, you can also use CLAUDE_CODE_OAUTH_TOKEN (generated via claude setup-token).

License

MIT