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 依存
cp config.yaml.example config.yaml

3. 最小設定

config.yaml で LLM 接続先とワーカーを設定する。最低限、使用するモデルとエンドポイントを指定すればよい（既定は Ollama http://localhost:11434/v1）。各項目の意味は configuration.md を参照。

主要な環境変数で上書きも可能:

export OLLAMA_BASE_URL=http://localhost:11434/v1
export OLLAMA_MODEL=qwen2.5:14b

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 を別途実行する。

5. Docker で起動

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

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

6. 最初のタスク

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

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

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

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

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

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

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

3.7 KiB Raw Blame History Unescape Escape