swallow/maestro
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity
maestro/docs/getting-started.ja.md
oss-sync 77ee3bc426
Some checks are pending
CI / build-and-test (push) Waiting to run
Details
sync: update from private repo (ddadfd71)
2026-07-08 23:35:00 +00:00

8.9 KiB
Raw Blame History

English | 日本語

Getting Started

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

1. 前提

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

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

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 を生成する。

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

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

# 別 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. ビルドと起動

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

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

サーバー管理:

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 の既存環境を更新するときは次を実行する。

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 で起動

docker compose up -d
# http://localhost:9876

DB とワークスペースは named volume（maestro-data / maestro-workspaces）に永続化される。Compose は既定で 9876 を全インターフェースに公開するため、インスタンスは LAN から到達でき、auth を設定するまで認証なしのまま。共有ネットワークに置く前に認証・TLS を有効化するか、ローカル限定にしたい場合はマッピングを 127.0.0.1:9876:9876 に固定する。config.yaml をホストからマウントする場合は docker-compose.yml のコメントを参照。

ブラウザ・セットアップウィザード（config.yaml を編集しない）

LLM 未設定のまま起動すると、アプリの代わりに全画面のセットアップウィザードが出る。npm run setup のブラウザ版で、次を順に設定する。

  1. LLM — 接続タイプ・エンドポイントを入れて疎通テスト、モデルを選択。即時反映・再起動不要。
  2. サーバーポート（任意）— 再起動で反映。
  3. サインイン（任意）— メール＋パスワード（初回 admin）または Google/Gitea OAuth。再起動で反映。

ウィザードは admin アカウントを作成できるため、変更系の呼び出しにはワンタイム・セットアップトークンが必要。起動時にサーバーログへ出力されるので、次で読み取る。

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 セクション を参照。

認証を有効にするまでは信頼できないネットワークへ公開しないこと。外部公開時は TLS 対応のリバースプロキシも使用する。運用上の注意は ../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 を参照。