cli/features.md +59 −0
44 44
45Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with `--cd` or add extra roots with `--add-dir` if you need to steer the environment before resuming.45Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with `--cd` or add extra roots with `--add-dir` if you need to steer the environment before resuming.
46 46
47## Connect the TUI to a remote app server
48
49Remote TUI mode lets you run the Codex app server on one machine and use the Codex terminal UI from another machine. This is useful when the code, credentials, or execution environment live on a remote host, but you want the local interactive TUI experience.
50
51Start the app server on the machine that should own the workspace and run commands:
52
53```bash
54codex app-server --listen ws://127.0.0.1:4500
55```
56
57Then connect from the machine running the TUI:
58
59```bash
60codex --remote ws://127.0.0.1:4500
61```
62
63For access from another machine, bind the app server to a reachable interface, for example:
64
65```bash
66codex app-server --listen ws://0.0.0.0:4500
67```
68
69`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses only. For plain WebSocket connections, prefer local-host addresses or SSH port forwarding. If you expose the listener beyond the local host, configure authentication before real remote use and put authenticated non-local connections behind TLS.
70
71Codex supports these WebSocket authentication modes for remote TUI connections:
72
73- **No WebSocket auth**: Best for local-host listeners or SSH port-forwarded connections. Codex can start non-local listeners without auth, but logs a warning and the startup banner reminds you to configure auth before real remote use.
74- **Capability token**: Store a shared token in a file on the app-server host, start the server with `--ws-auth capability-token --ws-token-file /abs/path/to/token`, then set the same token in an environment variable on the TUI host and pass `--remote-auth-token-env <ENV_VAR>`.
75- **Signed bearer token**: Store an HMAC shared secret in a file on the app-server host, start the server with `--ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret`, and have the TUI send a signed JWT bearer token through `--remote-auth-token-env <ENV_VAR>`. The shared secret must be at least 32 bytes. Signed tokens use HS256 and must include `exp`; Codex also validates `nbf`, `iss`, and `aud` when those claims or server options are present.
76
77To create a capability token on the app-server host, generate a random token file with permissions that only your user can read:
78
79```bash
80TOKEN_FILE="$HOME/.codex/codex-app-server-token"
81install -d -m 700 "$(dirname "$TOKEN_FILE")"
82openssl rand -base64 32 > "$TOKEN_FILE"
83chmod 600 "$TOKEN_FILE"
84```
85
86Treat the token file like a password, and regenerate it if it leaks.
87
88Then start the app server with that token file. For example, with a capability token behind a TLS proxy:
89
90```bash
91# Remote host
92TOKEN_FILE="$HOME/.codex/codex-app-server-token"
93codex app-server \
94 --listen ws://0.0.0.0:4500 \
95 --ws-auth capability-token \
96 --ws-token-file "$TOKEN_FILE"
97
98# TUI host
99export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"
100codex --remote wss://codex-devbox.example.com:4500 \
101 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN
102```
103
104The TUI sends remote auth tokens as `Authorization: Bearer <token>` during the WebSocket handshake. Codex only sends those tokens over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`, so put non-local remote listeners behind TLS if clients need to authenticate over the network.
105
47## Models and reasoning106## Models and reasoning
48 107
49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the108For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the