Agent Sandbox Registry

agent-sandbox

Getting Started

中文

docs/en/guide/getting-started.md

Getting Started

This tutorial walks you through the complete sandbox lifecycle, from installation to teardown.

Prerequisites

1. Installation

# Install the CLI globally from npm
npm install -g @agent-sandbox/cli

# Or run it without installing
npx @agent-sandbox/cli --version

# Verify the installation
abx --version

Standalone binary (no Node.js required)

If you'd rather not set up a Node.js environment, abx is also available as a precompiled standalone binary for Linux, macOS, and Windows:

# Example: install v0.3.0 on macOS (Apple Silicon)
curl -fsSL -o "$HOME/abx" \
  "https://github.com/alibaba-agent-sandbox/agent-sandbox/releases/download/v0.3.0/abx-0.3.0-darwin-arm64"
chmod +x "$HOME/abx"
sudo mv "$HOME/abx" /usr/local/bin/abx

For other platforms, checksum verification, and a comparison with the npm install, see the Binary Installation guide.

2. Configure the API Key

There are two ways to configure credentials. When a call actually needs the key, this is the order (highest first). The full table is in Configuration — Credential resolution.

export ABX_SANDBOX_API_KEY="your-api-key-here"

Used when neither the environment nor the project .env sets the key.

abx config set sandbox_api_key your-api-key
# Writes to ~/.abx/.env (permissions 600)

Verify the configuration:

abx config get sandbox_api_key

3. Create Your First Sandbox

Using the CLI

abx create --template base

4. Execute Code

CLI

abx exec <sandbox-id> "echo 'Hello from sandbox'"

5. Run Shell Commands

CLI

abx exec <sandbox-id> "pip install requests && python -c 'import requests; print(requests.__version__)'"

6. File Operations

CLI upload/download

# Upload
abx upload <sandbox-id> ./data.csv /home/user/data.csv

# Download
abx download <sandbox-id> /home/user/result.csv ./result.csv

7. List Directory Contents

abx sandbox files list <sandbox-id> --path /home/user

8. Destroy a Sandbox

CLI

abx kill <sandbox-id>

# Destroy all running sandboxes
abx kill --all --yes

9. Complete Example

# Create a sandbox and upload a project
abx create --template base --upload ./project

# Run something inside it
abx exec <sandbox-id> "python /home/user/project/main.py"

# Fetch the result and tear the sandbox down
abx download <sandbox-id> /home/user/result.csv ./result.csv
abx kill <sandbox-id> --yes

Next Steps

Using the Python SDK instead of (or next to) the CLI: Getting Started (SDK) and the SDK Usage Guide in the python-sdk repository.