97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
<!-- DRAFT — English README skeleton for OSS. NOT the live README.
|
||
The live public README is oss/overlay/README.md (currently Japanese).
|
||
When ready: translate/expand this, make it oss/overlay/README.md,
|
||
and move the current JA content to oss/overlay/README.ja.md. -->
|
||
|
||
# MAESTRO
|
||
|
||
[English](README.md) | [日本語](README.ja.md)
|
||
|
||
<!-- badges: add CI/build, release, node version; keep license -->
|
||
|
||
|
||
|
||
**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](https://ollama.com/), vLLM, …).
|
||
|
||
<!-- TODO: add 1-2 screenshots here (task detail / settings), e.g.:
|
||
 -->
|
||
|
||
## 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)
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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](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](docs/getting-started.md)** — install, first run, first task, auth/sandbox.
|
||
- **[docs/configuration.md](docs/configuration.md)** — full `config.yaml` reference.
|
||
- **[docs/architecture.md](docs/architecture.md)** — execution flow, Pieces/Movements, tools, DB, sandbox.
|
||
- **[docs/docker.md](docs/docker.md)** — Docker deployment (TODO: add).
|
||
- **[AGENTS.md](AGENTS.md)** / **[CONTRIBUTING.md](CONTRIBUTING.md)** — for contributors.
|
||
- **[SECURITY.md](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](SECURITY.md).
|
||
|
||
## License
|
||
|
||
[Apache-2.0](LICENSE).
|