bluebox 🟦

Index the world's undocumented APIs.

Why "Blue Box"? Named after the phone phreaking devices that let tech enthusiasts in the 1960s and 70s explore telephone networks.

You are in the right place if you ...

• need to scrape data behind UI interactions
• are dealing with closed APIs
• want to reverse engineer websites

Tutorial

bluebox-agent-tutorial.mov

Prerequisites

• Python 3.12+
• Vectorly API key (required, used by bluebox agent for web data extraction)
  • Sign up at console.vectorly.app
  • macOS/Linux: export VECTORLY_SERVICE_TOKEN="your-key"
  • Windows (PowerShell): setx VECTORLY_SERVICE_TOKEN "your-key"
  • Or add it to your .env file: VECTORLY_SERVICE_TOKEN=your-key
• LLM provider API key (required, used by bluebox agent for orchestration)
  • Configure one of the following:
  • OpenAI (default):
    • macOS/Linux: export OPENAI_API_KEY="your-key"
    • Windows (PowerShell): setx OPENAI_API_KEY "your-key"
    • .env: OPENAI_API_KEY=your-key
  • Anthropic:
    • macOS/Linux: export ANTHROPIC_API_KEY="your-key"
    • Windows (PowerShell): setx ANTHROPIC_API_KEY "your-key"
    • .env: ANTHROPIC_API_KEY=your-key
• uv (optional, for dependency management)
  • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows (PowerShell): iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex

Installation

# Clone the repository
git clone https://github.com/VectorlyApp/bluebox.git
cd bluebox

# Create and activate virtual environment
python3 -m venv bluebox-env
source bluebox-env/bin/activate  # On Windows: bluebox-env\Scripts\activate

# Install in editable mode
pip install -e .

# Or using uv (faster)
uv venv bluebox-env
source bluebox-env/bin/activate
uv pip install -e .

Bluebox agent

The bluebox agent is a conversational AI agent that automates web data extraction. It searches the Vectorly web routine index for relevant web APIs, executes matched endpoints in parallel, and falls back to a live AI browser agent when no suitable pre-built routine is available.

Quickstart

# run with OpenAI models
bluebox-agent --model gpt-5.2

# run with Anthropic models
bluebox-agent --model claude-opus-4-5

What it does:

• Interprets natural language requests and maps them to relevant routines
• Executes multiple routines concurrently for faster results
• Falls back to an AI browser agent for tasks without predefined routines
• Post-processes outputs using Python (CSV, JSON, etc.)
• Saves generated files to a local workspace

Ask it anything: "Run a price analysis on Rolex Sea Dweller 16600" — the agent automatically selects the right routine, runs it, and delivers structured results.

Create your own routines

To learn about the core technology powering BlueBox, see routine_discovery.md.

Contributing 🤝

We welcome contributions! Here's how to get started:

1. Report bugs or request features — Open an issue
2. Submit code — Fork the repo and open a pull request
3. Test your code — Add unit tests and make sure all tests pass:

python -m pytest tests/ -v

Please follow existing code style and include tests for new features.