AIO Sandbox Practical Workflows

Production-style workflow collection for learning AIO Sandbox quickly.

What You Get

• One workflow file per core feature
• A Docker launcher script for reproducible startup
• An end-to-end "real-world value" showcase
• Open-source friendly structure and docs

Quick Start

1. Start AIO Sandbox with Docker:

make sandbox-up

Check whether it is running:

make sandbox-status

Inspect logs when needed:

make sandbox-logs

Stop it when you are done:

make sandbox-stop

Alternative raw scripts:

./scripts/run_sandbox_docker.sh --detach
./scripts/status_sandbox_docker.sh
./scripts/logs_sandbox_docker.sh
./scripts/stop_sandbox_docker.sh

Alternative options:

# Run in foreground
./scripts/run_sandbox_docker.sh

# Use another host port
./scripts/run_sandbox_docker.sh --port 3000

# Use China mirror
./scripts/run_sandbox_docker.sh --mirror cn --port 8080

# Keep the container after it stops
./scripts/run_sandbox_docker.sh --detach --keep-container

# Remove a kept container explicitly
./scripts/stop_sandbox_docker.sh --remove

# Use another port via Make
make sandbox-up PORT=3000
make sandbox-status PORT=3000

2. Install SDK:

pip install agent-sandbox

3. Run a workflow:

python3 workflows/04_browser_screenshot.py --target-url https://example.com

Or run project checks:

make lint
make workflow-smoke

Workflow Catalog

• workflows/01_context.py: sandbox context and runtime metadata
• workflows/02_shell.py: execute shell command in sandbox
• workflows/03_file.py: write/read file in sandbox
• workflows/04_browser_screenshot.py: navigate and take screenshot
• workflows/05_browser_action.py: GUI action automation
• workflows/06_code_execute.py: execute Python via Jupyter kernel
• workflows/07_cdp_playwright.py: connect via CDP (Playwright)
• workflows/08_web_task_agent.py: rule-driven browser-use style website navigator
• workflows/09_sandbox_agent.py: model-driven final agent across shell/browser/file/jupyter
• workflows/market_research_pipeline.py: full workflow for market-page intelligence

End-to-End Real-World Scenario

market_research_pipeline.py implements a practical task:

• Collect environment facts via shell
• Capture target website screenshot via browser automation
• Extract rendered HTML from the sandbox browser when Playwright is available
• Execute Python in sandbox to build a markdown report
• Export all artifacts to local sandbox_outputs/

Run it:

python3 workflows/market_research_pipeline.py --target-url https://www.anthropic.com

If your local Python has broken CA certificates and HTTPS fetch fails, you can explicitly opt in:

python3 workflows/market_research_pipeline.py --target-url https://www.anthropic.com --allow-insecure-fetch

For the most consistent report output, install Playwright so the workflow can read rendered HTML from the sandbox browser instead of falling back to a local HTTP fetch:

pip install playwright
playwright install chromium

Agent Workflows

The repository now includes two "agent-flavored" workflows built on top of the sandbox browser, shell, file, and Jupyter capabilities:

• 08_web_task_agent.py: a stable, rule-driven website task agent that explores a site, follows likely navigation targets such as pricing/docs, captures screenshots, and writes a report.
• 09_sandbox_agent.py: a model-driven final agent that uses an OpenAI-compatible chat completion endpoint and can decide which sandbox tool to call next.

Run the rule-driven browser-use style workflow:

pip install playwright
playwright install chromium
python3 workflows/08_web_task_agent.py \
  --target-url https://www.anthropic.com \
  --goal "Find the pricing or developer docs page and summarize it"

Run the model-driven final agent:

export SANDBOX_AGENT_API_KEY="<your_api_key>"
# Optional: override the default model
# export SANDBOX_AGENT_MODEL="gpt-4.1-mini"
# Optional if you use a non-default OpenAI-compatible endpoint:
# export SANDBOX_AGENT_BASE_URL="https://api.openai.com/v1"

python3 workflows/09_sandbox_agent.py \
  --target-url https://www.anthropic.com \
  --task "Inspect the website, collect a few high-signal facts, and write a markdown report."

Environment variable fallback rules for 09_sandbox_agent.py:

• API key: SANDBOX_AGENT_API_KEY or OPENAI_API_KEY
• Model: SANDBOX_AGENT_MODEL or OPENAI_MODEL
• Base URL: SANDBOX_AGENT_BASE_URL or OPENAI_BASE_URL

Documentation

• Full tutorial: docs/QUICK_TUTORIAL.md
• AIO docs endpoint (default port): http://localhost:8080/v1/docs
• Contribution guide: CONTRIBUTING.md

Docker Lifecycle

The Docker helper scripts use a fixed container name per port:

• Port 8080 -> aio-sandbox-8080
• Port 3000 -> aio-sandbox-3000

This makes detached runs manageable and predictable:

# Start or reuse sandbox on port 8080
./scripts/run_sandbox_docker.sh --detach

# Check whether it is running, stopped, or not found
./scripts/status_sandbox_docker.sh

# Tail logs from the current sandbox container
./scripts/logs_sandbox_docker.sh --follow

# Stop the running container
./scripts/stop_sandbox_docker.sh

# Stop and remove a kept container
./scripts/stop_sandbox_docker.sh --remove

Equivalent Make targets:

make sandbox-up
make sandbox-status
make sandbox-logs
make sandbox-stop
make sandbox-stop-remove

Notes

• Python 3.11 or 3.12 is recommended.
• Python 3.14 may show pydantic.v1 compatibility warnings in current SDK versions.
• If your container runs on another port, pass --base-url http://localhost:<port> to each workflow.
• If you use non-default Docker port mapping, replace 8080 in dashboard/API docs URLs accordingly.
• run_sandbox_docker.sh supports foreground mode by default, plus --detach for background runs and --keep-container to keep stopped containers for inspection.
• Detached containers are managed by port-based names, so you can use status_sandbox_docker.sh, stop_sandbox_docker.sh, and logs_sandbox_docker.sh without guessing container IDs.
• Use --verbose on workflows to print structured JSON logs for CI/debugging.
• 08_web_task_agent.py and browser tools in 09_sandbox_agent.py require Playwright (pip install playwright && playwright install chromium).
• 09_sandbox_agent.py expects an OpenAI-compatible chat completion endpoint configured through environment variables.

License

MIT. See LICENSE.