<p align="center">
  <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License">
  <img src="https://img.shields.io/badge/python-3.10%2B-brightgreen.svg" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/status-alpha-orange.svg" alt="Status: Alpha">
</p>
 
<h1 align="center">🐰 Burrow</h1>
<p align="center">
  <strong>Open source AI agents you can run locally, modify freely, and control completely.</strong>
</p>
<p align="center">
  Your AI, your rules — no vendor lock-in, no data leaving your machine unless you want it to.
</p>
<p align="center">
  <a href="#quickstart">Quickstart</a> ·
  <a href="#features">Features</a> ·
  <a href="#docker">Docker</a> ·
  <a href="#plugins">Plugins</a> ·
  <a href="#api">API</a> ·
  <a href="https://burrow.nanocorp.app">Cloud Hosting</a>
</p>
 
---
 
## What is Burrow?
 
Burrow is a lightweight, extensible AI agent framework that runs on your own machine. It connects to any OpenAI-compatible LLM API (OpenAI, Anthropic, Ollama, LM Studio, etc.) and gives your agent tools to interact with files, run shell commands, search the web, and more.
 
- **Privacy-first**: Your data stays on your machine. Zero telemetry, zero tracking.
- **Fully open source**: Apache 2.0 licensed. Fork it, modify it, ship it.
- **Extensible**: Add custom tools via a simple plugin system.
- **Batteries included**: Built-in web dashboard, REST API, and CLI.
 
> **Want managed hosting?** Skip the setup and deploy instantly with [Burrow Cloud](https://burrow.nanocorp.app) — $19.99/mo with automatic updates and monitoring.
 
---
 
## Quickstart
 
### Prerequisites
 
- Python 3.10+
- An API key from [OpenAI](https://platform.openai.com/api-keys), or any OpenAI-compatible provider
 
### Install and run in 60 seconds
 
```bash
# Clone the repo
git clone https://github.com/nanocorp-hq/burrow.git
cd burrow/agent
 
# Install
pip install -e .
 
# Set your API key
export BURROW_API_KEY="sk-your-key-here"
 
# Start the agent
burrow start
```
 
That's it. Open **http://localhost:7700** to access the web dashboard.
 
### Or use the interactive CLI
 
```bash
burrow chat
```
 
```
  🐰 Burrow v0.1.0 — Interactive Chat
  Model: gpt-4o-mini | Tools: 6
  Type 'quit' to exit, 'reset' to clear history.
 
you: What files are in the current directory?
burrow: Let me check... [uses file tools] Here are the files: ...
```
 
---
 
## Features
 
### 🔧 Built-in Tools
 
| Tool | Description |
|------|-------------|
| `shell` | Execute shell commands |
| `file_read` | Read file contents |
| `file_write` | Write/create files |
| `list_directory` | List directory contents |
| `web_search` | Search the web (configurable provider) |
| `python_eval` | Evaluate Python expressions |
 
### 🌐 Web Dashboard
 
Start with `burrow start` and open `http://localhost:7700` — a clean, minimal chat interface for interacting with your agent in the browser.
 
### 🔌 Plugin System
 
Drop a Python file in the `plugins/` directory and it's automatically loaded:
 
```python
# plugins/my_tool.py
from burrow.tools import Tool
 
def my_function(query: str) -> str:
    return f"Result for: {query}"
 
def register(registry):
    registry.register(Tool(
        name="my_tool",
        description="Does something useful",
        parameters={
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "The input"}
            },
            "required": ["query"],
        },
        function=my_function,
    ))
```
 
### 🤖 Works with Any Provider
 
Burrow works with any OpenAI-compatible API:
 
| Provider | Config |
|----------|--------|
| **OpenAI** | `BURROW_API_KEY=sk-...` |
| **Ollama** | `BURROW_API_BASE=http://localhost:11434/v1` |
| **LM Studio** | `BURROW_API_BASE=http://localhost:1234/v1` |
| **Anthropic** | Via OpenAI-compatible proxy |
| **Azure OpenAI** | Set `BURROW_API_BASE` to your Azure endpoint |
 
---
 
## Docker
 
The fastest way to run Burrow without installing Python:
 
```bash
cd agent
 
# Set your API key
echo "BURROW_API_KEY=sk-your-key-here" > .env
 
# Start with Docker Compose
docker compose up
```
 
Or build and run manually:
 
```bash
docker build -t burrow .
docker run -p 7700:7700 -e BURROW_API_KEY=sk-your-key burrow
```
 
Open **http://localhost:7700** to access the dashboard.
 
### Using with Ollama (fully local, no API key needed)
 
```bash
# Start Ollama first
ollama serve
 
# Run Burrow pointed at Ollama
docker run -p 7700:7700 \
  -e BURROW_API_BASE=http://host.docker.internal:11434/v1 \
  -e BURROW_API_KEY=ollama \
  -e BURROW_MODEL=llama3.2 \
  burrow
```
 
---
 
## Configuration
 
Burrow can be configured via environment variables, a config file, or CLI flags.
 
### Environment Variables
 
| Variable | Default | Description |
|----------|---------|-------------|
| `BURROW_API_KEY` | — | LLM API key (required) |
| `BURROW_MODEL` | `gpt-4o-mini` | Model name |
| `BURROW_PROVIDER` | `openai` | LLM provider |
| `BURROW_API_BASE` | — | Custom API endpoint |
| `BURROW_HOST` | `0.0.0.0` | Server bind address |
| `BURROW_PORT` | `7700` | Server port |
| `BURROW_LOG_LEVEL` | `INFO` | Log level |
 
### Config File
 
```bash
burrow init  # Creates ~/.burrow/config.json
```
 
```json
{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "api_key": "sk-...",
  "temperature": 0.7,
  "enabled_tools": ["shell", "file_read", "file_write", "web_search"],
  "system_prompt": "You are a helpful assistant."
}
```
 
---
 
## API
 
The Burrow server exposes a simple REST API:
 
### `POST /api/chat`
 
Send a message and get a response:
 
```bash
curl -X POST http://localhost:7700/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is 2 + 2?"}'
```
 
```json
{"response": "2 + 2 = 4"}
```
 
### `POST /api/reset`
 
Clear the conversation history:
 
```bash
curl -X POST http://localhost:7700/api/reset
```
 
### `GET /api/health`
 
Health check endpoint:
 
```bash
curl http://localhost:7700/api/health
```
 
---
 
## Programmatic Usage
 
Use Burrow as a Python library:
 
```python
from burrow import Agent
from burrow.config import BurrowConfig
 
# Create an agent
config = BurrowConfig.load()
agent = Agent(config=config)
 
# Chat
response = agent.chat("List the files in the current directory")
print(response)
 
# Add custom tools
from burrow.tools import Tool
 
agent.register_tool(Tool(
    name="greet",
    description="Greet someone by name",
    parameters={
        "type": "object",
        "properties": {"name": {"type": "string"}},
        "required": ["name"],
    },
    function=lambda name: f"Hello, {name}!",
))
 
response = agent.chat("Greet Alice")
print(response)
```
 
---
 
## Project Structure
 
```
agent/
├── burrow/              # Core Python package
│   ├── __init__.py      # Package exports
│   ├── agent.py         # Agent logic (tool-calling loop)
│   ├── cli.py           # CLI commands (start, chat, init)
│   ├── config.py        # Configuration management
│   ├── plugins.py       # Plugin loader
│   ├── server.py        # HTTP server + web dashboard
│   └── tools.py         # Tool registry + built-in tools
├── plugins/             # Drop-in plugins (auto-loaded)
├── tests/               # Test suite
├── examples/            # Usage examples
├── Dockerfile           # Container support
├── docker-compose.yml   # One-command deployment
└── pyproject.toml       # Python project config
```
 
---
 
## Burrow Cloud
 
Don't want to self-host? **[Burrow Cloud](https://burrow.nanocorp.app)** gives you the same open source agent with managed infrastructure:
 
- ✅ Automatic updates and security patches
- ✅ Uptime monitoring and alerts
- ✅ No server management
- ✅ Cancel anytime — your data is always exportable
 
**$19.99/month** → [Get started at burrow.nanocorp.app](https://burrow.nanocorp.app)
 
---
 
## Contributing
 
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
Key areas where we need help:
- New tools and plugins
- Additional LLM provider support
- Documentation and examples
- Tests and bug fixes
 
---
 
## License
 
Apache 2.0 — see [LICENSE](LICENSE) for details. Use it, modify it, ship it.
 
---
 
<p align="center">
  Built by <a href="https://burrow.nanocorp.app">Burrow</a> — open source AI agents for everyone.
</p>