cli/features.md +69 −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
95 154
96Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.155Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.
97 156
157## Image generation
158
159Ask Codex to generate or edit images directly in the CLI. This works well for assets such as icons, banners, illustrations, sprite sheets, and placeholder art. If you want Codex to transform or extend an existing asset, attach a reference image with your prompt.
160
161You can ask in natural language or explicitly invoke the image generation skill by including `$imagegen` in your prompt.
162
163Built-in image generation uses `gpt-image-1.5`, counts toward your general Codex usage limits, and uses included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. For details, see [Pricing](https://developers.openai.com/codex/pricing#image-generation-usage-limits). For prompting tips and model details, see the [image generation guide](https://developers.openai.com/api/docs/guides/image-generation).
164
165For larger batches of image generation, set `OPENAI_API_KEY` in your environment variables and ask Codex to generate images through the API so API pricing applies instead.
166
98## Syntax highlighting and themes167## Syntax highlighting and themes
99 168
100The TUI syntax-highlights fenced markdown code blocks and file diffs so code is easier to scan during reviews and debugging.169The TUI syntax-highlights fenced markdown code blocks and file diffs so code is easier to scan during reviews and debugging.