From 00bf2ea16fa176b854b960a0979e6817cd4c3398 Mon Sep 17 00:00:00 2001 From: oss-sync Date: Tue, 16 Jun 2026 03:30:34 +0000 Subject: [PATCH] sync: update from private repo (1a0e50d) --- README.ja.md | 3 + README.md | 3 + docs/docker.ja.md | 107 +++++++++++++++++++++++++++++++++++ docs/docker.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 251 insertions(+) create mode 100644 docs/docker.ja.md create mode 100644 docs/docker.md diff --git a/README.ja.md b/README.ja.md index 60dbee6..81d2bf5 100644 --- a/README.ja.md +++ b/README.ja.md @@ -34,6 +34,8 @@ docker compose up -d Compose は安全のため `127.0.0.1:9876` のみに公開する。別ホストからアクセス可能にする前に OAuth 認証を設定し、TLS 対応のリバースプロキシを配置すること。LLM エンドポイントは `.env` / `config.yaml` で指定する。 +Docker の詳細ガイド（Linux のネットワーク・データ永続化・サンドボックス・トラブルシューティング）は **[docs/docker.md](docs/docker.ja.md)**。 + ### ソースから ```bash @@ -56,6 +58,7 @@ scripts/server.sh start # http://localhost:9876 ## ドキュメント - **[docs/getting-started.md](docs/getting-started.md)** — インストール・初回起動・最初のタスク・認証/サンドボックスの有効化 +- **[docs/docker.md](docs/docker.ja.md)** — Docker Compose での運用（LLM エンドポイント・永続化・サンドボックス・トラブルシューティング） - **[docs/configuration.md](docs/configuration.md)** — `config.yaml` の全設定項目リファレンス - **[docs/architecture.md](docs/architecture.md)** — 実行フロー・Piece/Movement・ツール・DB・サンドボックス - **[docs/tools/](docs/tools/)** — 各ツールの詳細 diff --git a/README.md b/README.md index 76c2845..eca1e25 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ docker compose up -d For safety, Compose exposes only `127.0.0.1:9876`. Before making it reachable from another host, configure OAuth authentication and place a TLS-enabled reverse proxy in front. Specify the LLM endpoint in `.env` / `config.yaml`. +Full Docker guide (Linux networking, data persistence, the sandbox, troubleshooting): **[docs/docker.md](docs/docker.md)**. + ### From source ```bash @@ -56,6 +58,7 @@ For detailed instructions, see **[docs/getting-started.md](docs/getting-started. ## Documentation - **[docs/getting-started.md](docs/getting-started.md)** — installation, first launch, your first task, enabling auth/sandbox +- **[docs/docker.md](docs/docker.md)** — running with Docker Compose (LLM endpoint, persistence, sandbox, troubleshooting) - **[docs/configuration.md](docs/configuration.md)** — full reference of every `config.yaml` setting - **[docs/architecture.md](docs/architecture.md)** — execution flow, Piece/Movement, tools, DB, sandbox - **[docs/tools/](docs/tools/)** — details of each tool diff --git a/docs/docker.ja.md b/docs/docker.ja.md new file mode 100644 index 0000000..0e87738 --- /dev/null +++ b/docs/docker.ja.md @@ -0,0 +1,107 @@ +[English](docker.md) | 日本語 + +# Docker で MAESTRO を動かす + +MAESTRO を最短で動かす方法が Docker Compose です。`git clone` から稼働まで一通りと、つまずきやすい点（Linux のネットワーク、LLM エンドポイント、データ永続化、サンドボックス）をまとめます。 + +## まずはこれだけ + +```bash +cp .env.example .env # OLLAMA_BASE_URL / OLLAMA_MODEL を自分の LLM に向ける +docker compose up -d # 初回はイメージをビルドしてから起動 +# http://localhost:9876 を開く +``` + +Compose は UI を `127.0.0.1:9876` だけに公開するので、初期状態では LAN から到達できません。外部公開は[ローカル以外へ出す](#ローカル以外へ出す)を参照。 + +## コンテナがやること・やらないこと + +- MAESTRO 本体（Web UI・ワーカー・ツール・任意の Gateway）を動かす。 +- LLM は動かさない。既存の OpenAI 互換エンドポイント（Ollama / vLLM / ホスト型ゲートウェイ等）に向ける。 +- ヘッド付きブラウザ一式（Xvfb / x11vnc / Chromium）と Bash サンドボックス（bubblewrap ＋ 事前同梱の Python ツール群）を内蔵。Browser タブとサンドボックス Bash は最初から動く。 + +## LLM エンドポイント + +`.env.example` の既定は、ホスト上の Ollama を指します。 + +```ini +OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 +OLLAMA_MODEL=qwen3:32b +``` + +`host.docker.internal` は Docker Desktop（macOS/Windows）に加え、`docker-compose.yml` が `extra_hosts: host.docker.internal:host-gateway` を設定しているため Linux でも解決できます。通常は変更不要です。 + +LLM が Docker ホスト以外にある場合は向き先を変えます。 + +```ini +# 別マシンの Ollama / vLLM（そのマシンの IP を指定） +OLLAMA_BASE_URL=http://192.0.2.10:11434/v1 +# ホスト型の OpenAI 互換ゲートウェイ +OLLAMA_BASE_URL=https://your-gateway.example.com/v1 +``` + +`OLLAMA_MODEL` のモデルがそのエンドポイントで実際に pull / 配信されていることを確認してください。なければ最初の LLM 呼び出しで失敗します。 + +## 起動の確認 + +```bash +docker compose ps # STATUS が healthy になる +docker compose logs -f maestro # 起動ログを追う。Ctrl-C で停止 +``` + +コンテナは `/health` を叩くヘルスチェックを持ちます。`healthy` になったら を開き、タスクを1つ作って進行することを確認します。LLM エンドポイントが誤っていれば、タスク開始直後にログへ接続エラーが出ます。 + +## データ永続化 + +`docker compose down` やイメージ再ビルドをまたいで残る名前付きボリュームが2つあります。 + +| ボリューム | マウント先 | 保持する内容 | +|--------|-------|-------| +| `maestro-data` | `/app/data` | SQLite DB・ユーザー・スキル・シークレット | +| `maestro-workspaces` | `/workspaces` | タスクごとのエージェント作業領域 | + +`docker compose down -v` はこれらのボリューム（＝全データ）を削除します。残したいときは `-v` を付けないこと。 + +## 設定 + +イメージには動作する `config.yaml`（`config.yaml.example` のコピー）が入っており、`.env` でよく使う項目（LLM エンドポイント・`PORT`）を上書きします。多くの構成では `.env` の編集だけで十分です。 + +`config.yaml` 全体をホスト側で管理し、**Settings UI** の編集をコンテナ再作成後も残したい場合は bind-mount します（`docker-compose.yml` のコメントを外す）。 + +```yaml + volumes: + - ./config.yaml:/app/config.yaml # 先に ./config.yaml を作っておく +``` + +起動前にホスト側のファイルを作成してください（`cp config.yaml.example config.yaml`）。無いと Docker がそのパスに*ディレクトリ*を作ってしまいます。bind-mount しない場合、Settings UI の変更はコンテナ内だけに残り、再作成で失われます。 + +## Docker 内の Bash サンドボックス + +`safety.bash_sandbox` の既定は `auto`（bubblewrap があれば使い、無ければ堅牢な許可リストへフォールバック）。イメージは bubblewrap を同梱するので、サンドボックスは既定で有効です。複数ユーザーや信頼できないワークロードでは `safety.bash_sandbox: always`（bubblewrap が無ければ fail-closed）にします。 + +bubblewrap は非特権ユーザー名前空間を必要とします。多くの新しめのホストでは有効ですが、ホストやコンテナランタイムが無効化している場合、`auto` は堅牢な許可リストへ縮退し、起動時に警告を出します。詳細は [operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md)。 + +## ビルド方式（プレビルトではない） + +`docker compose up` は `Dockerfile` から**ローカルでイメージをビルド**します（公開イメージはありません）。初回ビルドは Chromium と Python ツール群を取得するため数分かかります。以降はキャッシュを再利用します。新しいコードを取得したら `docker compose up -d --build` で再ビルドします。 + +## ローカル以外へ出す + +既定のバインドは意図的にローカル限定です。ネットワークへ公開する前に: + +1. 認証を有効化（OAuth、またはローカルアカウント）。 +2. `safety.bash_sandbox: always` を設定。 +3. TLS を終端（MAESTRO のネイティブ HTTPS か、前段のリバースプロキシ）。 +4. compose のポートマッピングを `127.0.0.1:9876:9876` から、公開したいインターフェースへ変更。 + +完全な堅牢化チェックリストは [SECURITY.md](../SECURITY.md) と [getting-started.md](getting-started.md) を参照。 + +## トラブルシューティング + +| 症状 | 考えられる原因 | +|---------|--------------| +| タスクが接続エラーで即失敗 | `OLLAMA_BASE_URL` にコンテナから到達できない、またはモデルが配信されていない | +| `host.docker.internal` が見つからない（Linux） | compose から `extra_hosts` が消えている、または host-gateway 非対応の古い Docker。ホストの LAN IP を使う | +| `down`/`up` 後に設定が消える | `config.yaml` を bind-mount していない（[設定](#設定)参照） | +| Browser タブ・CAPTCHA プールが不安定 | `/dev/shm` が小さい。compose は `shm_size: 1gb` を設定済み。維持すること | +| 再起動後にデータが全部消えた | `docker compose down -v` を使った（`-v` がボリュームを削除する） | diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 0000000..e81e5ac --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,138 @@ +English | [日本語](docker.ja.md) + +# Running MAESTRO with Docker + +The fastest way to run MAESTRO is Docker Compose. This guide covers the full +path from `git clone` to a working instance, plus the things that commonly trip +people up (Linux networking, the LLM endpoint, data persistence, the sandbox). + +## TL;DR + +```bash +cp .env.example .env # point OLLAMA_BASE_URL/OLLAMA_MODEL at your LLM +docker compose up -d # builds the image on first run, then starts +# open http://localhost:9876 +``` + +Compose publishes the UI on `127.0.0.1:9876` only, so a fresh instance is not +reachable from your LAN. See [Going beyond localhost](#going-beyond-localhost). + +## What the container is (and is not) + +- It runs the **MAESTRO app** (web UI, workers, tools, optional gateway). +- It does **not** run an LLM. You point MAESTRO at an existing + OpenAI-compatible endpoint (Ollama, vLLM, a hosted gateway, …). +- The image bundles the headed-browser stack (Xvfb / x11vnc / Chromium) and the + Bash **sandbox** (bubblewrap + a pre-baked Python toolchain), so the Browser + tab and sandboxed Bash work out of the box. + +## The LLM endpoint + +`.env.example` defaults to an Ollama running on the **host**: + +```ini +OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 +OLLAMA_MODEL=qwen3:32b +``` + +`host.docker.internal` resolves to the host on Docker Desktop (macOS/Windows) +and — because `docker-compose.yml` sets `extra_hosts: host.docker.internal:host-gateway` +— on Linux too. You usually don't need to change anything. + +Point it elsewhere when your LLM is not on the Docker host: + +```ini +# Ollama / vLLM on another machine (use that machine's IP) +OLLAMA_BASE_URL=http://192.0.2.10:11434/v1 +# A hosted OpenAI-compatible gateway +OLLAMA_BASE_URL=https://your-gateway.example.com/v1 +``` + +Make sure the model in `OLLAMA_MODEL` is actually pulled/served by that +endpoint, or task runs will fail at the first LLM call. + +## Verify it's running + +```bash +docker compose ps # STATUS should become healthy +docker compose logs -f maestro # watch startup; Ctrl-C to stop following +``` + +The container has a healthcheck that polls `/health`. Once it reports +`healthy`, open , create a task, and confirm it +progresses. If the LLM endpoint is wrong you'll see connection errors in the +logs as soon as a task starts. + +## Data persistence + +Two named volumes survive `docker compose down` / image rebuilds: + +| Volume | Mount | Holds | +|--------|-------|-------| +| `maestro-data` | `/app/data` | SQLite DB, users, skills, secrets | +| `maestro-workspaces` | `/workspaces` | per-task agent workspaces | + +`docker compose down -v` deletes these volumes (and all your data) — omit `-v` +to keep them. + +## Configuration + +The image ships a runnable `config.yaml` (copied from `config.yaml.example`), +and `.env` overrides the common knobs (LLM endpoint, `PORT`). For most setups, +editing `.env` is all you need. + +To manage the full `config.yaml` from the host (and have **Settings UI** edits +persist across container recreation), bind-mount it — uncomment in +`docker-compose.yml`: + +```yaml + volumes: + - ./config.yaml:/app/config.yaml # create ./config.yaml first +``` + +Create the host file before starting (`cp config.yaml.example config.yaml`), or +Docker will create a *directory* at that path. Without the bind-mount, Settings +UI changes live only inside the container and are lost when it is recreated. + +## The Bash sandbox in Docker + +`safety.bash_sandbox` defaults to `auto`: use bubblewrap when available, fall +back to a hardened allowlist otherwise. The image installs bubblewrap, so the +sandbox is active by default. For multi-user or untrusted workloads set +`safety.bash_sandbox: always` (fail-closed if bubblewrap is unavailable). + +bubblewrap needs unprivileged user namespaces. They are enabled on most modern +hosts; if your host or container runtime disables them, `auto` degrades to the +hardened allowlist and logs a warning at startup. See +[operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md). + +## Build vs. prebuilt image + +`docker compose up` **builds the image locally** from the `Dockerfile` (there is +no published image). The first build downloads Chromium and the Python +toolchain, so expect several minutes; later starts reuse the cached image. +Rebuild after pulling new code with `docker compose up -d --build`. + +## Going beyond localhost + +The default binding is intentionally local-only. Before exposing MAESTRO to a +network: + +1. Enable authentication (OAuth, or local accounts). +2. Set `safety.bash_sandbox: always`. +3. Terminate TLS — either MAESTRO's native HTTPS or a reverse proxy in front. +4. Change the compose port mapping from `127.0.0.1:9876:9876` to the interface + you intend to serve. + +See [SECURITY.md](../SECURITY.md) and +[getting-started.md](getting-started.md) for the full hardening checklist. + +## Troubleshooting + +| Symptom | Likely cause | +|---------|--------------| +| Tasks fail immediately with a connection error | `OLLAMA_BASE_URL` unreachable from the container, or the model isn't served | +| `host.docker.internal` not found (Linux) | `extra_hosts` removed from compose, or an old Docker without host-gateway — use the host's LAN IP | +| Settings changes vanish after `down`/`up` | `config.yaml` not bind-mounted (see [Configuration](#configuration)) | +| Browser tab / CAPTCHA pool unstable | `/dev/shm` too small — compose sets `shm_size: 1gb`; keep it | +| All data gone after restart | used `docker compose down -v` (the `-v` deletes volumes) |