84 lines
4.4 KiB
Markdown
84 lines
4.4 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.).
|
||
|
||
## 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)
|
||
|
||
```bash
|
||
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`.
|
||
|
||
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).
|