[English](getting-started.md) | 日本語

# Getting Started

MAESTRO を起動して最初のタスクを動かすまでのガイド。設定項目の詳細は
[configuration.md](configuration.md)、全体構造は [architecture.md](architecture.md) を参照。

## 1. 前提

- **Node.js 22 以上**
- **OpenAI 互換の LLM エンドポイント** — 例: [Ollama](https://ollama.com/)（`http://localhost:11434/v1`）、vLLM など。MAESTRO 自体のビルド/テストには不要だが、タスク実行には必要。
- **任意（Bash サンドボックス用）**: `bwrap`（bubblewrap, 非特権 user namespace が有効なこと）と `python3`/`pip`。マルチユーザー運用では有効化を推奨（[operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md)）。

## 2. インストール（ソースから）

```bash
git clone https://gitea.example.com/your-org/maestro.git
cd maestro
npm ci                 # バックエンド依存
npm --prefix ui ci     # UI 依存
```

## 3. 最小設定（対話ウィザード）

`npm run setup` で LLM 接続先を対話的に設定し、最小の `config.yaml` を生成する。

```bash
npm run setup
```

- 接続タイプ（`direct` = Ollama/vLLM 等 / `aao_gateway` = 別 MAESTRO Gateway 経由）を選ぶ。
- LLM endpoint URL（例 `http://localhost:11434/v1`）を入力。接続を確認し、見つかったモデルから選択できる（接続できなくてもモデル名を手入力して続行可能）。
- `aao_gateway` の場合は API キー（`sk-aao-...`）も入力する（`config.yaml` に保存され、権限は 0600）。
- 最後に MAESTRO サーバーの listen port（既定 9876）を設定する。

非対話（Docker / CI）:

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

```bash
# 別 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
```

詳細設定（複数ワーカー・tools・auth など）は生成後に `config.yaml` を直接編集するか、起動後の Settings UI で行う。`config.yaml.example` に全項目の説明がある。

## 4. ビルドと起動

```bash
scripts/build-all.sh          # バックエンド(dist/) と UI(ui/dist/) をビルド
scripts/server.sh start       # ビルド + 起動（PID 管理付き）
```

ブラウザで **http://localhost:9876** を開く。

サーバー管理:

```bash
scripts/server.sh status      # 状態確認
scripts/server.sh logs        # ログを tail -f
scripts/server.sh restart
scripts/server.sh stop
```

> `scripts/build-all.sh` は最後に Bash サンドボックス用 Python パッケージ
> （`runtime/python-requirements.txt`）を自動でプリベイクする。スキップするには
> `--skip-python`。システム Python への書き込みに権限が要る環境では
> `sudo bash scripts/prebake-python.sh` を別途実行する。

## 5. Docker で起動

```bash
cp .env.example .env          # OLLAMA_BASE_URL / OLLAMA_MODEL を設定
docker compose up -d
# http://localhost:9876
```

DB とワークスペースは named volume（`maestro-data` / `maestro-workspaces`）に永続化される。Compose は既定で `127.0.0.1:9876` のみに公開する。`config.yaml` をホストからマウントする場合は `docker-compose.yml` のコメントを参照。

## 6. 最初のタスク

1. UI を開き、新規タスクを作成（タイトル + 依頼内容を入力）。
2. LLM がタスクを分類し、適切な Piece（ワークフロー）へ自動ルーティングする。
3. 進捗タブで Movement の進行とツール呼び出しを確認、成果物は Output/Files タブでプレビューできる。

## 7. 認証を有効にする（任意）

既定では認証なしで動作する。Google / Gitea の OAuth を使う場合は `config.yaml` の
`auth` セクションを設定する（クライアント ID/シークレット/コールバック URL）。詳細は
[configuration.md の auth セクション](configuration.md#auth) を参照。

認証を有効にするまでは信頼できないネットワークへ公開しないこと。外部公開時は TLS
対応のリバースプロキシも使用する。運用上の注意は [../SECURITY.md](../SECURITY.md) を参照。

## 8. Bash サンドボックスを有効にする（任意・マルチユーザー推奨）

エージェントの Bash 実行をタスク単位で隔離する。本番では:

1. ホストに Python パッケージをプリベイク: `sudo bash scripts/prebake-python.sh`
2. `config.yaml` で `safety.bash_sandbox: always`
3. サーバー再起動

手順とトラブルシュートは [operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md) を参照。