110 lines
5.7 KiB
Markdown
110 lines
5.7 KiB
Markdown
English | [日本語](README.ja.md)
|
||
|
||
# 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](https://ollama.com/) / 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:
|
||
|
||
|
||
|
||
<details>
|
||
<summary>More screenshots — workspaces, chat list, and settings</summary>
|
||
|
||
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:
|
||
|
||
|
||
|
||
</details>
|
||
|
||
## 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).
|
||
|
||
```bash
|
||
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](docs/docker.md)**.
|
||
|
||
### 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/docker.md](docs/docker.md)** — running with Docker Compose (LLM endpoint, persistence, sandbox, troubleshooting)
|
||
- **[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
|
||
- **[docs/security-hardening.md](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](SECURITY.md) for details.
|
||
|
||
## Server management
|
||
|
||
```bash
|
||
scripts/server.sh start | stop | restart | status | logs
|
||
```
|
||
|
||
## License
|
||
|
||
[Apache-2.0](LICENSE).
|