remote-codex 0.11.22 → 0.11.23

package/README.md

@@ -1,38 +1,109 @@
-# Remote Codex Supervisor
+# Remote Codex
 
-Phase 1 implements the base supervisor foundation for a local `Codex` control surface:
+[![English](https://img.shields.io/badge/English-0f172a?style=for-the-badge)](#english)
+[![中文](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-0f172a?style=for-the-badge)](#中文)
 
-- `Fastify` API with health checks, runtime config, workspace registry, and WebSocket skeleton
-- `React + Vite` web shell with a single-user landing page, workspace list, add flow, and read-only tree
-- `Drizzle + better-sqlite3` persistence with explicit SQL migrations
-- Workspace browsing constrained to a configurable root path
+## English
 
-## Requirements
+Remote Codex is a web, Android, and iOS supervisor for Codex workspaces and
+threads. It can run locally, over Tailscale/LAN, or through a public relay so a
+private machine can connect outward without opening inbound ports.
 
-- Node.js `>= 20`
-- pnpm `>= 10`
+### Downloads
 
-## Install
+- Android APK: [remote-codex-android.apk](https://github.com/dufangshi/remoteCodex/releases/latest/download/remote-codex-android.apk)
+- iOS IPA: [RemoteCodex.ipa](https://github.com/dufangshi/remoteCodex/releases/latest/download/RemoteCodex.ipa)
+- npm CLI: `npm install -g remote-codex`
+
+### Features
+
+- Relay mode for web/mobile access to private workspaces.
+- Device-scoped routes, shared sessions, and per-device workspace/thread lists.
+- Codex thread chat with streaming steps, attachments, exports, and workspace explorer.
+- Workspace file browsing, preview, upload/download, edit, and image preview.
+- Android, iOS, web, Docker, and npm CLI entrypoints.
+
+### Run A Relay Server
+
+Docker from GHCR:
 
 ```bash
-pnpm install
-cp .env.example .env
+docker volume create remote-codex-relay-data
+
+docker run -d \
+  --name remote-codex-relay \
+  --restart unless-stopped \
+  -p 8798:8788 \
+  -v remote-codex-relay-data:/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_HOST=0.0.0.0 \
+  -e REMOTE_CODEX_RELAY_PORT=8788 \
+  -e REMOTE_CODEX_RELAY_DATA_DIR=/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_REGISTRATION_ENABLED=true \
+  -e REMOTE_CODEX_ADMIN_USERNAME=admin \
+  -e REMOTE_CODEX_ADMIN_PASSWORD='change-this-password' \
+  -e REMOTE_CODEX_RELAY_SESSION_SECRET='change-this-session-secret' \
+  ghcr.io/dufangshi/remotecodex-relay:latest
 ```
 
-Optional overrides:
+Build the Docker image yourself:
 
-- `WORKSPACE_ROOT=/absolute/path`
-- `DATABASE_URL=/absolute/path/to/sqlite.db`
+```bash
+git clone https://github.com/dufangshi/remoteCodex.git
+cd remoteCodex
+docker build -f Dockerfile.relay -t remote-codex-relay .
+docker run -d --name remote-codex-relay --restart unless-stopped \
+  -p 8798:8788 \
+  -v remote-codex-relay-data:/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_HOST=0.0.0.0 \
+  -e REMOTE_CODEX_RELAY_PORT=8788 \
+  -e REMOTE_CODEX_RELAY_DATA_DIR=/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_REGISTRATION_ENABLED=true \
+  -e REMOTE_CODEX_ADMIN_USERNAME=admin \
+  -e REMOTE_CODEX_ADMIN_PASSWORD='change-this-password' \
+  -e REMOTE_CODEX_RELAY_SESSION_SECRET='change-this-session-secret' \
+  remote-codex-relay
+```
 
-Defaults:
+Direct script mode:
 
-- development database: `.local/supervisor-dev.sqlite`
-- production database: `~/.remote-codex/supervisor.sqlite`
-- workspace root: current user home directory
+```bash
+git clone https://github.com/dufangshi/remoteCodex.git
+cd remoteCodex
+./start.sh
+```
 
-## Global CLI Install
+`start.sh` defaults to relay mode on `0.0.0.0:8798`, creates
+`.local/relay.env` on first run, and prints the initial admin password. Override
+the port with:
 
-Remote Codex can also be packaged as an npm global CLI:
+```bash
+REMOTE_CODEX_RELAY_PORT=18088 ./start.sh
+```
+
+Open `http://SERVER_HOST:8798/relay-portal`, sign in, create a device, and copy
+the setup command.
+
+### Connect A Private Machine
+
+Install the CLI on the machine that owns the workspace:
+
+```bash
+npm install -g remote-codex
+```
+
+Then run the copied command from the relay portal. It has this shape:
+
+```bash
+REMOTE_CODEX_RELAY_SERVER_URL=ws://SERVER_HOST:8798 \
+REMOTE_CODEX_RELAY_AGENT_TOKEN=rcd_device_token \
+REMOTE_CODEX_RELAY_SUPERVISOR_PORT=45679 \
+remote-codex relay-supervisor
+```
+
+`45679` is used by default in copied setup commands to avoid common local
+`8787` port conflicts. You can change it if needed.
+
+### Local Mode
 
 ```bash
 npm install -g remote-codex
@@ -41,122 +112,158 @@ remote-codex status
 remote-codex stop
 ```
 
-The global CLI starts the production API and web service:
+Default npm CLI ports:
 
-- API: `http://127.0.0.1:45674`
 - Web: `http://127.0.0.1:45673`
-- service logs/state: `~/.remote-codex/service/`
-- production database: `~/.remote-codex/supervisor.sqlite`
-
-Environment overrides:
+- API: `http://127.0.0.1:45674`
 
-- `SERVICE_HOST` and `SERVICE_PORT`
-- `SERVICE_API_HOST` and `SERVICE_API_PORT`
-- `REMOTE_CODEX_SERVICE_DIR`
-- `DATABASE_URL`
-- `WORKSPACE_ROOT`
-- `CODEX_HOME`
-- `CODEX_COMMAND`
+Override with `SERVICE_PORT` and `SERVICE_API_PORT`.
 
-## Development
+### Development
 
 ```bash
+pnpm install
 pnpm db:migrate
 pnpm dev
 ```
 
-This starts:
+Common checks:
 
-- API: `http://127.0.0.1:8787`
-- Web: `http://127.0.0.1:5173`
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+```
 
-## Service Mode
+### Publish Mobile Apps
 
-Build first, then use the service manager:
+After building an APK and IPA locally:
 
 ```bash
-pnpm build
-pnpm service:start
-pnpm service:status
-pnpm service:stop
+pnpm release:mobile -- --tag v0.11.23 \
+  --apk apps/android/app/build/outputs/apk/release/app-release.apk \
+  --ipa apps/ios/build/RemoteCodex.ipa
 ```
 
-This starts a quieter long-running stack:
+The uploaded asset names stay stable:
+
+- `remote-codex-android.apk`
+- `RemoteCodex.ipa`
+
+## 中文
+
+Remote Codex 是 Codex workspace 和 thread 的 Web、Android、iOS 控制台。它可以
+本地运行，也可以通过 Tailscale/LAN 访问；relay 模式下，私有机器只需要主动连到
+公网 relay，不需要开放入站端口。
 
-- API: `http://127.0.0.1:8787`
-- Web: `http://127.0.0.1:4173`
+### 下载
 
-Logs are written to `~/.remote-codex/service/` by default. Set `REMOTE_CODEX_SERVICE_DIR` to override this.
+- Android APK: [remote-codex-android.apk](https://github.com/dufangshi/remoteCodex/releases/latest/download/remote-codex-android.apk)
+- iOS IPA: [RemoteCodex.ipa](https://github.com/dufangshi/remoteCodex/releases/latest/download/RemoteCodex.ipa)
+- npm CLI: `npm install -g remote-codex`
 
-## Remote Access via Tailscale
+### 功能
 
-If you want to open the supervisor from another device on your tailnet:
+- Relay 模式：网页和移动端访问私有 workspace。
+- 按设备隔离 URL、workspace、thread，并支持 session 分享。
+- Codex thread 聊天、流式步骤、图片/附件、导出和 workspace explorer。
+- 文件浏览、预览、上传/下载、编辑和图片预览。
+- Web、Android、iOS、Docker、npm CLI 多入口。
+
+### 启动 Relay 服务器
+
+使用 GHCR 镜像：
 
 ```bash
-pnpm dev
-tailscale serve --bg 5173
+docker volume create remote-codex-relay-data
+
+docker run -d \
+  --name remote-codex-relay \
+  --restart unless-stopped \
+  -p 8798:8788 \
+  -v remote-codex-relay-data:/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_HOST=0.0.0.0 \
+  -e REMOTE_CODEX_RELAY_PORT=8788 \
+  -e REMOTE_CODEX_RELAY_DATA_DIR=/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_REGISTRATION_ENABLED=true \
+  -e REMOTE_CODEX_ADMIN_USERNAME=admin \
+  -e REMOTE_CODEX_ADMIN_PASSWORD='change-this-password' \
+  -e REMOTE_CODEX_RELAY_SESSION_SECRET='change-this-session-secret' \
+  ghcr.io/dufangshi/remotecodex-relay:latest
 ```
 
-Or, if you are using service mode:
+自己构建 Docker 镜像：
 
 ```bash
-pnpm build
-pnpm service:start
-tailscale serve --bg 4173
+git clone https://github.com/dufangshi/remoteCodex.git
+cd remoteCodex
+docker build -f Dockerfile.relay -t remote-codex-relay .
+docker run -d --name remote-codex-relay --restart unless-stopped \
+  -p 8798:8788 \
+  -v remote-codex-relay-data:/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_HOST=0.0.0.0 \
+  -e REMOTE_CODEX_RELAY_PORT=8788 \
+  -e REMOTE_CODEX_RELAY_DATA_DIR=/var/lib/remote-codex-relay \
+  -e REMOTE_CODEX_RELAY_REGISTRATION_ENABLED=true \
+  -e REMOTE_CODEX_ADMIN_USERNAME=admin \
+  -e REMOTE_CODEX_ADMIN_PASSWORD='change-this-password' \
+  -e REMOTE_CODEX_RELAY_SESSION_SECRET='change-this-session-secret' \
+  remote-codex-relay
 ```
 
-Useful Tailscale commands:
+直接脚本启动：
 
 ```bash
-tailscale serve status
-tailscale serve reset
+git clone https://github.com/dufangshi/remoteCodex.git
+cd remoteCodex
+./start.sh
 ```
 
-Notes:
+`start.sh` 默认以 relay 模式监听 `0.0.0.0:8798`，首次运行会创建
+`.local/relay.env` 并打印初始 admin 密码。改端口：
 
-- `tailscale serve --bg 5173` is required for the current remote-access workflow and was previously undocumented.
-- In both dev mode and service mode, the web entrypoint proxies `/api`, `/healthz`, and `/ws` to the API on
-  `127.0.0.1:8787`, so you do not need a separate `tailscale serve` rule for the API port.
-- If the Tailscale hostname for the target machine changes, update `allowedHosts` in
-  `apps/supervisor-web/vite.config.ts` before using remote access.
+```bash
+REMOTE_CODEX_RELAY_PORT=18088 ./start.sh
+```
+
+打开 `http://SERVER_HOST:8798/relay-portal`，登录后创建设备并复制 setup command。
 
+### 连接私有机器
 
-## Common Commands
+在真正拥有 workspace 的机器上安装 CLI：
 
 ```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm db:migrate
+npm install -g remote-codex
 ```
 
-## Documentation
-
-- [Plugin system](./docs/plugins.md)
-
-## API Endpoints
+然后运行 relay portal 复制出来的命令，形如：
 
-- `GET /healthz`
-- `GET /api/version`
-- `GET /api/config/runtime`
-- `GET /api/workspaces`
-- `GET /api/workspaces/:id`
-- `POST /api/workspaces`
-- `POST /api/workspaces/:id/favorite`
-- `POST /api/workspaces/:id/open`
-- `GET /api/workspaces/tree?path=...&showHidden=...`
-- `GET /ws`
+```bash
+REMOTE_CODEX_RELAY_SERVER_URL=ws://SERVER_HOST:8798 \
+REMOTE_CODEX_RELAY_AGENT_TOKEN=rcd_device_token \
+REMOTE_CODEX_RELAY_SUPERVISOR_PORT=45679 \
+remote-codex relay-supervisor
+```
 
-## Manual Acceptance
+复制命令默认使用 `45679`，用于避开本机常见的 `8787` 端口冲突；需要时可以手动换。
 
-1. Remove prior build and local state:
+### 本地模式
 
 ```bash
-rm -rf node_modules .local apps/*/dist packages/*/dist
+npm install -g remote-codex
+remote-codex start
+remote-codex status
+remote-codex stop
 ```
 
-2. Reinstall and start:
+npm CLI 默认端口：
+
+- Web: `http://127.0.0.1:45673`
+- API: `http://127.0.0.1:45674`
+
+可用 `SERVICE_PORT` 和 `SERVICE_API_PORT` 覆盖。
+
+### 开发
 
 ```bash
 pnpm install
@@ -164,31 +271,25 @@ pnpm db:migrate
 pnpm dev
 ```
 
-3. Verify API health:
+常用检查：
 
 ```bash
-curl http://127.0.0.1:8787/healthz
-curl http://127.0.0.1:8787/api/version
-curl http://127.0.0.1:8787/api/config/runtime
+pnpm build
+pnpm typecheck
+pnpm test
 ```
 
-4. Open the web UI at `http://127.0.0.1:5173`, add a valid workspace, then verify:
-
-- it appears in the workspace list
-- the detail page shows the tree
-- hidden files can be toggled on and off
-
-5. Verify failure paths by attempting to add:
+### 发布移动端安装包
 
-- a non-existent directory
-- a directory outside `WORKSPACE_ROOT`
-- a non-directory path
-
-6. Run the full quality gate:
+本地构建好 APK 和 IPA 后：
 
 ```bash
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm build
+pnpm release:mobile -- --tag v0.11.23 \
+  --apk apps/android/app/build/outputs/apk/release/app-release.apk \
+  --ipa apps/ios/build/RemoteCodex.ipa
 ```
+
+上传后的文件名保持固定：
+
+- `remote-codex-android.apk`
+- `RemoteCodex.ipa`