Getting Started

A guide that takes you from launching MAESTRO to running your first task. For setting details see configuration.md, and for the overall structure see architecture.md.

1. Prerequisites

Node.js 22 or later
An OpenAI-compatible LLM endpoint — e.g. Ollama (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).

2. Install (from source)

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.

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

SETUP_LLM_ENDPOINT=http://localhost:11434/v1 SETUP_MODEL=qwen3:14b npm run setup -- --yes

# 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

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:

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

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

Open the UI and create a new task (enter a title + the request body).
The LLM classifies the task and automatically routes it to the appropriate Piece (workflow).
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.

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.

8. Enable the Bash sandbox (optional, recommended for multi-user)

Isolates the agent's Bash execution per task. In production:

Pre-bake the Python packages on the host: sudo bash scripts/prebake-python.sh
Set safety.bash_sandbox: always in config.yaml
Restart the server

For the procedure and troubleshooting, see operations/bash-sandbox-provisioning.md.

4.4 KiB Raw Blame History