110 lines
4.4 KiB
Markdown
110 lines
4.4 KiB
Markdown
English | [日本語](getting-started.ja.md)
|
|
|
|
# Getting Started
|
|
|
|
A guide that takes you from launching MAESTRO to running your first task. For setting details see
|
|
[configuration.md](configuration.md), and for the overall structure see [architecture.md](architecture.md).
|
|
|
|
## 1. Prerequisites
|
|
|
|
- **Node.js 22 or later**
|
|
- **An OpenAI-compatible LLM endpoint** — e.g. [Ollama](https://ollama.com/) (`http://localhost:11434/v1`), vLLM, etc. Not needed to build/test MAESTRO itself, but required to run tasks.
|
|
- **Optional (for the Bash sandbox)**: `bwrap` (bubblewrap, with unprivileged user namespaces enabled) and `python3`/`pip`. Enabling it is recommended for multi-user operation ([operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md)).
|
|
|
|
## 2. Install (from source)
|
|
|
|
```bash
|
|
git clone https://gitea.example.com/your-org/maestro.git
|
|
cd maestro
|
|
npm ci # backend dependencies
|
|
npm --prefix ui ci # UI dependencies
|
|
```
|
|
|
|
## 3. Minimal configuration (interactive wizard)
|
|
|
|
`npm run setup` interactively configures the LLM connection target and generates a minimal `config.yaml`.
|
|
|
|
```bash
|
|
npm run setup
|
|
```
|
|
|
|
- Choose the connection type (`direct` = Ollama/vLLM, etc. / `aao_gateway` = via a separate MAESTRO Gateway).
|
|
- Enter the LLM endpoint URL (e.g. `http://localhost:11434/v1`). It checks the connection and lets you select from the discovered models (you can continue by entering a model name manually even if the connection fails).
|
|
- For `aao_gateway`, also enter the API key (`sk-aao-...`) (it is saved in `config.yaml` with permission 0600).
|
|
- Finally, set the listen port of the MAESTRO server (default 9876).
|
|
|
|
Non-interactive (Docker / CI):
|
|
|
|
```bash
|
|
SETUP_LLM_ENDPOINT=http://localhost:11434/v1 SETUP_MODEL=qwen3:14b npm run setup -- --yes
|
|
```
|
|
|
|
```bash
|
|
# Via a separate MAESTRO Gateway
|
|
SETUP_CONNECTION_TYPE=aao_gateway \
|
|
SETUP_LLM_ENDPOINT=http://gateway-host:9876/v1 \
|
|
SETUP_LLM_API_KEY=sk-aao-... \
|
|
SETUP_MODEL=qwen3:14b \
|
|
npm run setup -- --yes
|
|
```
|
|
|
|
For advanced settings (multiple workers, tools, auth, etc.), edit `config.yaml` directly after generation, or use the Settings UI after launch. `config.yaml.example` documents every option.
|
|
|
|
## 4. Build and launch
|
|
|
|
```bash
|
|
scripts/build-all.sh # build the backend (dist/) and the UI (ui/dist/)
|
|
scripts/server.sh start # build + launch (with PID management)
|
|
```
|
|
|
|
Open **http://localhost:9876** in your browser.
|
|
|
|
Server management:
|
|
|
|
```bash
|
|
scripts/server.sh status # check status
|
|
scripts/server.sh logs # tail -f the logs
|
|
scripts/server.sh restart
|
|
scripts/server.sh stop
|
|
```
|
|
|
|
> At the end, `scripts/build-all.sh` automatically pre-bakes the Python packages for the Bash sandbox
|
|
> (`runtime/python-requirements.txt`). To skip this, use
|
|
> `--skip-python`. In environments where writing to the system Python requires permissions, run
|
|
> `sudo bash scripts/prebake-python.sh` separately.
|
|
|
|
## 5. Launch with Docker
|
|
|
|
```bash
|
|
cp .env.example .env # set OLLAMA_BASE_URL / OLLAMA_MODEL
|
|
docker compose up -d
|
|
# http://localhost:9876
|
|
```
|
|
|
|
The DB and workspaces are persisted in named volumes (`maestro-data` / `maestro-workspaces`). By default Compose exposes only `127.0.0.1:9876`. If you want to mount `config.yaml` from the host, see the comments in `docker-compose.yml`.
|
|
|
|
## 6. Your first task
|
|
|
|
1. Open the UI and create a new task (enter a title + the request body).
|
|
2. The LLM classifies the task and automatically routes it to the appropriate Piece (workflow).
|
|
3. Check the Movement progress and tool calls in the Progress tab; preview deliverables in the Output/Files tabs.
|
|
|
|
## 7. Enable authentication (optional)
|
|
|
|
By default it runs without authentication. To use Google / Gitea OAuth, configure the
|
|
`auth` section of `config.yaml` (client ID/secret/callback URL). For details, see the
|
|
[auth section of configuration.md](configuration.md#auth).
|
|
|
|
Do not expose it to an untrusted network until authentication is enabled. When exposing it externally, also use a TLS-enabled
|
|
reverse proxy. For operational caveats, see [../SECURITY.md](../SECURITY.md).
|
|
|
|
## 8. Enable the Bash sandbox (optional, recommended for multi-user)
|
|
|
|
Isolates the agent's Bash execution per task. In production:
|
|
|
|
1. Pre-bake the Python packages on the host: `sudo bash scripts/prebake-python.sh`
|
|
2. Set `safety.bash_sandbox: always` in `config.yaml`
|
|
3. Restart the server
|
|
|
|
For the procedure and troubleshooting, see [operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md).
|