Agent install prompt

帮我安装这个 https://github.com/san-tian/codoxear，我会通过公网 IP xxxx 访问，因此你需要监听 0.0.0.0，端口你可以自己选。密码设置成 xxxxxx。使用守护进程防止闪退。同时把仓库里的 skills/codoxear-session 安装到 ${CODEX_HOME:-$HOME/.codex}/skills/codoxear-session，方便后续 agent 通过 Codoxear 创建、发送和管理会话。安装好之后告诉我如何登录。可以使用 Tailscale 发布到公网，问我是否需要。

Codoxear

Unofficial mobile handoff for local CLI agent sessions.

Codoxear runs a small web server on your computer and exposes a phone-friendly UI for continuing the same live CLI agent session from mobile. Your environment stays local (filesystem, tools, credentials). The phone is a view/controller.

Currently supported agent backends:

• Codex
• Pi

Name: "codoxear" = "codex dogear" (dog-ear a page so you can pick up where you left off), meaning you can seamlessly continue the same work from different devices.

Not affiliated with OpenAI or the Pi Coding Agent project. "Codex" and "Pi" are referenced only for CLI compatibility.

Platform support

Supported:

• Linux (uses /proc, PTYs)
• macOS (uses lsof/pgrep, PTYs)

Not supported:

• Windows (no POSIX PTY/termios model; use WSL2 if you want a Linux environment)

Quick start

Requires Rust, Node.js for frontend builds, and the Codex or Pi CLI you want to control.

1. Create .env:

   • Copy .env.example to .env
   • Set CODEX_WEB_PASSWORD
   • Codoxear reads .env from your current working directory

2. Build and start the local daemon:

   cd backend-rs
   cargo build --release --bins
   cd ..
   ./scripts/codoxear-local start

   • Default bind: 127.0.0.1
   • Default port: 8743

3. Install the bundled Codex skill so agents can operate Codoxear sessions:

   CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
   mkdir -p "$CODEX_HOME/skills"
   rm -rf "$CODEX_HOME/skills/codoxear-session"
   cp -R skills/codoxear-session "$CODEX_HOME/skills/codoxear-session"

   The skill adds helpers for creating Codoxear-visible sessions, sending messages, renaming sessions, and updating Nova markers. Set CODOXEAR_BASE_URL if the service is not reachable at http://127.0.0.1:8743.

4. Add separate wrappers for terminal-owned brokered sessions (zsh/bash function, not an alias):

   Never wrap or replace codex() or pi() themselves. Web-owned sessions launch the underlying CLI directly, so wrapping the original command to call the broker can recurse back into the broker and create an unbounded session-spawn loop.

   Add to ~/.zshrc or ~/.bashrc:

   codox() {
     /path/to/codoxear/backend-rs/target/release/codoxear-broker-rs -- "$@"
   }
   
   piox() {
     CODEX_WEB_AGENT_BACKEND=pi /path/to/codoxear/backend-rs/target/release/codoxear-broker-rs -- "$@"
   }

   Restart your shell or source your rc file.

5. Use codox for terminal-owned Codex sessions and piox for terminal-owned Pi sessions when you want them registered with Codoxear. Leave plain codex and pi unwrapped.

6. On your phone, open http://<your-computer>:8743, enter the password, and select the session.

7. (Optional) Enable Harness mode for a session:

   • Click the Harness icon in the top bar, toggle it on, tune cooldown minutes and injection count, and edit the optional extra request.
   • Harness runs in the server process (not the browser tab), so it continues even if you close the web page.
   • Settings are per session; each injection decrements the remaining count and harness turns itself off at zero. Enabled sessions show a harness badge in the sidebar.

Tailscale HTTPS

If you want browser notifications or iOS Web Push, use HTTPS instead of plain http://<host>:8743.

The simplest setup is Tailscale Serve on port 8443:

tailscale serve --bg --yes --https=8443 http://127.0.0.1:8743

Then open Codoxear at:

https://<device>.<tailnet>.ts.net:8443/

Example:

https://yiwen-workstation.tail0de6f7.ts.net:8443/

Notes:

• Browser notification APIs require a secure context (https://... or http://localhost).
• iOS Web Push requires an installed Home Screen web app on HTTPS; a normal Safari tab is not enough.
• Tailscale-issued HTTPS works for the *.ts.net name, not for a bare local hostname.

If you run Codoxear as a user systemd service, you can attach Tailscale Serve to the same lifecycle with:

[Service]
ExecStartPost=/usr/bin/tailscale serve --bg --yes --https=8443 http://127.0.0.1:8743
ExecStopPost=-/usr/bin/tailscale serve --bg --yes --https=8443 off

Then reload and restart:

systemctl --user daemon-reload
./scripts/codoxear-local restart
tailscale serve status

User stories

• Desktop Linux: start Codex or Pi in your GUI terminal emulator, then continue the same live session on your phone or a laptop browser.
• Headless Linux: start Codex or Pi inside tmux, then attach from your phone or a laptop browser. This avoids using a mobile terminal emulator for TUI interaction (for example Termius).
• Web-owned sessions: start a new Codex or Pi session from the Codoxear UI, use it from mobile, and kill it from the UI when finished.
• Web-owned tmux sessions: start a new Codex or Pi session from the Codoxear UI with Create in tmux enabled to run it inside a stable tmux session derived from the session workspace/cwd for shell-side observability. Sessions in the same workspace share one tmux session and use separate tmux windows.
• When a tmux-backed session is selected, the top bar shows a tmux button that copies the exact tmux attach-session ... command for reconnecting to that session from a terminal.
• The Nova preview shell also exposes a Copy tmux attach button for tmux-backed sessions, using the same tmux attach-session ... command shape.
• Nova shows a compact NEW badge beside Codoxear Nova when the local checkout does not contain the configured remote HEAD. By default it checks origin's default branch (origin/HEAD), then upstream's default branch, then main. Override this in .env only when you want a different update source:

CODOXEAR_UPDATE_REMOTE=origin
CODOXEAR_UPDATE_REF=san-tian-dev

Session ownership

Codoxear shows three kinds of sessions:

• Terminal-owned: sessions started from your local terminal via codox or piox (the broker wrappers). They are marked T in the UI.
• Web-owned: sessions started from the Codoxear UI ("New session"). They are marked W in the UI.
• Web-owned tmux: sessions started from the Codoxear UI with Create in tmux enabled. They are marked with the tmux split-pane icon in the UI and run under a tmux session derived from workspace_cwd when present, otherwise from the real cwd; each browser session gets its own tmux window.

The current UI offers Delete for all session kinds. Delete sends a shutdown request to the underlying broker, so deleting a terminal-owned session also stops the corresponding terminal session.

If you start a web-owned session and later want to continue it in your terminal while keeping it registered with Codoxear, use the matching backend workflow: Codex sessions resume through codox ..., Pi sessions through piox ... or plain pi --session <session-file> if you want to continue the same Pi session file directly.

Known limitations

Codex confirmation prompts still need a terminal

Codoxear cannot drive Codex confirmation prompts in default mode or plan mode from the browser UI.

For full remote interaction, run Codex in YOLO mode so confirmations do not block on interactive terminal prompts.

Codex /new may show as pending until first prompt

Codex does not always materialize (open) the new rollout-*.jsonl file immediately after /new. Codoxear tracks the active rollout by scanning the Codex process tree for open rollout-log file descriptors, so the UI may show the session as pending until the first prompt is sent and the rollout file is created/opened.

Security model

This project intentionally keeps security out of scope. It provides password gating only and does not provide TLS.

Assume anyone who can reach the port can:

• observe traffic (including the password)
• modify traffic

Use your own secure channel (VPN, SSH port-forward, reverse proxy with TLS) if you need network security.

Configuration

Set these in .env (or in the process environment):

• CODEX_WEB_PASSWORD (required)
• CODEX_WEB_HOST (default ::)
• CODEX_WEB_PORT (default 8743)
• CODEX_WEB_URL_PREFIX (default empty). Example: /codoxear serves the UI at /codoxear/ and the API under /codoxear/api/*.
• CODEX_WEB_DEFAULT_AGENT_BACKEND (default codex) - default backend tab for new web-owned sessions
• CODEX_HOME (default ~/.codex)
• CODEX_BIN (default codex)
• PI_HOME (default ~/.pi)
• PI_BIN (default pi)
• CODEX_WEB_COOKIE_TTL_SECONDS (default 2592000, 30 days)
• CODEX_WEB_COOKIE_SECURE (default 0; set to 1 behind HTTPS)
• CODEX_WEB_HARNESS_SWEEP_SECONDS (default 2.5)
• CODEX_WEB_VOICE_PUSH_SWEEP_SECONDS (default 1.0)

Replatforming preview

This repository contains the Rust backend and Nova frontend:

• frontend/ — Preact + TypeScript + Vite + Pretext
• backend-rs/ — Rust + Axum + SSE

Current route split:

• / and /nova/ — redirect to /nova-preview/, so the replatformed shell is the active browser entry
• /nova-preview/ — new Preact + Pretext shell, now wired to the live same-origin Rust /api/* browser contract for sessions, transcript polling, diagnostics, queue, harness, interrupt, file viewing, new-session creation, voice settings, notifications, and audio listener heartbeats
• /api/v1/* — Rust backend routes backing the same browser contract

Frontend dev:

cd frontend
npm install
npm run dev

Rust backend dev:

cd backend-rs
cargo run

The Nova preview frontend uses same-origin /api by default in production. For standalone local dev against a different server, set VITE_CODOXEAR_API_BASE=http://127.0.0.1:13780.

The local deploy helper ./scripts/codoxear-local now runs the Rust backend as the public/runtime process:

• public Rust web entry on :8743 redirecting / and /nova/ to /nova-preview/, serving the Nova preview shell, the legacy shell at /legacy/*, and the migrated public /api/* routes
• Rust daemon workers for delayed queue draining, harness sweep, live assistant-message voice scanning, OpenAI-compatible summary/TTS, Web Push delivery, and ffmpeg/HLS audio merging; APP_DIR/voice_inbox/*.json is now a Rust-internal handoff queue instead of a Python companion boundary
• native Rust broker binary at backend-rs/src/bin/codoxear-broker-rs.rs; new web-owned Codex and Pi session creation uses this broker, and CODOXEAR_RUST_BROKER_BIN selects the binary
• CODEX_WEB_HARNESS_SWEEP_SECONDS (default 2.5)
• CODEX_WEB_QUEUE_SWEEP_SECONDS (default 1.0)
• CODEX_WEB_QUEUE_IDLE_GRACE_SECONDS (default 10.0)
• CODEX_WEB_VOICE_PUSH_SWEEP_SECONDS (default 1.0)
• CODEX_WEB_DISCOVER_MIN_INTERVAL_SECONDS (default 1.0)
• CODEX_WEB_METRICS_WINDOW (default 256)
• CODEX_WEB_FILE_READ_MAX_BYTES (default 2097152)
• CODEX_WEB_FILE_HISTORY_MAX (default 20)
• CODEX_WEB_GIT_DIFF_MAX_BYTES (default 819200)
• CODEX_WEB_GIT_DIFF_TIMEOUT_SECONDS (default 4.0)
• CODEX_WEB_GIT_CHANGED_FILES_MAX (default 400)
• CODEX_WEB_FD_POLL_SECONDS (default 1.0) - how often the broker scans /proc to detect the active rollout-*.jsonl

Runtime state is stored under ~/.local/share/codoxear (legacy ~/.local/share/codex-web is no longer used).

Backend-specific session logs live under the backend home:

• Codex: ~/.codex/sessions/rollout-*.jsonl
• Pi: ~/.pi/agent/sessions/*.jsonl

License

MIT, see LICENSE.