English | [日本語](README.ja.md)

# MAESTRO

![License](https://img.shields.io/badge/license-Apache--2.0-blue)

**MAESTRO** — an agent orchestration platform that runs tasks driven by an LLM. The LLM automatically classifies the kind of task and handles it with the appropriate workflow (**Piece**). Tools run in a sandboxed runtime, and you manage workspaces, files, and progress through a web UI.

It works standalone as long as you have an OpenAI-compatible LLM endpoint ([Ollama](https://ollama.com/) / vLLM, etc.).

## Key features

- **Automatic task routing** — the LLM classifies the task body and dispatches it to the best-fit Piece (a YAML workflow).
- **Piece × Movement** — the LLM and tools converse in a ReAct loop, advancing the task step by step.
- **Rich tool set** — file operations (Read/Write/Edit/Bash/Glob/Grep), Office (PDF/Excel/Docx/PPTX), web fetching, browser automation (Playwright), images, SQLite, knowledge search (RAG), SSH, parallel subtask execution, MCP integration, and more.
- **Bash sandbox** — isolates the filesystem, network, and environment variables via bwrap (falls back to a hardened whitelist when bwrap is absent). Python packages are pre-baked.
- **LLM Gateway (optional)** — an LLM proxy with virtual keys, budgets, and metrics. Supports shared operation across multiple GPUs/teams.
- **Learning (Reflection), scheduled tasks, task sharing, OAuth authentication (Google/Gitea)** — all optional, enabled on demand.
- **Web UI** — task creation, progress, deliverable previews, settings editing, and skill/Piece management.

## Quickstart

### Docker (fastest)

```bash
cp .env.example .env          # set OLLAMA_BASE_URL / OLLAMA_MODEL
docker compose up -d
# open http://localhost:9876
```

For safety, Compose exposes only `127.0.0.1:9876`. Before making it reachable from another host, configure OAuth authentication and place a TLS-enabled reverse proxy in front. Specify the LLM endpoint in `.env` / `config.yaml`.

### From source

```bash
git clone https://gitea.example.com/your-org/maestro.git
cd maestro
npm ci && npm --prefix ui ci
cp config.yaml.example config.yaml      # edit provider / workers
scripts/build-all.sh
scripts/server.sh start                 # http://localhost:9876
```

For detailed instructions, see **[docs/getting-started.md](docs/getting-started.md)**.

## Requirements

- **Node.js 22+**
- **An OpenAI-compatible LLM endpoint** (Ollama / vLLM, etc.)
- Optional (for the Bash sandbox): `bwrap` (bubblewrap, unprivileged user namespaces) + `python3`/`pip`

## Documentation

- **[docs/getting-started.md](docs/getting-started.md)** — installation, first launch, your first task, enabling auth/sandbox
- **[docs/configuration.md](docs/configuration.md)** — full reference of every `config.yaml` setting
- **[docs/architecture.md](docs/architecture.md)** — execution flow, Piece/Movement, tools, DB, sandbox
- **[docs/tools/](docs/tools/)** — details of each tool
- **[docs/operations/bash-sandbox-provisioning.md](docs/operations/bash-sandbox-provisioning.md)** — how to enable the sandbox in production
- **[AGENTS.md](AGENTS.md)** / **[CONTRIBUTING.md](CONTRIBUTING.md)** — for contributors
- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — community standards
- **[SECURITY.md](SECURITY.md)** — security policy and vulnerability reporting

## Security

By default it runs without authentication, so do not expose it directly to an untrusted network. For multi-user or externally exposed environments, enable OAuth authentication, `safety.bash_sandbox: always`, and a TLS reverse proxy. See [SECURITY.md](SECURITY.md) for details.

## Server management

```bash
scripts/server.sh start | stop | restart | status | logs
```

## License

[Apache-2.0](LICENSE).