# MAESTRO [English](README.md) | [日本語](README.ja.md)   **MAESTRO** is an agent orchestration platform that runs tasks with LLMs. An LLM classifies each task and routes it to the right workflow (a **Piece**); tools run in a sandboxed runtime, and you manage workspaces, files, and progress from a web UI. It works standalone against any OpenAI-compatible LLM endpoint ([Ollama](https://ollama.com/), vLLM, …). ## Features - **Automatic task routing** — an LLM classifies the request and dispatches it to the best Piece (a YAML workflow). - **Pieces × Movements** — a ReAct loop where the LLM and tools collaborate to advance the task step by step. - **Rich tool set** — files (Read/Write/Edit/Bash/Glob/Grep), Office (PDF/Excel/Docx/PPTX), web fetch, browser automation (Playwright), images, SQLite, knowledge search (RAG), SSH, parallel sub-tasks, MCP integration, more. - **Bash sandbox** — bwrap-based filesystem/network/env isolation, with a hardened whitelist fallback; Python packages are pre-baked. - **Optional LLM Gateway** — a proxy with virtual keys, budgets, and metrics for shared multi-GPU / multi-team use. - **Reflection learning, scheduled tasks, task sharing, OAuth (Google/Gitea)** — all opt-in. - **Web UI** — create tasks, watch progress, preview artifacts, edit settings, manage skills and Pieces. ## Quickstart ### Docker (fastest) ```bash cp .env.example .env # set OLLAMA_BASE_URL / OLLAMA_MODEL docker compose up -d # open http://localhost:9876 ``` Compose binds to `127.0.0.1:9876` only. Before exposing it to other hosts, configure OAuth and put it behind a TLS reverse proxy. > Linux note: `host.docker.internal` may not resolve by default. Use your host's > gateway IP, add `extra_hosts: ["host.docker.internal:host-gateway"]` to > compose, or point at the LAN IP of the machine running Ollama. ### From source ```bash git clone maestro cd maestro npm ci && npm --prefix ui ci npm run setup # interactive: configure the LLM endpoint scripts/build-all.sh scripts/server.sh start # http://localhost:9876 ``` See **[docs/getting-started.md](docs/getting-started.md)** for the full walkthrough. ## Requirements - **Node.js 22+** - **An OpenAI-compatible LLM endpoint** (Ollama / vLLM / …). MAESTRO does not run the model itself. - Optional (Bash sandbox): `bwrap` (bubblewrap, unprivileged user namespaces) plus `python3`/`pip`. ## Documentation - **[docs/getting-started.md](docs/getting-started.md)** — install, first run, first task, auth/sandbox. - **[docs/configuration.md](docs/configuration.md)** — full `config.yaml` reference. - **[docs/architecture.md](docs/architecture.md)** — execution flow, Pieces/Movements, tools, DB, sandbox. - **[docs/docker.md](docs/docker.md)** — Docker deployment (TODO: add). - **[AGENTS.md](AGENTS.md)** / **[CONTRIBUTING.md](CONTRIBUTING.md)** — for contributors. - **[SECURITY.md](SECURITY.md)** — security policy and reporting. ## Security MAESTRO runs without auth by default — do not expose it directly to untrusted networks. For multi-user or public deployments, enable OAuth, `safety.bash_sandbox: always`, and a TLS reverse proxy. See [SECURITY.md](SECURITY.md). ## License [Apache-2.0](LICENSE).