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