maestro/README.md

English | 日本語

MAESTRO

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

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

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.

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 — installation, first launch, your first task, enabling auth/sandbox
• docs/configuration.md — full reference of every config.yaml setting
• docs/architecture.md — execution flow, Piece/Movement, tools, DB, sandbox
• docs/tools/ — details of each tool
• docs/operations/bash-sandbox-provisioning.md — how to enable the sandbox in production
• AGENTS.md / CONTRIBUTING.md — for contributors
• CODE_OF_CONDUCT.md — community standards
• 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 for details.

Server management

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

License

Apache-2.0.