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 ghcr.io/jercik/axkit-sandbox:latest "Review this PR"

# List available agents
axrun --list-agents

Options

-a, --agent <id>           Agent to use (claude, codex, gemini, opencode, copilot)
-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)
--list-agents              List available agents
-V, --version              Show version number
--help                     Show help

Supported Agents

| Agent | Package | API Key Env Var | | -------- | ------------------------- | --------------------- | | claude | @anthropic-ai/claude-code | ANTHROPIC_API_KEY | | codex | @openai/codex | OPENAI_API_KEY | | gemini | @google/gemini-cli | GEMINI_API_KEY | | opencode | opencode-ai | ANTHROPIC_API_KEY (†) | | copilot | @github/copilot | GITHUB_TOKEN |

(†) OpenCode supports multiple providers. Use --provider to specify which provider to use (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:

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

| Agent | Credential Env Var | | -------- | ----------------------- | | claude | AX_CLAUDE_CREDENTIALS | | codex | AX_CODEX_CREDENTIALS | | gemini | AX_GEMINI_CREDENTIALS | | opencode | AX_OPENCODE_CREDENTIALS | | copilot | AX_COPILOT_CREDENTIALS |

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

License

MIT