codex-webapp 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/ACKNOWLEDGEMENTS.md +11 -37
  2. package/README.ja.md +56 -101
  3. package/README.md +64 -103
  4. package/docs/architecture.md +85 -0
  5. package/docs/clean-release-verification.md +95 -0
  6. package/docs/codex-app-install.md +5 -0
  7. package/docs/distribution-boundary.md +37 -0
  8. package/docs/i18n/README.ko.md +11 -65
  9. package/docs/i18n/README.zh-CN.md +11 -65
  10. package/package.json +9 -2
  11. package/scripts/check-public-package-boundary.mjs +248 -0
  12. package/scripts/verify-clean-release.mjs +492 -0
  13. package/src/appServerBridge.js +150 -0
  14. package/src/appServerMessageCodec.js +12 -0
  15. package/src/auditEvidenceHook.js +18 -0
  16. package/src/bridgeEventEnvelope.js +29 -0
  17. package/src/browserPreload.js +176 -0
  18. package/src/browserSmoke.js +2 -2
  19. package/src/codexAppRenderer.js +12 -0
  20. package/src/codexWeb.js +7 -14
  21. package/src/commands.js +40 -33
  22. package/src/electronBridge.js +324 -0
  23. package/src/localServer.js +184 -0
  24. package/src/projectionManifest.js +8 -0
  25. package/src/rendererAssetSource.js +278 -0
  26. package/docs/assets/codex-webapp-readme-ja.png +0 -0
  27. package/docs/assets/codex-webapp-readme.png +0 -0
package/ACKNOWLEDGEMENTS.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Acknowledgements
2
2
 
3
- Codex WebApp is an unofficial companion package for OpenAI
4
- Codex `remote-control`. It is not affiliated with or endorsed by OpenAI.
3
+ Codex WebApp is an unofficial companion package for OpenAI Codex
4
+ `remote-control`. It is not affiliated with or endorsed by OpenAI.
5
5
 
6
6
  ## OpenAI Codex
7
7
 
@@ -12,41 +12,15 @@ and `codex remote-control`.
12
12
  - Codex App Server documentation:
13
13
  https://github.com/openai/codex/tree/main/codex-rs/app-server
14
14
 
15
- ## Prior Art And Adjacent Projects
16
-
17
- The remote-Codex and mobile-agent ecosystem is moving quickly. The following
18
- projects are useful adjacent references for users and maintainers evaluating the
19
- space:
20
-
21
- - codex-web by 0xcaff: https://github.com/0xcaff/codex-web
22
- - RemCodex: https://remcodex.com/
23
- - Taskdex: https://www.taskdex.app/
24
- - Taskdex GitHub: https://github.com/DhruvalGolakiya/taskdex
25
- - Remodex: https://github.com/Emanuele-web04/remodex
26
- - codexUI: https://github.com/friuns2/codexui
27
- - FlyDex: https://flydex.net/
28
- - The Companion: https://docs.thecompanion.sh/
29
- - MobileCLI: https://www.mobilecli.app/
30
- - RemoteVibeCode: https://remotevibecode.com/
31
- - Nitori Codex Webview:
32
- https://marketplace.visualstudio.com/items?itemName=Kaisei-Yasuzaki.nitori-codex-webview
33
-
34
- Listing a project here is acknowledgement of prior art or adjacency, not a
35
- claim that this package includes that project's code.
36
-
37
- ## codex-web
38
-
39
- `0xcaff/codex-web` is a particularly important reference point for this package.
40
- Its README describes a browser frontend for Codex Desktop running on a machine
41
- the user controls, with a deliberately thin wrapper so upstream Codex changes can
42
- be integrated quickly.
15
+ ## Code Provenance
43
16
 
44
- Codex WebApp follows that same spirit: stay thin, make the install path humane,
45
- keep the operator's machine in control, and avoid pretending to be an official
46
- OpenAI product.
17
+ Codex WebApp ships its own local browser surface, install checks, safety guard,
18
+ and smoke-test workflow. It is intended as a clean public package for Codex App
19
+ users who want a local-first browser entry point.
47
20
 
48
- ## Code Provenance
21
+ ## Related Work
49
22
 
50
- This package is intended as a clean public companion module. Unless a future
51
- file explicitly says otherwise, it does not vendor source code from the projects
52
- listed above.
23
+ The 0xcaff/codex-web project helped clarify the value of keeping the browser
24
+ surface close to the installed Codex renderer instead of rebuilding a separate
25
+ chat UI. Codex WebApp does not vendor, bundle, or depend on that project at
26
+ runtime.
package/README.ja.md CHANGED
@@ -6,51 +6,34 @@
6
6
 
7
7
  [English](./README.md) / 日本語 / [한국어](./docs/i18n/README.ko.md) / [简体中文](./docs/i18n/README.zh-CN.md)
8
8
 
9
- **Codex WebApp は、Codex `0.130.0` で入った `codex remote-control` を、Codex App ユーザーが貼るだけで起動しやすいローカルのブラウザUIにするための非公式 npm package です。** CLI だけでなく、ブラウザ、スマホ、アプリのような画面から Codex を触りたい人に向けて、準備確認、起動、表示確認までを短い導線にまとめます。
9
+ **Codex WebApp は、Codex App ユーザー向けの非公式・ローカルファーストな renderer bridge です。** インストール済み Codex App の `/Applications/Codex.app/Contents/Resources/app.asar` から `webview/` だけを `~/.cache/codex-webapp/` へ抽出し、その renderer を `127.0.0.1` で配信し、最後に smoke test まで行えるようにします。
10
10
 
11
- Codex `0.130.0` では、ヘッドレスでリモート制御可能な app-server を起動しやすくする入口として `codex remote-control` が追加されました。[^1] これは大きな前進ですが、そのリリースだけで誰でもすぐに使えるブラウザUIやスマホ向け体験が同梱されたわけではありません。Codex WebApp はその間を埋めるために、ローカルの Codex を確認し、`localhost` 上で Codex 風のWeb画面を起動し、最後に本当に開けたかを smoke test します。
12
-
13
- ![Codex WebApp の流れ](./docs/assets/codex-webapp-readme-ja.png)
14
-
15
- ## なぜ作ったか
16
-
17
- Codex は、ターミナルだけで完結するツールから、よりアプリらしい操作体験へ広がりつつあります。開発者としては Codex を自分のマシンで動かしつつ、ブラウザ、タブレット、スマホ、あるいは Codex App から自然に操作したいはずです。この package の目的は Codex CLI を置き換えることではありません。目的は、**「remote-control が来たらしい」** から **「ローカルのブラウザUIが起動し、表示確認まで通った」** までを最短にすることです。
18
-
19
- | 欲しい体験 | Codex WebApp が用意するもの |
20
- | --- | --- |
21
- | ターミナルに慣れていなくても始めたい | Codex App に貼るだけで進められるセットアップ用プロンプト。 |
22
- | 起動前に環境を確認したい | `doctor` による Codex CLI、version、`remote-control` の確認。 |
23
- | 安全な既定値で使いたい | デフォルトは `127.0.0.1`。非 loopback host は明示的に許可しない限り拒否。 |
24
- | 動いた証拠が欲しい | `smoke` によるURL確認と、必要に応じたブラウザ screenshot。 |
25
- | 何を起動しているか把握したい | 小さな wrapper と、固定された `codex-web` runtime reference。 |
26
-
27
- > **非公式だが、丁寧に扱うための companion です。** Codex WebApp は OpenAI の公式プロダクトではなく、OpenAI から承認・推奨されたものでもありません。ローカル制御を前提にし、telemetry、analytics、browser extension、project-operated phone-home path を含まない形を目指しています。
11
+ ![Codex WebApp の流れ](./docs/assets/codex-webapp-overview.svg)
28
12
 
29
13
  ## Codex App から始める
30
14
 
31
- Codex App を使っている場合は、次の指示をそのまま貼ってください。Codex が「npm package を一時実行して、ローカルのWeb画面を起動し、ブラウザで開く」ことを認識しやすいように書いてあります。
15
+ Codex App に次を貼ってください。
32
16
 
33
17
  ```text
34
18
  Codex WebApp をこのPCで起動してください。
35
19
 
36
- これは OpenAI 公式ではない、Codex App向けの非公式 companion UI です。
37
- token、cookie、private repository の中身、顧客データ、内部URLは表示しないでください。
38
- `.env` や `SECRET`、`KEY`、`TOKEN` を含むterminal出力は、AIにもissueにも貼らないでください。
20
+ これは Codex App ユーザー向けの非公式ローカル renderer bridge です。
21
+ token、cookie、private repository の中身、顧客データ、内部URL、`.env`、SECRET、KEY、TOKEN を含む内容は表示しないでください。
39
22
 
40
23
  次の順番で進めてください。
41
24
 
42
- 1. まず `node -v`、`npm -v`、`npx -v` を確認してください。`npx` が使えない場合は、ここで止まり、Node.js/npm が必要だと説明してください。
43
- 2. `npx -y codex-webapp@latest doctor` を実行して、Codex CLI が 0.130.0 以上で、`codex remote-control` が使えるか確認してください。
44
- 3. `doctor` がエラーを出した場合は、ここで止まり、`start` には進まず、原因と直し方を説明してください。
45
- 4. `npx -y codex-webapp@latest start --dry-run` を実行して、起動予定の内容を確認してください。
46
- 5. 問題なければ `npx -y codex-webapp@latest start` を実行して、ローカルのブラウザUIを起動してください。
47
- 6. 起動できたら、ブラウザで `http://127.0.0.1:8214/` を開くように案内してください。
48
- 7. この terminal window を閉じるとWeb画面は止まること、止めたいときは `Ctrl+C` を押すこと、PCを再起動した後はもう一度 `npx -y codex-webapp@latest start` が必要なことも説明してください。
25
+ 1. `node -v`、`npm -v`、`npx -v` を確認してください。
26
+ 2. `npx -y codex-webapp@latest doctor` を実行してください。
27
+ 3. doctor が失敗した場合は、start に進まず原因と直し方を説明してください。
28
+ 4. `npx -y codex-webapp@latest start --dry-run` を実行してください。
29
+ 5. 問題なければ `npx -y codex-webapp@latest start` を実行してください。
30
+ 6. 起動できたら `http://127.0.0.1:8214/` をブラウザで開くように案内してください。
31
+ 7. terminal window を閉じるとWeb画面は止まること、PC再起動後はもう一度 start が必要なことも説明してください。
49
32
 
50
- 外出先のPCやスマホから使う場合は、raw UI server をpublic IPへ直接公開せず、Tailscale、Cloudflare Access、または同等の信頼できるアクセス境界を使ってください。認証なしのport-forwardingやpublic tunnelは使わないでください。
33
+ スマホや外出先PCから使う場合は、raw UI server を public IP へ直接公開せず、Tailscale、Cloudflare Access、または同等の信頼できるアクセス境界を使ってください。
51
34
  ```
52
35
 
53
- 実際には、おおむね次のようなコマンドが実行されます。
36
+ 実際にはおおむね次を実行します。
54
37
 
55
38
  ```bash
56
39
  npx -y codex-webapp@latest doctor
@@ -58,51 +41,27 @@ npx -y codex-webapp@latest start --dry-run
58
41
  npx -y codex-webapp@latest start
59
42
  ```
60
43
 
61
- `npx` は、npm に公開されている package を一時的に実行する仕組みです。試すだけなら、この repository を clone したり、手元で新しい project を作ったりする必要はありません。READMEでは、常に公開済みの最新パッチを使うため `codex-webapp@latest` を指定しています。
62
-
63
- > **秘密情報はユーザー側でも確認してください。** Codexには秘密情報を出さないよう指示していますが、AIへの指示だけで安全が保証されるわけではありません。terminal output、`.env`、error log、issue本文を貼る前に、`SECRET`、`KEY`、`TOKEN`、cookie、顧客名、private URL が含まれていないか必ず見てください。
64
-
65
- ## 起動中だけ使える、という基本
66
-
67
- Codex WebApp はクラウド上に常駐するサービスではありません。あなたのPC上で `npx -y codex-webapp@latest start` が動いている間だけ、ブラウザUIが使えます。
68
-
69
- 大事なポイントは、**PCを再起動すると、このプロセスは自動では戻らない**ということです。昨日使えていても、今日PCを再起動した後は、もう一度 `npx -y codex-webapp@latest start` を実行する必要があります。
70
-
71
- | できごと | 何が起きるか | どうすればよいか |
72
- | --- | --- | --- |
73
- | terminal window を閉じた | Web画面は止まります。 | もう一度 `npx -y codex-webapp@latest start` を実行します。 |
74
- | 起動中のUIを止めたい | terminal上のプロセスを止めます。 | 起動しているterminalで `Ctrl+C` を押してください。 |
75
- | PCをスリープした | 復帰後に動く場合もありますが、接続が切れることがあります。 | 開けない場合は起動し直してください。 |
76
- | PCを再起動した | プロセスは残りません。昨日のWeb画面はもう動いていません。 | 再起動後にもう一度 `npx -y codex-webapp@latest start` を実行してください。 |
77
- | 別のPCやスマホから開きたい | `127.0.0.1` は「このPC自身」を指すため、そのままでは別端末から開けません。 | Tailscale、Cloudflare Access、または同等の安全なアクセス境界を用意してください。 |
78
-
79
- まずは同じPCのブラウザで `http://127.0.0.1:8214/` を開けるところまでを確認してください。スマホや外出先PCからの利用は、その次の段階です。認証なしのport-forwardingやpublic tunnelでraw UI serverを公開すると、意図しない第三者にあなたのPC上のCodex操作面を見せる危険があります。
80
-
81
- 毎日使う場合は、PC起動時に自動で `npx -y codex-webapp@latest start` を実行する設定を検討できます。これは「PCを再起動しても、毎回自分でstartし直さなくてよい」ようにするための設定です。ただし、初回セットアップではなく常用者向けです。まず手動起動で `doctor`、`start`、ブラウザ表示、止め方、アクセス境界を確認してから、macOS の Login Items、`launchd`、または自分が管理できるプロセスマネージャーで設定してください。自動起動する場合も、raw UI server を認証なしで外へ出さないでください。
82
-
83
44
  ## ターミナルから始める
84
45
 
85
- 自分でコマンドを実行したい場合は、次の順番で進めてください。Codex WebApp には **Node.js 20 以上** と **Codex CLI 0.130.0 以上** が必要です。
86
-
87
46
  ```bash
88
47
  npx -y codex-webapp doctor
89
48
  npx -y codex-webapp start --dry-run
90
49
  npx -y codex-webapp start
91
50
  ```
92
51
 
93
- デフォルトでは、ローカルマシン上の次のURLでブラウザUIが開きます。
52
+ 起動したら開きます。
94
53
 
95
54
  ```text
96
55
  http://127.0.0.1:8214/
97
56
  ```
98
57
 
99
- UIが起動したら、URLに到達できるかを確認します。
58
+ 表示確認:
100
59
 
101
60
  ```bash
102
61
  npx -y codex-webapp smoke --url http://127.0.0.1:8214/
103
62
  ```
104
63
 
105
- issue や検証用にブラウザの証跡が必要な場合は、screenshot 付きの smoke test を実行できます。
64
+ screenshot 証跡:
106
65
 
107
66
  ```bash
108
67
  npx -y codex-webapp smoke \
@@ -111,48 +70,53 @@ npx -y codex-webapp smoke \
111
70
  --screenshot artifacts/codex-webapp.png
112
71
  ```
113
72
 
114
- ## 内部で何をしているか
73
+ ## 何を起動するか
115
74
 
116
- Codex WebApp は、できるだけ薄い wrapper として作られています。まずローカルの `codex` 実行ファイルが存在するかを確認し、version が `remote-control` に対応しているかを見ます。そのうえで `codex remote-control --help` が動くことを確認し、loopback address 上で Codex 風のWeb画面を起動します。最後に `smoke` でURL到達性を確認するため、セットアップの結果が曖昧になりにくい構成です。
75
+ `codex-webapp start` は、この package に同梱されているローカル renderer bridge を起動します。bridge は、このMacにインストール済みの Codex App から webview を準備し、抽出済み renderer を `~/.cache/codex-webapp/` にcacheし、cache header付きで静的配信します。別runtimeを同梱せず、hosted service でもなく、phone-home もしません。
117
76
 
118
- | コマンド | 目的 | 期待される結果 |
119
- | --- | --- | --- |
120
- | `doctor` | Codex CLI、version、`remote-control` の利用可否を確認します。 | 準備完了の要約、または更新が必要な箇所の説明。 |
121
- | `start --dry-run` | 実際には起動せず、起動予定の内容を表示します。 | ローカルURLと内部で実行する `npx` command。 |
122
- | `start` | 確認後にローカルのブラウザUIを起動します。 | `http://127.0.0.1:8214/` で動くUI。 |
123
- | `start --yes` | 対話確認なしで起動します。 | script や自動化されたローカル検証に便利。 |
124
- | `smoke` | UI URL に到達でき、期待する内容があるかを確認します。 | 速い pass/fail 結果。 |
125
- | `smoke --browser --screenshot ...` | headless browser でUIを開き、証跡を保存します。 | debug や support に使える screenshot。 |
77
+ この package は adapter であり、Codex App 本体ではありません。Codex/OpenAI binaries、`app.asar`、抽出済み `webview/`、token、cookie、signed URL、private session database、private repository contents、customer data は同梱しません。実行時にユーザーのローカル Codex App を読み、`webview/` だけをユーザーのローカル cache に抽出して、そのローカルコピーを配信します。
126
78
 
127
- 現在の runtime reference は次の通りです。
79
+ | コマンド | 目的 |
80
+ | --- | --- |
81
+ | `doctor` | Codex CLI、version、`remote-control` の利用可否を確認します。 |
82
+ | `start --dry-run` | 実際には起動せず、予定URLを表示します。 |
83
+ | `start` | インストール済み Codex App renderer を準備して配信します。 |
84
+ | `start --yes` | 対話確認なしで起動します。 |
85
+ | `smoke` | UI URLが応答し、期待する文字列を含むか確認します。 |
86
+ | `smoke --browser --screenshot ...` | browserで開いて証跡を保存します。 |
128
87
 
129
- ```text
130
- github:0xcaff/codex-web#585613f5a3a355af5aefc388ca4e31b07a472cda
131
- ```
88
+ adapter boundary の開発者向け概要は [Architecture](./docs/architecture.md) を参照してください。
132
89
 
133
- ## 安全性について
90
+ ## 安全性
134
91
 
135
- このブラウザUIは強力です。URLに到達できる人は、そのhost上の Codex を操作できる可能性があります。そのため、Codex WebApp はデフォルトで `127.0.0.1` に bind し、非 loopback host は `--allow-non-loopback` を明示しない限り拒否し、起動前に確認を出します。
92
+ URLに到達できる人は、そのhost上の Codex を操作できる可能性があります。そのため Codex WebApp はデフォルトで `127.0.0.1` に bind し、非 loopback host は `--allow-non-loopback` を明示しない限り拒否します。
136
93
 
137
- | シナリオ | 推奨される境界 |
138
- | --- | --- |
139
- | 同じマシンで使う | デフォルトの `http://127.0.0.1:8214/` のまま使ってください。 |
140
- | 自分のスマホや別PCから使う | Tailscale、Cloudflare Access、または同等の信頼できるアクセス境界を先に用意してください。 |
141
- | public internet から直接見せる | 生のUIサーバーを public IP に直接公開しないでください。 |
142
- | issue で相談する | token、cookie、private repository、customer data、internal URL は必ず redact してください。 |
94
+ raw UI server を public IP に直接公開しないでください。スマホや別PCから使う場合は、Tailscale、Cloudflare Access、WireGuard、SSH tunneling、または同等の信頼できるアクセス境界を先に置いてください。
95
+
96
+ Codex WebApp は telemetry、analytics、browser extension、project-operated phone-home path を含みません。
97
+
98
+ ## 起動中だけ使える
143
99
 
144
- Codex WebApp は telemetry、analytics、browser extension、project-operated phone-home path を含みません。また、extension を入れないため、browser token を extension storage に保存することもありません。
100
+ Codex WebApp はクラウドサービスではありません。`npx -y codex-webapp start` がこのPCで動いている間だけ、ブラウザUIを使えます。
101
+
102
+ | できごと | 何が起きるか | どうするか |
103
+ | --- | --- | --- |
104
+ | terminal window を閉じた | UIは止まります。 | もう一度 `npx -y codex-webapp start` を実行します。 |
105
+ | PCをスリープした | 接続が切れることがあります。 | 開けない場合は起動し直します。 |
106
+ | PCを再起動した | プロセスは残りません。 | 再起動後にもう一度 start します。 |
107
+ | スマホから開きたい | `127.0.0.1` は同じPCだけです。 | 信頼できるアクセス境界を先に用意します。 |
145
108
 
146
109
  ## 必要条件
147
110
 
148
111
  | 項目 | version または補足 |
149
112
  | --- | --- |
150
- | Codex CLI | `codex remote-control` を使うため、`0.130.0` 以上が必要です。 |
151
- | Node.js | `20` 以上が必要です。 |
152
- | network binding | デフォルトは `127.0.0.1`。非 loopback host は明示的な opt-in が必要です。 |
153
- | package channel | npm の `latest` channel から `codex-webapp` を使ってください。現在の release は `0.1.7` です。 |
113
+ | Codex CLI | `0.130.0` 以上。 |
114
+ | Codex App | macOS app として `/Applications/Codex.app` にインストール済み。 |
115
+ | Node.js | `20.11` 以上。 |
116
+ | network binding | デフォルトは `127.0.0.1`。 |
117
+ | package | npm の `codex-webapp`。 |
154
118
 
155
- Codex が入っていない、または古い場合は、先に更新してください。
119
+ Codex が古い場合:
156
120
 
157
121
  ```bash
158
122
  npm install -g @openai/codex@latest
@@ -160,17 +124,9 @@ codex --version
160
124
  codex remote-control --help
161
125
  ```
162
126
 
163
- ## Troubleshooting
127
+ Codex App が標準位置に無い場合は先にインストールするか、`CODEX_APP_PATH` でローカルの `Codex.app` を指定するか、`CODEX_WEBAPP_CODEX_ASAR` でローカルの `app.asar` を指定してください。この package は実行時に `webview/` だけを抽出します。上流rendererファイルは package に含めません。
164
128
 
165
- 多くの失敗は、Codex CLI の有無、version、`remote-control` の有無、port、URL のどれかに集約されます。issue を開く場合は、以下の確認結果を redact したうえで共有してください。
166
-
167
- | 症状 | 最初に見るもの | 次に試すこと |
168
- | --- | --- | --- |
169
- | `Codex CLI was not found` と出る | `codex --version` | Codex CLI を install または update してください。 |
170
- | `remote-control` が使えない | `codex remote-control --help` | Codex CLI `0.130.0` 以上へ更新してください。 |
171
- | UI が開かない | `npx -y codex-webapp start --dry-run` | port の衝突や起動コマンドを確認してください。 |
172
- | smoke test が失敗する | `npx -y codex-webapp smoke --url http://127.0.0.1:8214/` | server が起動中か、URL が正しいかを確認してください。 |
173
- | debug 用の証跡が欲しい | `smoke --browser --screenshot artifacts/codex-webapp.png` | screenshot と redact 済み log を issue に添付してください。 |
129
+ ローカル renderer cache を消したい場合は `~/.cache/codex-webapp/` を削除してください。次に `start` したときに再作成されます。
174
130
 
175
131
  ## Development
176
132
 
@@ -178,18 +134,17 @@ codex remote-control --help
178
134
  npm test
179
135
  npm pack --dry-run
180
136
  npm run start:dry-run
137
+ npm run verify:clean-release
181
138
  ```
182
139
 
140
+ release handoff 前に clean release gate を実行し、redact 済みの証跡を添付してください。詳細は [Clean Release Verification](./docs/clean-release-verification.md) を参照してください。
141
+
183
142
  ## Support
184
143
 
185
144
  issue には OS、shell、Node version、Codex version、実行した command、redact 済みの `doctor` / `start` / `smoke` output を入れてください。token、cookie、private repository contents、customer data、internal URL は public issue に貼らないでください。
186
145
 
187
- 追加の方針は [SECURITY.md](./SECURITY.md)、[SUPPORT.md](./SUPPORT.md)、[ACKNOWLEDGEMENTS.md](./ACKNOWLEDGEMENTS.md) を参照してください。
146
+ [SECURITY.md](./SECURITY.md) と [SUPPORT.md](./SUPPORT.md) も参照してください。
188
147
 
189
148
  ## License
190
149
 
191
150
  [Apache-2.0](./LICENSE.md)
192
-
193
- ## References
194
-
195
- [^1]: [openai/codex Releases: 0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0) では、`codex remote-control` が headless かつ remotely controllable な app-server を起動しやすくする entrypoint として追加されたことが説明されています。
package/README.md CHANGED
@@ -6,77 +6,42 @@
6
6
 
7
7
  [English](./README.md) / [日本語](./README.ja.md) / [한국어](./docs/i18n/README.ko.md) / [简体中文](./docs/i18n/README.zh-CN.md)
8
8
 
9
- **Codex WebApp turns the new `codex remote-control` capability into a local, browser-based Codex surface that Codex App users can start with one pasted instruction.** It is a small, unofficial npm package for people who want the convenience of an app-like UI without giving up the safety of a local-first Codex setup.
9
+ **Codex WebApp is an unofficial, local-first renderer bridge for Codex App users.** It reads the installed Codex App renderer from `/Applications/Codex.app/Contents/Resources/app.asar`, extracts only the `webview/` tree into `~/.cache/codex-webapp/`, serves that renderer on `127.0.0.1`, and gives you a repeatable smoke test.
10
10
 
11
- Codex `0.130.0` added `codex remote-control` as a simpler entrypoint for starting a headless, remotely controllable app-server.[^1] That is an important foundation, but the CLI release does not by itself give every user a ready-to-use browser or phone-friendly experience. Codex WebApp fills that gap by checking your local Codex installation, starting a pinned browser surface on `localhost`, and verifying that the page actually opened.
11
+ ![Codex WebApp flow](./docs/assets/codex-webapp-overview.svg)
12
12
 
13
- ![Codex WebApp flow](./docs/assets/codex-webapp-readme.png)
13
+ ## Quick Start From Codex App
14
14
 
15
- ## Why this exists
16
-
17
- Codex is becoming more useful outside a terminal-only workflow. Developers want to keep Codex running on their machine, but review and control it from a browser, a tablet, a phone, or an app-like surface. The goal of this package is therefore not to replace Codex CLI. The goal is to give Codex App users a simple path from **“I heard remote-control is here”** to **“I have a local browser UI running and smoke-tested.”**
18
-
19
- | Need | What Codex WebApp provides |
20
- | --- | --- |
21
- | A non-terminal entry point | A pasteable Codex App prompt that lets Codex run the setup steps for you. |
22
- | Confidence before starting | `doctor` checks whether Codex CLI is installed and whether `remote-control` is available. |
23
- | A safe default | The UI binds to `127.0.0.1` by default and refuses non-loopback hosts unless you explicitly opt in. |
24
- | A quick proof that it works | `smoke` verifies the local URL and can capture browser evidence when needed. |
25
- | A thin, inspectable wrapper | The runtime is pinned to a known `codex-web` reference rather than hidden behind a large installer. |
26
-
27
- > **Unofficial but respectful.** Codex WebApp is not affiliated with or endorsed by OpenAI. It is designed to stay close to Codex’s local-control model and to avoid telemetry, analytics, browser extensions, or a project-operated phone-home path.
28
-
29
- ## Quick start from Codex App
30
-
31
- If you are using Codex App, paste the following instruction. Codex should perform the checks, run a dry run, start the local UI, and report whether the smoke test passed.
15
+ Paste this into Codex App:
32
16
 
33
17
  ```text
34
- Please set up Codex WebApp on this machine.
18
+ Please start Codex WebApp on this computer.
19
+
20
+ This is an unofficial local renderer bridge for Codex App users.
21
+ Do not print tokens, cookies, private repository contents, customer data, internal URLs, `.env` values, or anything containing SECRET, KEY, or TOKEN.
35
22
 
36
- Use this npm package:
37
- codex-webapp
23
+ Please do this in order:
38
24
 
39
- Please:
40
- 1. Check my Codex version. Codex CLI must be 0.130.0 or newer because this uses `codex remote-control`.
41
- 2. Run the package doctor.
42
- 3. Run start in dry-run mode first.
43
- 4. Start the local browser UI on localhost.
44
- 5. Smoke-test the printed local URL.
25
+ 1. Check `node -v`, `npm -v`, and `npx -v`.
26
+ 2. Run `npx -y codex-webapp@latest doctor`.
27
+ 3. If doctor fails, stop and explain the fix.
28
+ 4. Run `npx -y codex-webapp@latest start --dry-run`.
29
+ 5. If the dry run looks good, run `npx -y codex-webapp@latest start`.
30
+ 6. When it starts, tell me to open `http://127.0.0.1:8214/`.
31
+ 7. Explain that closing this terminal stops the page, and that after a computer restart I need to run start again.
45
32
 
46
- Do not print tokens, cookies, private repo contents, customer data, or internal URLs.
47
- Keep any raw Codex browser server on localhost unless I have a trusted access boundary such as Tailscale or Cloudflare Access.
33
+ For phone or remote access, do not expose the raw UI server directly to a public IP. Use Tailscale, Cloudflare Access, or an equivalent trusted access boundary.
48
34
  ```
49
35
 
50
- Codex will normally run commands like the following.
36
+ Codex will usually run:
51
37
 
52
38
  ```bash
53
- npx -y codex-webapp doctor
54
- npx -y codex-webapp start --dry-run
55
- npx -y codex-webapp start
39
+ npx -y codex-webapp@latest doctor
40
+ npx -y codex-webapp@latest start --dry-run
41
+ npx -y codex-webapp@latest start
56
42
  ```
57
43
 
58
- `npx` runs the published npm package temporarily. You do not need to create a project, clone this repository, or install Codex WebApp by hand just to try it.
59
-
60
- ## It only works while the process is running
61
-
62
- Codex WebApp is not a hosted cloud service. The browser UI is available only while `npx -y codex-webapp start` is running on your computer.
63
-
64
- The important point: **after your computer restarts, that process does not come back automatically.** Even if the browser UI worked yesterday, you need to run `npx -y codex-webapp start` again after a reboot unless you have deliberately configured auto-start.
65
-
66
- | Event | What happens | What to do |
67
- | --- | --- | --- |
68
- | You close the terminal window | The browser UI stops. | Run `npx -y codex-webapp start` again. |
69
- | The computer sleeps | The connection may survive, but it can also break. | Restart the command if the page no longer opens. |
70
- | The computer restarts | The process is gone. Yesterday’s browser UI is no longer running. | Run `npx -y codex-webapp start` again after rebooting. |
71
- | You want to open it from a phone or another PC | `127.0.0.1` means “this same computer,” so another device cannot use that URL directly. | Put Tailscale, Cloudflare Access, or an equivalent trusted access boundary in front first. |
72
-
73
- Start with the same computer first: run the command, then open `http://127.0.0.1:8214/` in that computer’s browser. Phone and remote access should come after that local check passes.
74
-
75
- If you use this every day, you may eventually want an auto-start setup that runs `npx -y codex-webapp start` when the computer starts. Treat that as an advanced, after-the-first-success step. First confirm manual `doctor`, `start`, browser access, how to stop the process, and your trusted access boundary. If you do configure auto-start through Login Items, `launchd`, or a process manager you control, still do not expose the raw UI server without authentication.
76
-
77
- ## Quick start from a terminal
78
-
79
- Use this route if you prefer to control the commands yourself. Codex WebApp requires **Node.js 20 or newer** and **Codex CLI 0.130.0 or newer**.
44
+ ## Terminal Quick Start
80
45
 
81
46
  ```bash
82
47
  npx -y codex-webapp doctor
@@ -84,19 +49,19 @@ npx -y codex-webapp start --dry-run
84
49
  npx -y codex-webapp start
85
50
  ```
86
51
 
87
- By default, the browser UI opens on the local machine at the following URL.
52
+ Then open:
88
53
 
89
54
  ```text
90
55
  http://127.0.0.1:8214/
91
56
  ```
92
57
 
93
- When the page is running, confirm that the browser surface is reachable.
58
+ Verify the page:
94
59
 
95
60
  ```bash
96
61
  npx -y codex-webapp smoke --url http://127.0.0.1:8214/
97
62
  ```
98
63
 
99
- If you need browser evidence for a report or issue, run the browser-backed smoke test and save a screenshot.
64
+ For screenshot evidence:
100
65
 
101
66
  ```bash
102
67
  npx -y codex-webapp smoke \
@@ -105,48 +70,53 @@ npx -y codex-webapp smoke \
105
70
  --screenshot artifacts/codex-webapp.png
106
71
  ```
107
72
 
108
- ## What happens under the hood
73
+ ## What It Runs
109
74
 
110
- Codex WebApp is intentionally small. It first verifies that the local `codex` executable exists, checks that its version supports `remote-control`, and confirms that `codex remote-control --help` works. It then starts a pinned Codex-style web surface on a loopback address and gives you a smoke-test command so the setup ends with a concrete pass/fail signal.
75
+ `codex-webapp start` starts the local renderer bridge shipped by this package. The bridge prepares the Codex App webview from the Codex App already installed on this Mac, caches the extracted renderer under `~/.cache/codex-webapp/`, and serves those static files with cache headers. It does not bundle another runtime, does not start a hosted service, and does not phone home.
111
76
 
112
- | Command | Purpose | Typical result |
113
- | --- | --- | --- |
114
- | `doctor` | Checks Codex CLI, version, and `remote-control` availability. | A readiness summary or a clear update instruction. |
115
- | `start --dry-run` | Shows what would be launched without starting the UI. | A planned local URL and the underlying `npx` command. |
116
- | `start` | Starts the local browser UI after confirmation. | A running UI at `http://127.0.0.1:8214/`. |
117
- | `start --yes` | Starts without the interactive confirmation prompt. | Useful for scripted local setups. |
118
- | `smoke` | Checks whether the UI URL is reachable and contains expected content. | A fast pass/fail result. |
119
- | `smoke --browser --screenshot ...` | Opens the UI in a headless browser and captures evidence. | A screenshot file for debugging or support. |
77
+ This package is the adapter, not Codex App itself. It does not bundle Codex/OpenAI binaries, `app.asar`, a pre-extracted `webview/`, tokens, cookies, signed URLs, private session databases, private repository contents, or customer data. At runtime it reads the user's locally installed Codex App, extracts only `webview/` into the user's local cache, and serves that local copy.
78
+
79
+ | Command | Purpose |
80
+ | --- | --- |
81
+ | `doctor` | Checks Codex CLI, version, and `remote-control` availability. |
82
+ | `start --dry-run` | Shows the planned local URL without starting the server. |
83
+ | `start` | Prepares and serves the installed Codex App renderer. |
84
+ | `start --yes` | Starts without an interactive confirmation prompt. |
85
+ | `smoke` | Checks that the local UI URL responds with expected content. |
86
+ | `smoke --browser --screenshot ...` | Opens the page in a browser and saves evidence. |
120
87
 
121
- Current runtime reference:
88
+ For a developer-friendly overview of the adapter boundary, see [Architecture](./docs/architecture.md).
122
89
 
123
- ```text
124
- github:0xcaff/codex-web#585613f5a3a355af5aefc388ca4e31b07a472cda
125
- ```
90
+ ## Safety Model
126
91
 
127
- ## Safety model
92
+ The UI is powerful because anyone who can reach it may be able to operate Codex on the host machine. Codex WebApp therefore defaults to `127.0.0.1`, refuses non-loopback hosts unless `--allow-non-loopback` is provided, and prints a confirmation before starting.
128
93
 
129
- The browser UI is powerful because anyone who can reach it may be able to operate Codex on the host machine. For that reason, Codex WebApp defaults to `127.0.0.1`, refuses non-loopback hosts unless `--allow-non-loopback` is explicitly provided, and prints a confirmation before starting the UI.
94
+ Do not expose the raw UI server on a public IP. For phone or remote access, put Tailscale, Cloudflare Access, WireGuard, SSH tunneling, or an equivalent trusted boundary in front first.
130
95
 
131
- | Scenario | Recommended boundary |
132
- | --- | --- |
133
- | Same machine | Keep the default `http://127.0.0.1:8214/`. |
134
- | Phone or another computer you control | Use Tailscale, Cloudflare Access, or an equivalent trusted access layer before exposing anything beyond localhost. |
135
- | Public internet | Do not expose the raw UI server directly on a public IP. |
136
- | Support issue | Redact tokens, cookies, private repository contents, customer data, and internal URLs before sharing logs. |
96
+ Codex WebApp does not include telemetry, analytics, a browser extension, or a project-operated phone-home path.
137
97
 
138
- Codex WebApp does not include telemetry, analytics, a browser extension, or a project-operated phone-home path. It also does not store browser tokens in extension storage because it does not install an extension.
98
+ ## It Only Works While The Process Is Running
99
+
100
+ Codex WebApp is not a hosted cloud service. The browser UI exists only while `npx -y codex-webapp start` is running on your computer.
101
+
102
+ | Event | Result | Fix |
103
+ | --- | --- | --- |
104
+ | You close the terminal window | The UI stops. | Run `npx -y codex-webapp start` again. |
105
+ | The computer sleeps | The connection may break. | Restart the command if the page stops opening. |
106
+ | The computer restarts | The process is gone. | Run `npx -y codex-webapp start` again after rebooting. |
107
+ | You want phone access | `127.0.0.1` only works on the same computer. | Add a trusted access boundary first. |
139
108
 
140
109
  ## Requirements
141
110
 
142
111
  | Requirement | Version or note |
143
112
  | --- | --- |
144
- | Codex CLI | `0.130.0` or newer, because `codex remote-control` is required. |
145
- | Node.js | `20` or newer. |
146
- | Network binding | `127.0.0.1` by default. Non-loopback hosts require explicit opt-in. |
147
- | Package channel | `codex-webapp` from the npm `latest` channel. Current release: `0.1.7`. |
113
+ | Codex CLI | `0.130.0` or newer. |
114
+ | Codex App | macOS app installed at `/Applications/Codex.app`. |
115
+ | Node.js | `20.11` or newer. |
116
+ | Binding | `127.0.0.1` by default. |
117
+ | Package | `codex-webapp` from npm. |
148
118
 
149
- If Codex is missing or too old, update it first.
119
+ If Codex is missing or too old:
150
120
 
151
121
  ```bash
152
122
  npm install -g @openai/codex@latest
@@ -154,17 +124,9 @@ codex --version
154
124
  codex remote-control --help
155
125
  ```
156
126
 
157
- ## Troubleshooting
158
-
159
- Most setup failures fall into a small number of categories. Run the commands in this order and share only redacted output if you open an issue.
127
+ If Codex App is missing from the default location, install it first, set `CODEX_APP_PATH` to the local `Codex.app`, or point `CODEX_WEBAPP_CODEX_ASAR` at a local `app.asar`. The package extracts only `webview/` at runtime; renderer files from Codex App are not included in this package.
160
128
 
161
- | Symptom | First check | Likely next step |
162
- | --- | --- | --- |
163
- | `Codex CLI was not found` | `codex --version` | Install or update Codex CLI. |
164
- | `remote-control` is unavailable | `codex remote-control --help` | Upgrade to Codex CLI `0.130.0` or newer. |
165
- | The UI does not open | `npx -y codex-webapp start --dry-run` | Check whether the port is available and whether the launch command is correct. |
166
- | The smoke test fails | `npx -y codex-webapp smoke --url http://127.0.0.1:8214/` | Confirm the server is still running and that you are using the printed URL. |
167
- | You need proof for debugging | `smoke --browser --screenshot artifacts/codex-webapp.png` | Attach the screenshot and redacted logs to an issue. |
129
+ To remove the local renderer cache, delete `~/.cache/codex-webapp/`. It will be prepared again the next time `start` runs.
168
130
 
169
131
  ## Development
170
132
 
@@ -172,18 +134,17 @@ Most setup failures fall into a small number of categories. Run the commands in
172
134
  npm test
173
135
  npm pack --dry-run
174
136
  npm run start:dry-run
137
+ npm run verify:clean-release
175
138
  ```
176
139
 
140
+ Before release handoff, run the clean release gate and attach redacted evidence. See [Clean Release Verification](./docs/clean-release-verification.md).
141
+
177
142
  ## Support
178
143
 
179
144
  Open an issue with your OS, shell, Node version, Codex version, the command you ran, and redacted output from `doctor`, `start`, or `smoke`. Do not paste tokens, cookies, private repository contents, customer data, or internal URLs into a public issue.
180
145
 
181
- See [SECURITY.md](./SECURITY.md), [SUPPORT.md](./SUPPORT.md), and [ACKNOWLEDGEMENTS.md](./ACKNOWLEDGEMENTS.md) for additional guidance.
146
+ See [SECURITY.md](./SECURITY.md) and [SUPPORT.md](./SUPPORT.md).
182
147
 
183
148
  ## License
184
149
 
185
150
  [Apache-2.0](./LICENSE.md)
186
-
187
- ## References
188
-
189
- [^1]: [openai/codex Releases: 0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0) states that `codex remote-control` was added as a simpler entrypoint for starting a headless, remotely controllable app-server.