159 lines
8.7 KiB
Markdown
159 lines
8.7 KiB
Markdown
[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` を別途実行する。
|
||
|
||
### 既存環境の更新（`git pull` の後）
|
||
|
||
bare-metal の既存環境を更新するときは次を実行する。
|
||
|
||
```bash
|
||
scripts/upgrade.sh # git pull → 再ビルド（依存 + サーバー + UI）→ 再起動
|
||
```
|
||
|
||
`scripts/server.sh restart` はサーバーしか再ビルドせず、**UI は再ビルドしない**
|
||
（`ui/dist` は gitignore 対象で別途ビルドされる）。npm 依存も更新しない。そのため
|
||
依存やフロントエンドが変わった pull の後にそのまま restart すると、UI バンドルが
|
||
古いまま残ることがある。`scripts/upgrade.sh` は正しい手順を一括で実行する。
|
||
|
||
**ネットワークバインドの移行**も扱う。2026-06-10 以降、サーバーのデフォルトバインドが
|
||
セキュリティのため `0.0.0.0` から `127.0.0.1`（loopback 限定）に変わった（エージェント
|
||
API には Bash ツールが含まれるため、認証なしで LAN に晒すと実質的に認証なし RCE になる）。
|
||
別マシンから MAESTRO にアクセスしていて、更新後に突然 `ERR_CONNECTION_REFUSED` が出る
|
||
場合はこれが原因。`HOST` を明示的に設定し（例: `.env` に `HOST=0.0.0.0`）、先に
|
||
`config.yaml` で認証を有効にすること。upgrade スクリプトはこの状況を検出して設定を
|
||
提案する。
|
||
|
||
## 5. Docker で起動
|
||
|
||
```bash
|
||
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` のコメントを参照。
|
||
|
||
### ブラウザ・セットアップウィザード（`config.yaml` を編集しない）
|
||
|
||
LLM 未設定のまま起動すると、アプリの代わりに**全画面のセットアップウィザード**が出る。`npm run setup` のブラウザ版で、次を順に設定する。
|
||
|
||
1. **LLM** — 接続タイプ・エンドポイントを入れて疎通テスト、モデルを選択。即時反映・再起動不要。
|
||
2. **サーバーポート**（任意）— 再起動で反映。
|
||
3. **サインイン**（任意）— メール＋パスワード（初回 admin）または Google/Gitea OAuth。再起動で反映。
|
||
|
||
ウィザードは admin アカウントを作成できるため、変更系の呼び出しには**ワンタイム・セットアップトークン**が必要。起動時にサーバーログへ出力されるので、次で読み取る。
|
||
|
||
```bash
|
||
docker compose logs | grep "setup token"
|
||
```
|
||
|
||
これをウィザード最初の入力欄に貼る。トークンは初回の無認証ウィンドウ中だけ有効で、LLM を設定した時点（または認証を有効化して再起動した時点）で失効する。非対話で設定したい場合は、`docker compose up` の前に `.env`（`cp .env.example .env`）へ `OLLAMA_BASE_URL` / `OLLAMA_MODEL` を設定しておけば、ウィザードは出ない。
|
||
|
||
## 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) を参照。
|
||
|
||
### ワークスペースを共有する（招待リンク）
|
||
|
||
認証を有効にすると、案件ワークスペースを複数ユーザーで共有できる。メンバー追加のピッカーは
|
||
プライバシー保護のため同じ組織のユーザーしか出ないため、組織を持たないユーザー（例: 管理者が
|
||
ローカル組織を割り当てていない Google ログインユーザー）はピッカーが空になることがある。
|
||
|
||
その場合は **招待リンク** を使う。オーナーまたは管理者がワークスペースの **設定 → メンバー** で
|
||
リンクを発行し、付与する役割（編集者 / 閲覧者）と有効期限（無期限 / 7日 / 30日）を選ぶ。リンクを
|
||
受け取ったログインユーザーは `/ui/invite/<トークン>` を開いて参加する。リンクで付与できるのは
|
||
編集者・閲覧者のみ（オーナー権限は付与不可）。発行・無効化はオーナー / 管理者だけが行える。
|
||
ワークスペースごとに有効なリンクは1本で、再生成すると旧リンクは即座に失効する。無効・期限切れの
|
||
リンクはワークスペース情報を一切返さない。認証なしモードでは招待リンクは無効。
|
||
|
||
## 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) を参照。
|