codex-webapp 0.1.0-beta.1 → 0.1.0-beta.3

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 (3) hide show
  1. package/README.ja.md +95 -66
  2. package/README.md +78 -176
  3. package/package.json +1 -1
package/README.ja.md CHANGED
@@ -1,45 +1,35 @@
1
- > **非公式の community project です。** この project は OpenAI、公式 Codex team、または公式 Codex App と提携・承認・後援・関連していません。
2
-
3
1
  # Codex WebApp
4
2
 
3
+ [![CI](https://github.com/penso-os/codex-webapp/actions/workflows/ci.yml/badge.svg)](https://github.com/penso-os/codex-webapp/actions/workflows/ci.yml)
4
+ [![npm version](https://img.shields.io/npm/v/codex-webapp?label=npm)](https://www.npmjs.com/package/codex-webapp)
5
+ [![npm beta](https://img.shields.io/npm/v/codex-webapp/beta?label=beta)](https://www.npmjs.com/package/codex-webapp)
6
+ [![License](https://img.shields.io/npm/l/codex-webapp)](./LICENSE.md)
7
+
5
8
  [English](./README.md) / 日本語 / [한국어](./docs/i18n/README.ko.md) / [简体中文](./docs/i18n/README.zh-CN.md)
6
9
 
7
- Codex App を使っている人向けの、敬意ある非公式 WebApp surface です。
10
+ **Codex WebApp は、Codex `0.130.0` で入った `codex remote-control` を、Codex App ユーザーが貼るだけで起動しやすいローカルのブラウザUIにするための非公式 npm package です。** CLI だけでなく、ブラウザ、スマホ、アプリのような画面から Codex を触りたい人に向けて、準備確認、起動、表示確認までを短い導線にまとめます。
8
11
 
9
- Codex App に貼れるプロンプト、わかりやすい `doctor`、安全なローカル起動、そして「本当に Codex っぽいブラウザ画面が開けるか」を確認する smoke test をまとめています。
12
+ Codex `0.130.0` では、ヘッドレスでリモート制御可能な app-server を起動しやすくする入口として `codex remote-control` が追加されました。[^1] これは大きな前進ですが、そのリリースだけで誰でもすぐに使えるブラウザUIやスマホ向け体験が同梱されたわけではありません。Codex WebApp はその間を埋めるために、ローカルの Codex を確認し、`localhost` 上で Codex 風のWeb画面を起動し、最後に本当に開けたかを smoke test します。
10
13
 
11
14
  ![Codex WebApp overview](./docs/assets/codex-webapp-overview.svg)
12
15
 
13
- > OpenAI とは提携しておらず、OpenAI から承認・推奨された公式プロダクトではありません。
14
- >
15
- > 生の UI サーバーは原則 `localhost` のまま使ってください。スマホや別PCから触る場合は、Tailscale、Cloudflare Access、または同等の信頼できるアクセス境界を先に用意してください。公開IPへ直接出さないでください。
16
-
17
- ## これは何ですか
18
-
19
- 「Codex をブラウザやスマホから使えるらしい」と聞いたのに、サーバー起動後に何を開けばいいかわからない。そこを埋めるための npm パッケージです。
20
-
21
- この beta でできること:
22
-
23
- - Codex CLI が入っているか確認する
24
- - `codex remote-control --help` が使えるか確認する
25
- - npm の一時実行で `doctor` / `start` / `smoke` を走らせる
26
- - Codex App に貼るだけのプロンプトを提供する
27
- - ローカルの Codex 風ブラウザ UI を起動する
28
- - smoke test で「画面が本当に見えている」ことを確認する
29
-
30
- ## いまの beta の位置づけ
31
-
32
- 現在の npm beta は `codex-webapp@0.1.0-beta.1` です。
16
+ ## なぜ作ったか
33
17
 
34
- これは Codex App の native marketplace plugin、browser extension、one-click installer、managed hosting service ではありません。Codex App にプロンプトを貼り、Codex に `npx` で npm パッケージを実行してもらう形です。
18
+ Codex は、ターミナルだけで完結するツールから、よりアプリらしい操作体験へ広がりつつあります。開発者としては Codex を自分のマシンで動かしつつ、ブラウザ、タブレット、スマホ、あるいは Codex App から自然に操作したいはずです。この package の目的は Codex CLI を置き換えることではありません。目的は、**「remote-control が来たらしい」** から **「ローカルのブラウザUIが起動し、表示確認まで通った」** までを最短にすることです。
35
19
 
36
- 現在の方針は experimental かつ compatibility-first です。現在は `0xcaff/codex-web` の commit `585613f5a3a355af5aefc388ca4e31b07a472cda` を参照する Codex 風 browser runtime を起動し、その周辺に install、safety、evidence、support の層を加えています。この public repository は package、user documentation、safety notes、contribution path に絞ります。
20
+ | 欲しい体験 | Codex WebApp が用意するもの |
21
+ | --- | --- |
22
+ | ターミナルに慣れていなくても始めたい | Codex App に貼るだけで進められるセットアップ用プロンプト。 |
23
+ | 起動前に環境を確認したい | `doctor` による Codex CLI、version、`remote-control` の確認。 |
24
+ | 安全な既定値で使いたい | デフォルトは `127.0.0.1`。非 loopback host は明示的に許可しない限り拒否。 |
25
+ | 動いた証拠が欲しい | `smoke` によるURL確認と、必要に応じたブラウザ screenshot。 |
26
+ | 何を起動しているか把握したい | 小さな wrapper と、固定された `codex-web` runtime reference。 |
37
27
 
38
- 注: 現在、software interface 自体は主に英語です。この日本語ドキュメントは setup を助けるための翻訳です。
28
+ > **非公式だが、丁寧に扱うための companion です。** Codex WebApp は OpenAI の公式プロダクトではなく、OpenAI から承認・推奨されたものでもありません。ローカル制御を前提にし、telemetry、analytics、browser extension、project-operated phone-home path を含まない形を目指しています。
39
29
 
40
- ## Codex App に貼るプロンプト
30
+ ## Codex App から始める
41
31
 
42
- 以下をそのまま Codex App に貼ってください。
32
+ Codex App を使っている場合は、次の指示をそのまま貼ってください。Codex が準備確認、dry-run、ローカルUIの起動、smoke test までを進め、成功・失敗を報告する想定です。
43
33
 
44
34
  ```text
45
35
  Please set up Codex WebApp on this machine.
@@ -48,19 +38,17 @@ Use this npm package:
48
38
  codex-webapp@beta
49
39
 
50
40
  Please:
51
- 1. Check my Codex version.
41
+ 1. Check my Codex version. Codex CLI must be 0.130.0 or newer because this uses `codex remote-control`.
52
42
  2. Run the package doctor.
53
43
  3. Run start in dry-run mode first.
54
- 4. Start the local browser UI only on localhost.
44
+ 4. Start the local browser UI on localhost.
55
45
  5. Smoke-test the printed local URL.
56
46
 
57
- Keep everything on localhost unless I already have Tailscale, Cloudflare Access,
58
- or another trusted access boundary set up.
59
-
60
47
  Do not print tokens, cookies, private repo contents, customer data, or internal URLs.
48
+ Keep any raw Codex browser server on localhost unless I have a trusted access boundary such as Tailscale or Cloudflare Access.
61
49
  ```
62
50
 
63
- Codex は内部でだいたい次のようなコマンドを実行します。
51
+ 実際には、おおむね次のようなコマンドが実行されます。
64
52
 
65
53
  ```bash
66
54
  npx -y codex-webapp@beta doctor
@@ -68,34 +56,31 @@ npx -y codex-webapp@beta start --dry-run
68
56
  npx -y codex-webapp@beta start
69
57
  ```
70
58
 
71
- `npx` は「npm に公開されているパッケージを、一時的に実行するための仕組み」です。ユーザーが手でプロジェクトを作ったり、依存関係を管理したりする必要を減らします。
59
+ `npx` は、npm に公開されている package を一時的に実行する仕組みです。試すだけなら、この repository を clone したり、手元で新しい project を作ったりする必要はありません。
60
+
61
+ ## ターミナルから始める
72
62
 
73
- ## ターミナルで試す場合
63
+ 自分でコマンドを実行したい場合は、次の順番で進めてください。Codex WebApp には **Node.js 20 以上** と **Codex CLI 0.130.0 以上** が必要です。
74
64
 
75
65
  ```bash
76
- codex --version
77
- codex remote-control --help
78
66
  npx -y codex-webapp@beta doctor
79
67
  npx -y codex-webapp@beta start --dry-run
80
68
  npx -y codex-webapp@beta start
81
69
  ```
82
70
 
83
- デフォルトでは次のローカルURLを使います。
71
+ デフォルトでは、ローカルマシン上の次のURLでブラウザUIが開きます。
84
72
 
85
73
  ```text
86
74
  http://127.0.0.1:8214/
87
75
  ```
88
76
 
89
- ## Smoke Test
90
-
91
- UI サーバーを起動したら、次で確認できます。
77
+ UIが起動したら、URLに到達できるかを確認します。
92
78
 
93
79
  ```bash
94
- npx -y codex-webapp@beta smoke \
95
- --url http://127.0.0.1:8214/
80
+ npx -y codex-webapp@beta smoke --url http://127.0.0.1:8214/
96
81
  ```
97
82
 
98
- ブラウザ証跡を撮る場合:
83
+ issue や検証用にブラウザの証跡が必要な場合は、screenshot 付きの smoke test を実行できます。
99
84
 
100
85
  ```bash
101
86
  npx -y codex-webapp@beta smoke \
@@ -104,41 +89,85 @@ npx -y codex-webapp@beta smoke \
104
89
  --screenshot artifacts/codex-webapp.png
105
90
  ```
106
91
 
107
- 公開する証跡には、private repo、branch名、アカウント情報、顧客データ、token、cookie、社内URLを含めないでください。
92
+ ## 内部で何をしているか
93
+
94
+ Codex WebApp は、できるだけ薄い wrapper として作られています。まずローカルの `codex` 実行ファイルが存在するかを確認し、version が `remote-control` に対応しているかを見ます。そのうえで `codex remote-control --help` が動くことを確認し、loopback address 上で Codex 風のWeb画面を起動します。最後に `smoke` でURL到達性を確認するため、セットアップの結果が曖昧になりにくい構成です。
95
+
96
+ | コマンド | 目的 | 期待される結果 |
97
+ | --- | --- | --- |
98
+ | `doctor` | Codex CLI、version、`remote-control` の利用可否を確認します。 | 準備完了の要約、または更新が必要な箇所の説明。 |
99
+ | `start --dry-run` | 実際には起動せず、起動予定の内容を表示します。 | ローカルURLと内部で実行する `npx` command。 |
100
+ | `start` | 確認後にローカルのブラウザUIを起動します。 | `http://127.0.0.1:8214/` で動くUI。 |
101
+ | `start --yes` | 対話確認なしで起動します。 | script や自動化されたローカル検証に便利。 |
102
+ | `smoke` | UI URL に到達でき、期待する内容があるかを確認します。 | 速い pass/fail 結果。 |
103
+ | `smoke --browser --screenshot ...` | headless browser でUIを開き、証跡を保存します。 | debug や support に使える screenshot。 |
104
+
105
+ 現在の runtime reference は次の通りです。
106
+
107
+ ```text
108
+ github:0xcaff/codex-web#585613f5a3a355af5aefc388ca4e31b07a472cda
109
+ ```
110
+
111
+ ## 安全性について
108
112
 
109
- ## 安全境界
113
+ このブラウザUIは強力です。URLに到達できる人は、そのhost上の Codex を操作できる可能性があります。そのため、Codex WebApp はデフォルトで `127.0.0.1` に bind し、非 loopback host は `--allow-non-loopback` を明示しない限り拒否し、起動前に確認を出します。
110
114
 
111
- この package は、危険なネットワーク公開を安全に変える魔法ではありません。
115
+ | シナリオ | 推奨される境界 |
116
+ | --- | --- |
117
+ | 同じマシンで使う | デフォルトの `http://127.0.0.1:8214/` のまま使ってください。 |
118
+ | 自分のスマホや別PCから使う | Tailscale、Cloudflare Access、または同等の信頼できるアクセス境界を先に用意してください。 |
119
+ | public internet から直接見せる | 生のUIサーバーを public IP に直接公開しないでください。 |
120
+ | issue で相談する | token、cookie、private repository、customer data、internal URL は必ず redact してください。 |
112
121
 
113
- 推奨:
122
+ Codex WebApp は telemetry、analytics、browser extension、project-operated phone-home path を含みません。また、extension を入れないため、browser token を extension storage に保存することもありません。
114
123
 
115
- - 自分のMacだけで使うなら `localhost`
116
- - 自分の端末間だけなら Tailscale
117
- - 複数人で使うなら Cloudflare Access などの identity-aware proxy
124
+ ## 必要条件
118
125
 
119
- 避けること:
126
+ | 項目 | version または補足 |
127
+ | --- | --- |
128
+ | Codex CLI | `codex remote-control` を使うため、`0.130.0` 以上が必要です。 |
129
+ | Node.js | `20` 以上が必要です。 |
130
+ | network binding | デフォルトは `127.0.0.1`。非 loopback host は明示的な opt-in が必要です。 |
131
+ | package channel | beta 中は `codex-webapp@beta` を使ってください。 |
120
132
 
121
- - 生の UI サーバーを public IP に出す
122
- - token / cookie / customer data / private repo 内容を public issue に貼る
123
- - OpenAI 公式プロダクトのように見せる
124
- - 現在の beta を managed hosting service として扱う
133
+ Codex が入っていない、または古い場合は、先に更新してください。
125
134
 
126
- ## Security And Privacy
135
+ ```bash
136
+ npm install -g @openai/codex@latest
137
+ codex --version
138
+ codex remote-control --help
139
+ ```
127
140
 
128
- この package は open source で、監査可能であることを前提にしています。
141
+ ## Troubleshooting
129
142
 
130
- CLI wrapper は、prompt、repository、token、cookie、customer data を、この project が運営する第三者サーバーへ送信しません。ローカルの Codex 風 browser surface を起動し、指定された URL に対して readiness / smoke check を行います。
143
+ 多くの失敗は、Codex CLI の有無、version、`remote-control` の有無、port、URL のどれかに集約されます。issue を開く場合は、以下の確認結果を redact したうえで共有してください。
131
144
 
132
- この package は browser extension をインストールせず、browser token を `localStorage`、`chrome.storage`、extension profile に保存しません。ただし、下層の Codex 風 runtime や、利用者自身が用意する trusted-access layer には別の挙動があり得ます。運用境界として確認してください。
145
+ | 症状 | 最初に見るもの | 次に試すこと |
146
+ | --- | --- | --- |
147
+ | `Codex CLI was not found` と出る | `codex --version` | Codex CLI を install または update してください。 |
148
+ | `remote-control` が使えない | `codex remote-control --help` | Codex CLI `0.130.0` 以上へ更新してください。 |
149
+ | UI が開かない | `npx -y codex-webapp@beta start --dry-run` | port の衝突や起動コマンドを確認してください。 |
150
+ | smoke test が失敗する | `npx -y codex-webapp@beta smoke --url http://127.0.0.1:8214/` | server が起動中か、URL が正しいかを確認してください。 |
151
+ | debug 用の証跡が欲しい | `smoke --browser --screenshot artifacts/codex-webapp.png` | screenshot と redact 済み log を issue に添付してください。 |
133
152
 
134
- public issue や screenshot を共有する前に、secret と private URL は削除してください。
153
+ ## Development
135
154
 
136
- ## 謝辞
155
+ ```bash
156
+ npm test
157
+ npm pack --dry-run
158
+ npm run start:dry-run
159
+ ```
137
160
 
138
- 現在の beta は、Codex 風ブラウザ体験を実現する public project `0xcaff/codex-web` のアプローチを利用・参照しています。この repository は、その周辺に配布、doctor、安全境界、ドキュメント、検証証跡の層を加えるものです。
161
+ ## Support
139
162
 
140
- 詳しくは [ACKNOWLEDGEMENTS.md](./ACKNOWLEDGEMENTS.md) を参照してください。
163
+ issue には OS、shell、Node version、Codex version、実行した command、redact 済みの `doctor` / `start` / `smoke` output を入れてください。token、cookie、private repository contents、customer data、internal URL は public issue に貼らないでください。
164
+
165
+ 追加の方針は [SECURITY.md](./SECURITY.md)、[SUPPORT.md](./SUPPORT.md)、[ACKNOWLEDGEMENTS.md](./ACKNOWLEDGEMENTS.md) を参照してください。
141
166
 
142
167
  ## License
143
168
 
144
169
  [Apache-2.0](./LICENSE.md)
170
+
171
+ ## References
172
+
173
+ [^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
@@ -1,7 +1,3 @@
1
- > **Unofficial community project.** This project is not affiliated with,
2
- > sponsored by, endorsed by, or associated with OpenAI, the official Codex team,
3
- > or the official Codex App.
4
-
5
1
  # Codex WebApp
6
2
 
7
3
  [![CI](https://github.com/penso-os/codex-webapp/actions/workflows/ci.yml/badge.svg)](https://github.com/penso-os/codex-webapp/actions/workflows/ci.yml)
@@ -9,64 +5,31 @@
9
5
  [![npm beta](https://img.shields.io/npm/v/codex-webapp/beta?label=beta)](https://www.npmjs.com/package/codex-webapp)
10
6
  [![License](https://img.shields.io/npm/l/codex-webapp)](./LICENSE.md)
11
7
 
12
- A respectful, community-maintained web app surface for Codex App users.
13
-
14
- It gives you a pasteable Codex App prompt, a friendly `doctor`, a safe local
15
- launcher, and smoke tests that prove a real Codex-style browser surface is
16
- reachable from a machine you control.
17
-
18
- ![Codex WebApp overview](./docs/assets/codex-webapp-overview.svg)
19
-
20
- > Not affiliated with or endorsed by OpenAI.
21
- >
22
- > Keep the raw UI server on `localhost` unless you have Tailscale, Cloudflare
23
- > Access, or an equivalent trusted access boundary. Do not put the raw server on
24
- > a public IP.
25
-
26
- Quick check:
27
-
28
- ```bash
29
- npx -y codex-webapp@beta doctor
30
- ```
31
-
32
- ## Languages
33
-
34
- - English: this README
35
- - Japanese: [README.ja.md](./README.ja.md)
36
- - Korean: [docs/i18n/README.ko.md](./docs/i18n/README.ko.md)
37
- - Simplified Chinese: [docs/i18n/README.zh-CN.md](./docs/i18n/README.zh-CN.md)
8
+ [English](./README.md) / [日本語](./README.ja.md) / [한국어](./docs/i18n/README.ko.md) / [简体中文](./docs/i18n/README.zh-CN.md)
38
9
 
39
- ## Who This Is For
10
+ **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.
40
11
 
41
- This package is for people who opened Codex App, heard that Codex can be used
42
- from a browser or phone, and then got stuck at "the server is running, but what
43
- do I open?"
12
+ 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.
44
13
 
45
- It is also for maintainers who want a repeatable public-beta gate:
46
-
47
- - check the local Codex install
48
- - start the Codex-style browser UI on a safe local port
49
- - verify the page with HTTP or browser smoke tests
50
- - collect evidence before sharing a beta package
51
- - document the trusted-access boundary instead of improvising it in DMs
14
+ ![Codex WebApp overview](./docs/assets/codex-webapp-overview.svg)
52
15
 
53
- ## Current Beta Shape
16
+ ## Why this exists
54
17
 
55
- Current npm beta: `codex-webapp@0.1.0-beta.1`
18
+ 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.”**
56
19
 
57
- This is an npm package that Codex App can run through a prompt. It is not a
58
- native Codex App marketplace plugin, browser extension, one-click installer, or
59
- managed hosting service.
20
+ | Need | What Codex WebApp provides |
21
+ | --- | --- |
22
+ | A non-terminal entry point | A pasteable Codex App prompt that lets Codex run the setup steps for you. |
23
+ | Confidence before starting | `doctor` checks whether Codex CLI is installed and whether `remote-control` is available. |
24
+ | A safe default | The UI binds to `127.0.0.1` by default and refuses non-loopback hosts unless you explicitly opt in. |
25
+ | A quick proof that it works | `smoke` verifies the local URL and can capture browser evidence when needed. |
26
+ | A thin, inspectable wrapper | The runtime is pinned to a known `codex-web` reference rather than hidden behind a large installer. |
60
27
 
61
- The current beta is experimental and compatibility-first. It launches a pinned
62
- Codex-style web runtime reference, currently `0xcaff/codex-web` at commit
63
- `585613f5a3a355af5aefc388ca4e31b07a472cda`, and wraps it with clearer install,
64
- safety, evidence, and support behavior. The public repository is kept focused on
65
- the package, user documentation, safety notes, and contribution path.
28
+ > **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.
66
29
 
67
- ## Codex App Quick Start
30
+ ## Quick start from Codex App
68
31
 
69
- Paste this into Codex App:
32
+ 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.
70
33
 
71
34
  ```text
72
35
  Please set up Codex WebApp on this machine.
@@ -75,19 +38,17 @@ Use this npm package:
75
38
  codex-webapp@beta
76
39
 
77
40
  Please:
78
- 1. Check my Codex version.
41
+ 1. Check my Codex version. Codex CLI must be 0.130.0 or newer because this uses `codex remote-control`.
79
42
  2. Run the package doctor.
80
43
  3. Run start in dry-run mode first.
81
- 4. Start the local browser UI only on localhost.
44
+ 4. Start the local browser UI on localhost.
82
45
  5. Smoke-test the printed local URL.
83
46
 
84
- Keep everything on localhost unless I already have Tailscale, Cloudflare Access,
85
- or another trusted access boundary set up.
86
-
87
47
  Do not print tokens, cookies, private repo contents, customer data, or internal URLs.
48
+ Keep any raw Codex browser server on localhost unless I have a trusted access boundary such as Tailscale or Cloudflare Access.
88
49
  ```
89
50
 
90
- Codex should run commands like these for you:
51
+ Codex will normally run commands like the following.
91
52
 
92
53
  ```bash
93
54
  npx -y codex-webapp@beta doctor
@@ -95,49 +56,31 @@ npx -y codex-webapp@beta start --dry-run
95
56
  npx -y codex-webapp@beta start
96
57
  ```
97
58
 
98
- If Codex App asks what `npx` means, the plain-English answer is:
59
+ `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.
99
60
 
100
- > `npx` runs a published npm package temporarily, without asking you to install
101
- > or manage a project by hand.
61
+ ## Quick start from a terminal
102
62
 
103
- ## Terminal Quick Start
104
-
105
- Developers can run the same flow from a terminal:
63
+ 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**.
106
64
 
107
65
  ```bash
108
- # 1. Confirm Codex is available.
109
- codex --version
110
-
111
- # 2. Check whether the remote-control command exists.
112
- codex remote-control --help
113
-
114
- # 3. Run the friendly readiness check.
115
66
  npx -y codex-webapp@beta doctor
116
-
117
- # 4. Preview the launcher command without starting anything.
118
67
  npx -y codex-webapp@beta start --dry-run
119
-
120
- # 5. Start the local Codex-style browser UI.
121
68
  npx -y codex-webapp@beta start
122
69
  ```
123
70
 
124
- By default the browser UI is local only:
71
+ By default, the browser UI opens on the local machine at the following URL.
125
72
 
126
73
  ```text
127
74
  http://127.0.0.1:8214/
128
75
  ```
129
76
 
130
- ## Browser Smoke Test
131
-
132
- Once the UI server is running:
77
+ When the page is running, confirm that the browser surface is reachable.
133
78
 
134
79
  ```bash
135
- npx -y codex-webapp@beta smoke \
136
- --url http://127.0.0.1:8214/
80
+ npx -y codex-webapp@beta smoke --url http://127.0.0.1:8214/
137
81
  ```
138
82
 
139
- The lightweight smoke test fetches the page and checks for the expected
140
- Codex-style surface. To capture browser evidence:
83
+ If you need browser evidence for a report or issue, run the browser-backed smoke test and save a screenshot.
141
84
 
142
85
  ```bash
143
86
  npx -y codex-webapp@beta smoke \
@@ -146,85 +89,66 @@ npx -y codex-webapp@beta smoke \
146
89
  --screenshot artifacts/codex-webapp.png
147
90
  ```
148
91
 
149
- If Playwright is missing:
92
+ ## What happens under the hood
150
93
 
151
- ```bash
152
- npm install -D playwright
153
- npx playwright install chromium
154
- ```
155
-
156
- Public evidence must use a clean or demo environment. Do not publish screenshots
157
- that expose private repositories, private branches, account metadata, customer
158
- data, tokens, cookies, or internal URLs.
94
+ 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.
159
95
 
160
- ## Safety Boundary
96
+ | Command | Purpose | Typical result |
97
+ | --- | --- | --- |
98
+ | `doctor` | Checks Codex CLI, version, and `remote-control` availability. | A readiness summary or a clear update instruction. |
99
+ | `start --dry-run` | Shows what would be launched without starting the UI. | A planned local URL and the underlying `npx` command. |
100
+ | `start` | Starts the local browser UI after confirmation. | A running UI at `http://127.0.0.1:8214/`. |
101
+ | `start --yes` | Starts without the interactive confirmation prompt. | Useful for scripted local setups. |
102
+ | `smoke` | Checks whether the UI URL is reachable and contains expected content. | A fast pass/fail result. |
103
+ | `smoke --browser --screenshot ...` | Opens the UI in a headless browser and captures evidence. | A screenshot file for debugging or support. |
161
104
 
162
- This package does not make an unsafe network setup safe.
105
+ Current runtime reference:
163
106
 
164
- Use one of these boundaries:
165
-
166
- - `localhost` only for local use
167
- - Tailscale for private-device access
168
- - Cloudflare Access or an equivalent identity-aware proxy for shared access
169
-
170
- Do not:
107
+ ```text
108
+ github:0xcaff/codex-web#585613f5a3a355af5aefc388ca4e31b07a472cda
109
+ ```
171
110
 
172
- - expose a raw Codex UI server on a public IP
173
- - paste tokens, cookies, customer data, or private repository contents into
174
- public issues
175
- - describe this project as an official OpenAI or Codex product
176
- - treat the current beta as a managed hosting service
111
+ ## Safety model
177
112
 
178
- ## Security And Privacy
113
+ 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.
179
114
 
180
- This package is open source and intended to be auditable.
115
+ | Scenario | Recommended boundary |
116
+ | --- | --- |
117
+ | Same machine | Keep the default `http://127.0.0.1:8214/`. |
118
+ | Phone or another computer you control | Use Tailscale, Cloudflare Access, or an equivalent trusted access layer before exposing anything beyond localhost. |
119
+ | Public internet | Do not expose the raw UI server directly on a public IP. |
120
+ | Support issue | Redact tokens, cookies, private repository contents, customer data, and internal URLs before sharing logs. |
181
121
 
182
- The CLI wrapper does not send your prompts, repositories, tokens, cookies, or
183
- customer data to a third-party service operated by this project. It launches a
184
- local Codex-style browser surface and runs local readiness/smoke checks against
185
- the URL you provide.
122
+ 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.
186
123
 
187
- This package does not install a browser extension and does not write browser
188
- tokens to `localStorage`, `chrome.storage`, or an extension profile. The
189
- underlying Codex-style runtime and your own trusted-access layer may have their
190
- own behavior; review and operate those components as part of your deployment
191
- boundary.
124
+ ## Requirements
192
125
 
193
- Codex WebApp does not include telemetry, analytics, or a project-operated
194
- phone-home path.
126
+ | Requirement | Version or note |
127
+ | --- | --- |
128
+ | Codex CLI | `0.130.0` or newer, because `codex remote-control` is required. |
129
+ | Node.js | `20` or newer. |
130
+ | Network binding | `127.0.0.1` by default. Non-loopback hosts require explicit opt-in. |
131
+ | Package channel | `codex-webapp@beta` while the package is in beta. |
195
132
 
196
- For public support, remove secrets and private URLs before sharing command
197
- output or screenshots.
133
+ If Codex is missing or too old, update it first.
198
134
 
199
- ## Product Principles
135
+ ```bash
136
+ npm install -g @openai/codex@latest
137
+ codex --version
138
+ codex remote-control --help
139
+ ```
200
140
 
201
- ![Mobile and trusted-access concept](./docs/assets/codex-webapp-mobile.svg)
141
+ ## Troubleshooting
202
142
 
203
- - **Codex App first**: the primary path is a prompt a non-CLI user can paste
204
- into Codex App.
205
- - **Compatibility first**: staying close to the Codex browser experience is more
206
- valuable than a custom UI that drifts quickly.
207
- - **Security owned**: the public package must keep the raw server local and make
208
- trusted access explicit.
209
- - **Evidence driven**: launch claims must be backed by doctor, dry-run, smoke,
210
- browser, and clean-sandbox evidence.
211
- - **Contribution friendly**: the repo should be easy to inspect, test, and
212
- improve without needing private maintainer context.
143
+ 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.
213
144
 
214
- ## Repository Layout
215
-
216
- ```text
217
- bin/codex-webapp.mjs CLI entrypoint for doctor/start/smoke
218
- src/commands.js CLI command handlers
219
- src/browserSmoke.js HTTP and optional Playwright smoke checks
220
- src/codexWeb.js Codex-style web launch arguments and safety checks
221
- src/version.js Codex CLI version parsing and readiness checks
222
- test/*.test.mjs node:test coverage
223
- docs/assets/ public-safe README visuals
224
- docs/i18n/ localized quickstart docs
225
- docs/codex-app-install.md Codex App prompt-driven setup guide
226
- docs/ja-quickstart.md Japanese quickstart guide
227
- ```
145
+ | Symptom | First check | Likely next step |
146
+ | --- | --- | --- |
147
+ | `Codex CLI was not found` | `codex --version` | Install or update Codex CLI. |
148
+ | `remote-control` is unavailable | `codex remote-control --help` | Upgrade to Codex CLI `0.130.0` or newer. |
149
+ | The UI does not open | `npx -y codex-webapp@beta start --dry-run` | Check whether the port is available and whether the launch command is correct. |
150
+ | The smoke test fails | `npx -y codex-webapp@beta smoke --url http://127.0.0.1:8214/` | Confirm the server is still running and that you are using the printed URL. |
151
+ | You need proof for debugging | `smoke --browser --screenshot artifacts/codex-webapp.png` | Attach the screenshot and redacted logs to an issue. |
228
152
 
229
153
  ## Development
230
154
 
@@ -236,36 +160,14 @@ npm run start:dry-run
236
160
 
237
161
  ## Support
238
162
 
239
- Open a GitHub issue with:
240
-
241
- - your OS
242
- - Node version
243
- - Codex version
244
- - the exact command you ran
245
- - the doctor or smoke output after removing secrets and private URLs
246
-
247
- Never paste tokens, cookies, private repository contents, customer data, or
248
- internal URLs into a public issue. See [SECURITY.md](./SECURITY.md) and
249
- [SUPPORT.md](./SUPPORT.md).
250
-
251
- ## Project Boundary
252
-
253
- This repository is the public distribution layer for the browser companion:
254
- launcher, doctor, smoke tests, documentation, safety boundary, and release
255
- evidence.
163
+ 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.
256
164
 
257
- Managed hosting, private support operations, proprietary gateways, and internal
258
- workspace automation are outside this public package.
259
-
260
- ## Acknowledgements
261
-
262
- The current beta uses and acknowledges the public `0xcaff/codex-web` approach
263
- for rendering a Codex-like browser surface. This project adds distribution,
264
- doctor, safety, documentation, and release-evidence layers around that style of
265
- workflow while keeping the non-affiliation boundary explicit.
266
-
267
- See [ACKNOWLEDGEMENTS.md](./ACKNOWLEDGEMENTS.md).
165
+ See [SECURITY.md](./SECURITY.md), [SUPPORT.md](./SUPPORT.md), and [ACKNOWLEDGEMENTS.md](./ACKNOWLEDGEMENTS.md) for additional guidance.
268
166
 
269
167
  ## License
270
168
 
271
169
  [Apache-2.0](./LICENSE.md)
170
+
171
+ ## References
172
+
173
+ [^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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-webapp",
3
- "version": "0.1.0-beta.1",
3
+ "version": "0.1.0-beta.3",
4
4
  "description": "Unofficial. Respectful web app surface, doctor, and safety wrapper for Codex App users.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",