@agent-arena-tools/cli

Effortlessly deploy, execute, and manage autonomous AI coding agents inside isolated, secure local sandboxes.

agents is the official command-line interface for the Agent Arena ecosystem. It eliminates the friction of installing, executing, and configuring diverse autonomous software engineering (SWE) agents—such as Claude Code, Devin, Aider, Cline, and Nanobot-AI—by automatically containerizing their runtimes or auditing native host dependencies.

🌐 Visit the Arena Platform

Want to see which agent writes the cleanest code? Check out our live platform to view crowd-sourced performance metrics, inspect historical git diffs, and cast your votes in the blind preference arena: 👉 Explore the Live Leaderboard at agent-arena.top

🚀 Key Features

• 🐳 One-Click Docker Sandboxing (Default): Runs agents inside secure, ephemeral Docker containers to prevent unauthorized filesystem edits, arbitrary terminal execution, or rogue scripts from modifying your host machine.
• 💻 Native OS Installation (-g): Option to deploy agents directly on your host machine for native process speed, integrated IDE configurations, or local shell environments.
• 🔍 Interactive Pre-install Auditing: Runs quick requirement diagnostics (e.g., Node.js, Python, package managers like uv or cargo) before host setups and prompts to resolve missing packages dynamically.
• 🔑 Secure Key Forwarding: Automatically reads required developer API tokens (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEVIN_API_KEY) from your host environment and securely bridges them to the sandboxed runtime.
• 📡 Dynamic Blueprint Ingestion: Fetches the latest installation recipes, base images, and live platform metadata over the network directly from the Agent Arena database, featuring seamless offline fallbacks.

📦 Installation

Install the package globally via npm:

npm install -g @agent-arena-tools/cli

⚠️ Prerequisite Note: If you plan to run autonomous tools inside isolated sandboxes (highly recommended default behavior), ensure the Docker Engine is installed and active on your system.

🛠️ Command Reference

1. List Blueprints

Fetch and list all supported AI coding agents currently configured live in the Arena database.

agents list

2. Install / Run an Agent

Initialize a secure environment and launch an AI coding agent.

agents install <agent-slug>

Options:

• -g, --global: Install the agent globally on your host machine instead of inside an isolated Docker container.

Examples:

# Securely install and start Claude Code inside an isolated Docker container
agents install claude-code

# Install Aider globally on your local host OS
agents install aider -g

3. Uninstall / Clean up an Agent

Stop and tear down an AI agent's sandbox container, volume paths, or native system files.

agents uninstall <agent-slug>

Options:

• -g, --global: Uninstall the target agent profile from your host machine instead of Docker.

Examples:

# Terminate and remove the Claude Code Docker sandbox container
agents uninstall claude-code

# Remove Aider completely from your global host system
agents uninstall aider -g

4. Run an Installed Agent

Instantly run an installed agent. Automatically starts the sandbox if it's stopped.

agents run <agent-slug>

Options:

• -g, --global: Run the natively installed agent instead of Docker sandbox.

Examples:

# Run Claude Code inside its Docker sandbox
agents run claude-code

# Run Aider natively on your host
agents run aider -g

📊 Deep Dive: Sandboxed vs Native Mode

When executing agents install , the CLI orchestrates installation environments based on your target isolation parameters: | Feature | Sandboxed Mode (Docker Default) | Native Mode (-g / --global) | |---|---|---| | Orchestrator | Docker Engine | Host OS (Node/Python/Pip/Npm/Uv) | | Container Layer | arena- | N/A | | Default Runtime | Dynamic based on recipe (Node, Python, Rust) | Your local system environment | | Prerequisites | Docker running | Language runtimes matching agent source | | Interactive Checks | None (Pre-configured inside clean container) | Evaluates missing host dependencies | | Security Isolation | 🛡️ Maximum (Filesystem & network blocks) | ⚠️ None (Full read/write host access) | | Ideal For | Safe feature generation, untrusted code strings | Heavy local builds, local editor plugins |

🧠 How It Works Under the Hood

1. Sandbox Initialization Flow

graph TD;
    A[Run install <agent>] --> B{Is -g / --global active?};
    B -- No --> C[Check Docker status];
    C -- Offline --> D[Log Error & Link Download];
    C -- Running --> E{Container State?};
    E -- running --> F[Notify Active & Show Exec Command];
    E -- stopped --> G[Restart existing container];
    E -- non-existent --> H[Create background container tailing /dev/null];
    H --> I[Forward API Keys as -e flags];
    I --> J[Run installCmd inside Container];
    J --> K[Ready! Run via docker exec];
    
    B -- Yes --> L[Lookup runtime requirement];
    L --> M{Diagnostic Check Command};
    M -- Exits 0 --> N[Install globally via package manager];
    M -- Fails --> O[Prompt User to install missing dependency];
    O -- y/yes --> P[Run devDepInstallCmd] --> N;
    O -- n/no --> Q[Abort Installation];

2. Environment Variable Forwarding

To configure agents inside Docker cleanly without hardcoding credentials, the CLI reads your local terminal environment and mounts existing keys to the container runtime on initialization:

• ANTHROPIC_API_KEY (e.g., Claude Code, OpenClaw)
• OPENAI_API_KEY (e.g., Aider, AutoGPT)
• DEVIN_API_KEY (e.g., Devin) Ensure they are defined on your shell path before bootstrapping an installer loop:

export ANTHROPIC_API_KEY="your-api-key"
agents install claude-code

🔒 Security Policy

The default sandbox configuration wraps automated tools in pristine execution areas:

• Containers boot using lightweight alpine or slim base images with minimal networking surfaces.
• Processes are isolated to internal virtual software bridges, safeguarding local network interfaces.
• Host volumes are unmounted by default, preventing rogue LLM generation strings from corrupting parent project structures.

🏷️ Keywords & Search Tags

For optimization, tracking, and discoverability across the ecosystem: ai-agents claude-code swe-agent sandbox docker llm-tools autonomous-agents aider openclaw cline devin code-arena leaderboard terminal cli package-manager

📄 License

MIT License. Copyright (c) 2026 Agent Arena.

🔗 Source Code

Source code is available on GitHub: github.com/naimul-islam-64/Agent-Arena-CLI