feat(remote): ship signed cross-platform agents

Author: Ingwannu

.github/workflows/ci.yml

@@ -9,6 +9,8 @@ on:
       - "tests/**"
       - "scripts/**"
       - "gui/**"
+      - "platform/**"
+      - "remote-agent/**"
       - ".gitattributes"
       - ".npmignore"
       - "package.json"
@@ -26,6 +28,8 @@ on:
       - "tests/**"
       - "scripts/**"
       - "gui/**"
+      - "platform/**"
+      - "remote-agent/**"
       - ".gitattributes"
       - ".npmignore"
       - "package.json"
@@ -45,6 +49,70 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  remote-agent:
+    name: Remote Agent ${{ matrix.package }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - package: linux-x64
+            os: ubuntu-24.04
+            target: x86_64-unknown-linux-musl
+            executable: opencodex-remote-agent
+          - package: linux-arm64
+            os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-musl
+            executable: opencodex-remote-agent
+          - package: macos-x64
+            os: macos-15-intel
+            target: x86_64-apple-darwin
+            executable: opencodex-remote-agent
+          - package: macos-arm64
+            os: macos-15
+            target: aarch64-apple-darwin
+            executable: opencodex-remote-agent
+          - package: windows-x64
+            os: windows-latest
+            target: x86_64-pc-windows-msvc
+            executable: opencodex-remote-agent.exe
+          - package: windows-arm64
+            os: windows-11-arm
+            target: aarch64-pc-windows-msvc
+            executable: opencodex-remote-agent.exe
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+
+      - name: Install musl build tools
+        if: ${{ startsWith(matrix.package, 'linux-') }}
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends musl-tools
+
+      - name: Install pinned Rust target
+        working-directory: remote-agent
+        run: rustup target add "${{ matrix.target }}"
+
+      - name: Format
+        working-directory: remote-agent
+        run: cargo fmt --check
+
+      - name: Clippy
+        working-directory: remote-agent
+        run: cargo clippy --locked --target "${{ matrix.target }}" --all-targets -- -D warnings
+
+      - name: Test
+        working-directory: remote-agent
+        run: cargo test --locked --target "${{ matrix.target }}"
+
+      - name: Build release binary
+        working-directory: remote-agent
+        run: cargo build --locked --release --target "${{ matrix.target }}"
+
+      - name: Verify release binary exists
+        shell: bash
+        run: test -s "remote-agent/target/${{ matrix.target }}/release/${{ matrix.executable }}"
+
   test:
     name: ${{ matrix.os }}
     runs-on: ${{ matrix.os }}

.github/workflows/release.yml

@@ -26,7 +26,7 @@ on:
         default: true
       expected-sha:
         description: "Immutable release commit this dispatch must publish (fail if the branch moved)"
-        required: false
+        required: true
         type: string
 
 permissions:
@@ -40,9 +40,78 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  remote-agent-build:
+    name: Remote Agent ${{ matrix.package }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - package: linux-x64
+            os: ubuntu-24.04
+            target: x86_64-unknown-linux-musl
+            executable: opencodex-remote-agent
+          - package: linux-arm64
+            os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-musl
+            executable: opencodex-remote-agent
+          - package: macos-x64
+            os: macos-15-intel
+            target: x86_64-apple-darwin
+            executable: opencodex-remote-agent
+          - package: macos-arm64
+            os: macos-15
+            target: aarch64-apple-darwin
+            executable: opencodex-remote-agent
+          - package: windows-x64
+            os: windows-latest
+            target: x86_64-pc-windows-msvc
+            executable: opencodex-remote-agent.exe
+          - package: windows-arm64
+            os: windows-11-arm
+            target: aarch64-pc-windows-msvc
+            executable: opencodex-remote-agent.exe
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+
+      - name: Install musl build tools
+        if: ${{ startsWith(matrix.package, 'linux-') }}
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends musl-tools
+
+      - name: Install pinned Rust target
+        working-directory: remote-agent
+        run: rustup target add "${{ matrix.target }}"
+
+      - name: Build release binary
+        working-directory: remote-agent
+        run: cargo build --locked --release --target "${{ matrix.target }}"
+
+      - name: Stage release binary
+        shell: bash
+        run: |
+          mkdir -p remote-agent-artifact
+          cp "remote-agent/target/${{ matrix.target }}/release/${{ matrix.executable }}" \
+            "remote-agent-artifact/${{ matrix.executable }}"
+          test -s "remote-agent-artifact/${{ matrix.executable }}"
+
+      - name: Upload unsigned build artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: remote-agent-${{ matrix.package }}
+          path: remote-agent-artifact/${{ matrix.executable }}
+          if-no-files-found: error
+          retention-days: 1
+
   publish:
+    needs: remote-agent-build
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    environment:
+      name: ${{ inputs.dry-run && 'remote-agent-dry-run' || 'remote-agent-release' }}
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
@@ -54,7 +123,8 @@ jobs:
           EXPECTED_SHA: ${{ inputs.expected-sha }}
         run: |
           if [ -z "$EXPECTED_SHA" ]; then
-            echo "::warning::no expected-sha supplied; publishing whatever the branch currently points at"
+            echo "::error::expected-sha is required; refusing to release an unaudited branch tip"
+            exit 1
           elif [ "$GITHUB_SHA" != "$EXPECTED_SHA" ]; then
             echo "::error::branch moved after the release audit (expected ${EXPECTED_SHA}, got ${GITHUB_SHA}) — refusing to publish an unaudited commit"
             exit 1
@@ -92,6 +162,12 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Download platform Agent artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          pattern: remote-agent-*
+          path: remote-agent-artifacts
+
       - name: Verify version matches package.json
         env:
           RELEASE_VERSION: ${{ inputs.version }}
@@ -243,10 +319,51 @@ jobs:
             fi
           fi
 
+      - name: Assemble and sign Remote Agent bundle
+        shell: bash
+        env:
+          REMOTE_AGENT_SIGNING_KEY: ${{ secrets.REMOTE_AGENT_SIGNING_KEY }}
+          DRY_RUN: ${{ inputs.dry-run }}
+        run: |
+          set -euo pipefail
+          signing_key="$RUNNER_TEMP/opencodex-remote-agent-signing.pem"
+          public_key="$RUNNER_TEMP/opencodex-remote-agent-signing.pub.pem"
+          cleanup() {
+            if [ -f "$signing_key" ] && command -v shred >/dev/null 2>&1; then
+              shred -u "$signing_key"
+            else
+              rm -f "$signing_key"
+            fi
+          }
+          trap cleanup EXIT
+          umask 077
+          expected_public_key=""
+          if [ "$DRY_RUN" = "true" ]; then
+            openssl genpkey -algorithm ED25519 -out "$signing_key"
+            openssl pkey -in "$signing_key" -pubout -out "$public_key"
+            expected_public_key="$public_key"
+            echo "OPENCODEX_REMOTE_AGENT_DRY_RUN_PUBLIC_KEY_FILE=$public_key" >> "$GITHUB_ENV"
+          else
+            if [ -z "$REMOTE_AGENT_SIGNING_KEY" ]; then
+              echo "::error::REMOTE_AGENT_SIGNING_KEY is not configured in the protected release environment"
+              exit 1
+            fi
+            printf '%s' "$REMOTE_AGENT_SIGNING_KEY" > "$signing_key"
+          fi
+          REMOTE_AGENT_SIGNING_KEY_FILE="$signing_key" \
+          REMOTE_AGENT_EXPECTED_PUBLIC_KEY_FILE="$expected_public_key" \
+          GITHUB_SHA="$GITHUB_SHA" \
+            bun scripts/remote-agent-bundle.ts assemble \
+              remote-agent-artifacts \
+              bin/remote-agent \
+              .tmp/remote-agent-release
+
       - name: Publish (or dry-run)
         env:
           DRY_RUN: ${{ inputs.dry-run }}
           NPM_DIST_TAG: ${{ inputs.tag }}
+          OPENCODEX_REQUIRE_REMOTE_AGENT_BUNDLE: "1"
+          OPENCODEX_RELEASE_DRY_RUN: ${{ inputs.dry-run }}
         run: |
           if [ "$DRY_RUN" = "true" ]; then
             echo "::notice::DRY RUN — building + packing, not publishing"
@@ -452,5 +569,6 @@ jobs:
             git push origin "refs/tags/${release_tag}"
           fi
 
-          gh release create "$release_tag" --target "$GITHUB_SHA" --title "$release_tag" \
+          gh release create "$release_tag" .tmp/remote-agent-release/* \
+            --target "$GITHUB_SHA" --title "$release_tag" \
             --notes-file "$notes_file" ${prerelease_flag:+$prerelease_flag}

docs-site/src/content/docs/guides/web-dashboard.md

@@ -35,14 +35,14 @@ The **Remote** page makes the local `ocx gui` the start of remote setup:
 
 1. Continue with GitHub. `opencodexpages.me` handles OAuth and asks you to approve the device code.
 2. Set a separate Remote password. GitHub OAuth tokens are not stored or sent to the local PC.
-3. Choose a one-level `<name>.opencodexpages.me` address. The central worker provisions an isolated
-   Cloudflare Tunnel and the page follows `pending`, `awaiting agent`, `connecting`, and `online`.
-4. Pair the signed local helper. Visiting the assigned hostname later requires both the owning
-   GitHub account and the Remote password before the Gateway creates a host-only instance session.
+3. Choose a unique one-level `<name>.opencodexpages.me` address and a unique name for this computer.
+4. Start the signed, unprivileged Agent from the page. It opens one outbound encrypted WSS connection;
+   no root access, port forwarding, or inbound listener is required. Visiting the assigned hostname
+   later requires both the owning GitHub account and the Remote password.
 
-This is currently an invite-only Linux MVP. The privileged signed helper installer and Windows/macOS
-helpers are not shipped in the npm package yet. The GUI reports that limitation instead of claiming
-the Tunnel is online. **Super Sync is not part of this flow.**
+This remains an invite-only beta. Release packages carry signature-verified Agent binaries for Linux,
+macOS, and Windows on x64 and arm64. Unsupported OS/architecture combinations fail honestly instead of
+compiling code on the user's computer. **Super Sync is not part of this flow.**
 
 ## What you can do
 
@@ -58,7 +58,7 @@ the Tunnel is online. **Super Sync is not part of this flow.**
 | **Providers** | Add, edit, enable/disable, and remove providers; manage OAuth account pools and API-key pools where supported. Provider Settings can disable live model discovery for endpoints with missing, slow, or oversized `/models` catalogs. For Claude (Anthropic) OAuth pools, each logged-in account shows its own 5-hour and weekly rate-limit bars (usage is per credential); a failed probe keeps the last-known bars and marks them unavailable until the next successful refresh. |
 | **Add provider** | Search registry-backed presets for account login, API-key services, local servers, or a custom endpoint. |
 | **Codex Auth** | Add ChatGPT/Codex pool accounts, select the next-session account, refresh 5h / weekly / 30d quotas, enable or disable quota auto-switch, set its 1–100% threshold, and configure transient-failure failover. |
-| **Remote** | Connect this PC to the central GitHub identity service, set a separate access password, reserve its hostname, and follow Tunnel/Agent provisioning. |
+| **Remote** | Connect this PC to the central GitHub identity service, set a separate E2EE password, reserve its hostname, and start its signed outbound Agent. |
 | **Subagents** | Feature up to five bare native or namespaced routed models in the `spawn_agent` override list. |
 | **Models** | Toggle native GPT and routed models, set provider allowlists and context caps, choose v1/base/v2, and configure the v2 thread limit. Configured providers stay visible as zero-model groups when discovery is off or returns no rows. |
 | **Logs** | Auto-refresh recent requests with tokens, requested effort and (when available) effective outbound effort, resolved model, provider, status, request id, duration, and error details. The detail view includes the exact reasoning wire field when the adapter emits one. Filter by opaque conversation/session id (when the client sends one) to total tokens and estimated list-price cost for the currently loaded Logs ring. |
@@ -138,7 +138,7 @@ The GUI is a thin client over the proxy's JSON management API. Useful endpoints
 | --- | --- |
 | `GET` / `PUT /api/settings` | Read settings or toggle Codex autostart. |
 | `GET /api/remote/status` · `POST /api/remote/link` · `PUT /api/remote/password` | Read local Remote state, start device approval, and set the separate access password without exposing device or GitHub tokens to the browser. |
-| `POST /api/remote/activate` · `POST /api/remote/pairing-code` · `DELETE /api/remote/device` | Reserve the instance hostname, prepare one-time Agent pairing, or revoke this PC. |
+| `POST /api/remote/activate` · `POST /api/remote/agent/start` · `POST /api/remote/pairing-code` · `DELETE /api/remote/device` | Reserve the workspace/computer names, start the packaged Agent, use the legacy pairing path, or revoke this PC. |
 | `GET /api/startup-health` | Read secret-free routing, service, shim, and restart-safety diagnostics. |
 | `POST /api/startup-action` | Install the background service or Codex launcher shim through fixed, allowlisted actions. |
 | `GET` / `POST /api/windows-tray` | Read or change the Windows tray installation and visible-process state. POST accepts `install`, `start`, `stop`, or `uninstall`. |

docs-site/src/content/docs/ja/guides/web-dashboard.md

@@ -27,10 +27,10 @@ bun run dev:gui
 
 1. GitHub で続行します。`opencodexpages.me` が OAuth を処理し、デバイスコードの承認を求めます。
 2. GitHub パスワードとは別の Remote パスワードを設定します。GitHub OAuth トークンは保存せず、ローカル PC にも送りません。
-3. 1 階層の `<名前>.opencodexpages.me` を選びます。中央 worker が分離された Cloudflare Tunnel を作成し、GUI が `pending` から `online` まで追跡します。
-4. 署名済みローカルヘルパーをペアリングします。割り当て済みアドレスへアクセスする際は、所有者の GitHub アカウントと Remote パスワードを確認してから hostname 専用 session を作ります。
+3. 重複しない 1 階層の `<名前>.opencodexpages.me` と、この PC 固有の名前を選びます。
+4. ページから署名済み非特権 Agent を起動します。Agent は暗号化 outbound WSS 接続を 1 本だけ開くため、root、ポート転送、inbound listener は不要です。割り当て済みアドレスでは所有者の GitHub アカウントと Remote パスワードを確認します。
 
-現在は招待制 Linux MVP です。管理者権限が必要な署名済み helper installer と Windows/macOS helper は npm パッケージにまだ含まれません。GUI はこの制限を隠しません。**Super Sync はこのフローに含まれません。**
+現在は招待制プライベートベータです。release package には Linux、macOS、Windows の x64・arm64 用署名検証済み Agent が含まれます。未対応 OS/architecture ではユーザー PC 上でコンパイルせず明確に停止します。**Super Sync はこのフローに含まれません。**
 
 ## できること
 
@@ -46,7 +46,7 @@ bun run dev:gui
 | **プロバイダー** | プロバイダーを追加、編集、有効化/無効化、削除し、対応する OAuth アカウントプールと API キープールを管理します。Claude（Anthropic）OAuth プールでは、ログイン済みの各アカウントに独自の 5 時間・週間レート制限バーが表示され（利用量は資格情報単位）、取得失敗時は直近の値を保持して一時利用不可と表示します。 |
 | **プロバイダー追加** | レジストリベースのプリセットからアカウントログイン、API キーサービス、ローカルサーバー、custom エンドポイントを検索します。 |
 | **Codex 認証** | ChatGPT/Codex プールアカウントを追加し、次回セッションアカウントを選び、5 時間 / 週間 / 30 日クォータを更新し、クォータ自動切り替えのオン/オフと 1～100% のしきい値、一時的失敗フェイルオーバーを設定します。 |
-| **Remote** | この PC を中央 GitHub ID サービスへ接続し、別のアクセスパスワードと hostname を設定して Tunnel/Agent 状態を追跡します。 |
+| **Remote** | この PC を中央 GitHub ID サービスへ接続し、別の E2EE パスワードと hostname を設定して署名済み outbound Agent を起動します。 |
 | **サブエージェント** | `spawn_agent` オーバーライド一覧にネイティブまたはルーティングモデルを最大 5 つまで優先公開します。 |
 | **モデル** | ネイティブ GPT とルーティングモデルをオン/オフし、プロバイダー許可リストとコンテキスト上限、v1/base/v2、v2 スレッド数を設定します。 |
 | **ログ** | トークン、要求された強度と（利用可能な場合は）実際に送信された強度、実際のモデル、プロバイダー、状態、リクエスト ID、所要時間、エラー詳細を含む最近のリクエストを自動更新します。アダプターが reasoning パラメーターを送信した場合、詳細表示に正確な wire field も表示されます。 |
@@ -111,7 +111,7 @@ GUI はプロキシの JSON 管理 API を使うシンクライアントです
  --- | --- |
 | `GET` / `PUT /api/settings` | 設定を読むか Codex 自動起動をオン/オフします。 |
 | `GET /api/remote/status` · `POST /api/remote/link` · `PUT /api/remote/password` | デバイス/GitHub トークンをブラウザへ公開せず、Remote 状態、デバイス承認、アクセスパスワードを管理します。 |
-| `POST /api/remote/activate` · `POST /api/remote/pairing-code` · `DELETE /api/remote/device` | hostname の予約、一回限りの Agent ペアリング、またはこの PC の失効を行います。 |
+| `POST /api/remote/activate` · `POST /api/remote/agent/start` · `POST /api/remote/pairing-code` · `DELETE /api/remote/device` | workspace/PC 名の予約、同梱 Agent の起動、従来のペアリング経路、またはこの PC の失効を行います。 |
 | `GET /api/startup-health` | 秘密情報を含まないルーティング、サービス、shim、再起動安全性診断を読み取ります。 |
 | `GET` / `POST /api/windows-tray` | Windows トレイの導入・表示状態を読み取り、`install`、`start`、`stop`、`uninstall` を実行します。 |
 | `POST /api/sync` | 共有モデルカタログを再構築し Codex モデルキャッシュを古い状態としてマークします。 |