cli/features.md Codex Docs, 2026-05-14 21:00 UTC → 2026-05-18 22:01 UTC

48 48 

49## Connect the TUI to a remote app server49## Connect the TUI to a remote app server

50 50 

51Remote 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.51Remote TUI mode lets you run the Codex app server on one machine and use the

52 52Codex terminal UI from another machine. Start the app server with a WebSocket

53Start the app server on the machine that should own the workspace and run commands:53listener:

54 54 

55```bash55```bash

56codex app-server --listen ws://127.0.0.1:450056codex app-server --listen ws://127.0.0.1:4500

57```57```

58 58 

59Then connect from the machine running the TUI:59Then connect the TUI to that endpoint:

60 60 

61```bash61```bash

62codex --remote ws://127.0.0.1:450062codex --remote ws://127.0.0.1:4500

63```63```

64 64 

65For access from another machine, bind the app server to a reachable interface, for example:65For access from another machine, bind the app server to a reachable interface

66 66and configure WebSocket auth before remote use:

67```bash

68codex app-server --listen ws://0.0.0.0:4500

69```

70 

71`--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.

72 

73Codex supports these WebSocket authentication modes for remote TUI connections:

74 

75- **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.

76- **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>`.

77- **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.

78 

79To create a capability token on the app-server host, generate a random token file with permissions that only your user can read:

80 67 

81```bash68```bash

82TOKEN_FILE="$HOME/.codex/codex-app-server-token"69TOKEN_FILE="$HOME/.codex/app-server-token"

83install -d -m 700 "$(dirname "$TOKEN_FILE")"

84openssl rand -base64 32 > "$TOKEN_FILE"70openssl rand -base64 32 > "$TOKEN_FILE"

85chmod 600 "$TOKEN_FILE"71chmod 600 "$TOKEN_FILE"

72codex app-server --listen ws://0.0.0.0:4500 --ws-auth capability-token --ws-token-file "$TOKEN_FILE"

86```73```

87 74 

88Treat the token file like a password, and regenerate it if it leaks.75`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses.

76Plain WebSocket connections are appropriate for localhost and SSH

77port-forwarding workflows. For non-local clients, use WebSocket auth and put the

78connection behind TLS.

79 

80Codex supports these WebSocket authentication modes:

81 

82- Capability token: start the server with `--ws-auth capability-token` and

83 either `--ws-token-file /absolute/path` or `--ws-token-sha256 HEX`.

84- Signed bearer token: start the server with

85 `--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path`, plus

86 optional `--ws-issuer`, `--ws-audience`, and `--ws-max-clock-skew-seconds`.

89 87 

90Then start the app server with that token file. For example, with a capability token behind a TLS proxy:88The TUI sends the remote auth token as an `Authorization: Bearer <token>` header

89during the WebSocket handshake. Codex only accepts remote auth tokens over

90`wss://` URLs or loopback `ws://` URLs.

91 91 

92```bash92```bash

93# Remote host93export CODEX_REMOTE_TOKEN="$(cat "$TOKEN_FILE")"

94TOKEN_FILE="$HOME/.codex/codex-app-server-token"94codex --remote wss://remote-host:4500 --remote-auth-token-env CODEX_REMOTE_TOKEN

95codex app-server \

96 --listen ws://0.0.0.0:4500 \

97 --ws-auth capability-token \

98 --ws-token-file "$TOKEN_FILE"

99 

100# TUI host

101export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"

102codex --remote wss://codex-devbox.example.com:4500 \

103 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

104```95```

105 96 

106The 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.97For SSH remote projects in the Codex app, use

98[Remote connections](https://developers.openai.com/codex/remote-connections). For managed remote-control

99clients, `codex remote-control` starts an app-server process with

100remote-control support enabled.

107 101 

108## Models and reasoning102## Models and reasoning

109 103 

110For most tasks in Codex, `gpt-5.5` is the recommended model when it is104For most tasks in Codex, `gpt-5.5` is the recommended model when it's

111available. It is OpenAI's newest frontier model for complex coding, computer105available. It's OpenAI's newest frontier model for complex coding, computer

112use, knowledge work, and research workflows, with stronger planning, tool use,106use, knowledge work, and research workflows, with stronger planning, tool use,

113and follow-through on multi-step tasks. If `gpt-5.5` is not yet available,107and follow-through on multi-step tasks. If `gpt-5.5` isn't yet available,

114continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have108continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have

115access to the GPT-5.3-Codex-Spark model in research preview.109access to the GPT-5.3-Codex-Spark model in research preview.

116 110