maestro/docs/README.en.draft.md

MAESTRO

English | 日本語

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, 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)

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

git clone <repo-url> 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 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 — install, first run, first task, auth/sandbox.
• docs/configuration.md — full config.yaml reference.
• docs/architecture.md — execution flow, Pieces/Movements, tools, DB, sandbox.
• docs/docker.md — Docker deployment (TODO: add).
• AGENTS.md / CONTRIBUTING.md — for contributors.
• 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.

License

Apache-2.0.