WSL で個人用に動かす
Windows の WSL2 で、Agent Fleet を 1 人で試せるように、コマンド 1 つで立ち上げます。 サインインもテナントの選択もなく、ワークスペースは WSL の中の Docker で動きます。
| あなたがやること | 起きること |
|---|---|
| WSL2 のディストリビューションに Docker Engine・Go・Node を入れる | 起動スクリプトでビルドできるようになる |
deploy/local/run-dev.sh wsl を実行する |
ワークスペースのイメージ・Console・Control Plane をビルドし、Control Plane をホストで起動する |
Windows のブラウザで http://localhost:8099 を開く |
サインインなしで Console が開く |
本番向けの Docker Compose と Caddy の構成は、公開ドメインと 80・443 番ポートが要るので、個人で試すのには使いません。
省いているもの
Section titled “省いているもの”| 項目 | この構成での扱い |
|---|---|
| サインイン | AUTH=dev の固定ユーザー dev です。サインインの画面も oauth2-proxy もなく、すべてのリクエストが dev になります。スクリプトが AF_ALLOW_INSECURE_DEV_AUTH=1 も渡します |
| テナント | default のテナントが内部で作られ、dev が自動で入ります。所属が 1 つなので、テナントを選ぶ画面は出ません |
| 暗号化 | AF_MASTER_KEY を設定しないので、保存時の暗号化はオフです。シークレットは平文の JSON で保存されます。個人で試すぶんには許容範囲です |
| ランタイム | AF_RUNTIME=local です。ワークスペースのコンテナは WSL の中の Docker で起動し、本番の形態と同じくコンテナの隔離とワークスペースごとの cgroup の上限があります |
コードを変える必要はありません。どれも run-dev.sh wsl の既定の振る舞いです。
1. 必要なものを入れる
Section titled “1. 必要なものを入れる”WSL2 のディストリビューションの中に入れます。Docker は、WSL2 の中に直接入れた Docker Engine をおすすめします。 Docker Desktop の連携でも動きますが、この構成はホストの Docker と同じ名前空間とパスを前提にしているので、直接入れるほうが合います。
| 入れるもの | 補足 |
|---|---|
| Docker Engine(dockerd) | 下のコマンドで入れます |
| cgroup v2 | --memory の上限とリソースの表示がこれに依存します。最近の WSL2 は既定で v2 です |
| Go | Control Plane をホストでビルドします。https://go.dev/dl/ から入れて PATH に足します |
| Node | Console を Vite でビルドします。nvm をおすすめします |
curl -fsSL https://get.docker.com | sh # docker-ce を入れるsudo usermod -aG docker "$USER" # 以後は sudo なしで docker を使えるsudo service docker start # WSL では systemd がなくても `service` が使える# 新しいシェルを開く。`docker info` が通れば準備完了- systemd を有効にすると(
/etc/wsl.confの[boot]にsystemd=true)、dockerdが自動で起動し、手で起動する手間が省けます
stat -fc %T /sys/fs/cgroup # cgroup2fs と出れば OKcgroup2fsと出なければ、Windows の側でwsl --updateを実行して WSL を新しくします
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash. ~/.nvm/nvm.sh && nvm install --lts2. 起動する
Section titled “2. 起動する”git clone <this-repo> && cd agent-fleetdeploy/local/run-dev.sh wsl # 前の wsl-quickstart.sh はこれを呼ぶだけ(今も使える)スクリプトがすることは次のとおりです。
- 事前チェックをします(docker に接続できるか、cgroup v2、go、npm)
- 共有の JDK を
~/.local/share/agent-fleet/shared/jvmに 1 回だけ展開し、bind mount で渡します(WS_JDK=0で省けます) - ワークスペースのイメージをビルドします
- Console(Vite)と Control Plane(Go)をビルドします
AUTH=dev・AF_RUNTIME=localで Control Plane を起動します
- 初回は、イメージのビルドと JDK の展開に時間がかかります
- イメージはエージェントの CLI を含まない軽量版です。CLI は、ワークスペースの初回の起動のときに決められたバージョンが入ります。
BAKE_AGENT_CLIS=1を付けると、CLI をイメージに組み込んでビルドし、初回の起動を速くできます - 古い
deploy/local/wsl-quickstart.shは、同じものを呼ぶだけの互換のためのスクリプトです
run-dev.sh は、サブコマンドで動作を選びます。
| サブコマンド | 使いどころ |
|---|---|
wsl |
この構成 |
local |
開発の既定(Docker) |
native |
Docker を入れられないとき(下の Docker を入れられないとき) |
reset |
データを消す(下の 止める・消す・ビルドし直す) |
3. ブラウザで開く
Section titled “3. ブラウザで開く”Control Plane は http://localhost:8099 で待ち受けます。WSL2 の localhostForwarding で、Windows の側のブラウザから そのまま開けます。
開いたら、Console でリポジトリをクローンし、Claude のセッションを始めます。
GitHub とつなぐ
Section titled “GitHub とつなぐ”GitHub のクローンとプッシュを OAuth のデバイスフローで使うには、GitHub の OAuth App の client_id を Console に登録します。環境変数は使いません。
- GitHub(Settings → Developer settings → OAuth Apps)で OAuth App を作り、Enable Device Flow をオンにします
- Console のテナント設定で、その
client_idを登録します(連携に使う OAuth アプリを選ぶ)。client_idはシークレットではありません - ワークスペースから GitHub の連携を始めます。デバイスコードと確認の URL が案内されます。
gh auth loginは要りません
- この構成は 1 人に固定で、
AUTHは常にdevです。oauth.envにAUTH=oauthと書いても使われません - 固定ユーザーは配備管理者(super_admin)なので、テナント設定の画面に入れます
- トークン(PAT)を貼り付けても動きます。そのときは何も登録しなくてかまいません
rtk と JDK
Section titled “rtk と JDK”| 項目 | 扱い |
|---|---|
| rtk(トークンを節約する Bash のフック) | ワークスペースの起動のときに、決められたバージョンを入れます(BAKE_AGENT_CLIS=1 ならイメージに組み込んでビルドします)。フックはエントリポイントが自動で用意します |
| JDK | 既定は、イメージを軽く保つ 共有の bind mount(WS_JVM_DIR)です |
どの環境でも、コンテナの中から JDK を入れられます。
workspace-agent install-jdk 21 # 最新の GA の Temurin を ~/.local/share/agent-fleet/jvm に入れる- Console の 設定 → ツールチェーン で Java のバージョンを選ぶと、足りないバージョンを次のコンテナの起動で入れ、各セッションに
JAVA_HOMEを渡します(ツールチェーンを選ぶ) WS_JDK=0で起動すると、共有の JDK を用意せず、この入れ方だけに頼ります- エージェントの CLI と rtk を最新版に追従させる設定も同じタブにあります(エージェントの CLI を最新にする)
止める・消す・ビルドし直す
Section titled “止める・消す・ビルドし直す”| やりたいこと | 操作 |
|---|---|
| 止める | フォアグラウンドの Control Plane を Ctrl-C します。起動したワークスペースのコンテナは残るので、必要なら docker ps・docker stop <name> で止めます |
| データの場所 | ~/.local/share/agent-fleet(DB・ユーザーごとの home・共有の JDK) |
| 消す | Control Plane を止めてから deploy/local/run-dev.sh reset。既定では dev のワークスペース(home と claude-config)だけを消し、DB と共有の JDK は残します。--all で DB と共有の JDK まで消します(JDK は次の実行で用意し直します) |
| ビルドし直す | CLI のバージョンを上げたときなどは、run-dev.sh wsl をもう一度実行します。イメージがビルドし直されます |
reset は、消す前にどちらのランタイムの残り(コンテナ・Agent のプロセス・専用の tmux)も片付けるので、どの形で動かしていても安全です。
Docker を入れられないとき
Section titled “Docker を入れられないとき”WSL2 にどうしても Docker を入れられないときは、ワークスペースをコンテナなしでホストのプロセスとして動かせます(AF_RUNTIME=native、1 人だけ、試験的)。
# tmux / git / claude などの CLI はホストに入れておく(何も同梱されない)deploy/local/run-dev.sh native- コンテナの隔離・メモリの上限・エントリポイントの初期化(claude の自動インストールなど)はありません。承知のうえでのトレードオフです
- ワークスペースの HOME は
~/.local/share/agent-fleet/dev/homeに分かれていて、自分の~には触れません。Windows のエクスプローラーから\\wsl.localhost\<distro>\...で見えます - Docker を使えるなら、1. 必要なものを入れる の構成を選びます
- ビルドツールを入れずに Docker なしで使うなら、ネイティブパッケージ もあります
うまくいかないとき
Section titled “うまくいかないとき”| 症状 | 見るところ |
|---|---|
cannot reach the docker daemon |
sudo service docker start・usermod -aG docker のあと、ログインし直します |
| cgroup が v2 でないという警告 | Windows の側で wsl --update を実行して、WSL のカーネルを新しくします |
| Console のビルドがメモリ不足で落ちる | NODE_OPTIONS=--max-old-space-size=3072(スクリプトが設定済みです)。メモリが厳しいときは、ほかのビルドを止めます |
go・npm がない |
1. 必要なものを入れる のとおりに入れ、PATH を直します(スクリプトは nvm を自動で読み込みます) |
| Java が見つからない | ls -d /usr/lib/jvm/temurin-*-jdk* ~/.local/share/agent-fleet/jvm/temurin-*-jdk*。空なら workspace-agent install-jdk <major> |
エージェントの選択肢に agy がない |
ホストの CPU が使える RDRAND を出しておらず(grep -w rdrand /proc/cpuinfo が空)、回避もうまくいきませんでした。agy は RDRAND が要る FIPS のビルドで、カーネルが命令を取り下げているときは Agent が OpenSSL の CPU 検出から外して動かします。それでも出ないのは、外した状態の agy --version も失敗したか、AF_AGY_RDRAND_MASK=0 でこの回避を無効にしているからです |
エージェント向け
この指示をエージェントに送ると、このページを読ませられます。
https://agent-fleet.org/docs/ja/operate/wsl/index.md を読んで