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

Screenshots

The workspace — a rail of your workspaces on the left, the chats inside the selected one next to it, and the live conversation with the agent's rendered output filling the rest. Overview, progress, files, and the full trace are one tab away:

More screenshots — workspaces, chat list, and settings

Your personal workspace and each project workspace sit side by side; the same agent runs in every one:

Chats with at-a-glance status (running / waiting / done) and quick filters:

Settings: every config.yaml section as a form — LLM workers, sandbox, auth, tools, and more:

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)

Works on Linux and on Windows via WSL2 (Docker Desktop's WSL integration).

docker compose up -d          # builds on first run, then starts
# open http://localhost:9876

No .env or config.yaml is needed to start: a fresh docker compose up opens a setup wizard in the UI where you point MAESTRO at your LLM. To preset it instead, cp .env.example .env and set OLLAMA_BASE_URL / OLLAMA_MODEL.

Compose publishes 9876 on all interfaces, so a Docker host is reachable from your LAN out of the box — and unauthenticated until you configure it. Before leaving it on a shared network, enable authentication, safety.bash_sandbox: always, and TLS (native server.tls or a reverse proxy); pin the mapping to 127.0.0.1:9876:9876 to keep it local-only. Specify the LLM endpoint in .env / config.yaml.

Full Docker guide (Linux networking, data persistence, the sandbox, troubleshooting): docs/docker.md.

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/docker.md — running with Docker Compose (LLM endpoint, persistence, sandbox, troubleshooting)
• 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
• docs/security-hardening.md — production hardening checklist

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.