Subshell Docs

Terminal troubleshooting

Diagnose terminal input and rendering problems.

Input unavailable

Check that the session's process is running and that you have edit access. View-only access lets you watch but doesn't let you type. In an SSH subshell, only its owner can type, even if someone else has edit access. MCP and other bearer credentials can't send SSH terminal input either.

On a phone or tablet, open the subshell’s ⋯ actions menu and choose Enable text input if text copying is enabled. Copy mode disables typing, Paste, and the key bar’s input buttons; scrolling remains available.

An offline node makes its stream unreachable even if its process continues on the machine.

Home and End don't scroll the conversation

In Codex, Home and End move within the input line. Use Ctrl+Home to jump to the beginning of the conversation and Ctrl+End to return to the latest message. PgUp and PgDn scroll one page at a time.

The mobile key bar shows these controls while a full-screen app owns the terminal. Swipe the bar sideways to reach them. They send keys to the app, so they require input mode, edit access, and a connected terminal. Other apps may assign different actions to the same keys.

Select and copy terminal text

On a phone or tablet, open the subshell’s ⋯ actions menu and choose Enable text copying. Press and hold the text, adjust the selection handles, then use your browser or device’s copy action. Tapping an HTTP or HTTPS link opens it; dragging a selection doesn’t open the link.

A subshell’s actions menu with Enable text copying among its controls.
Choose Enable text copying in the subshell’s actions menu.
A terminal showing Build complete and the selected text 3 checks passed.
Copy mode lets you select rendered terminal text. Your device supplies the copy action.

Copy mode keeps the keyboard closed while you select text. Choose Enable text input in the same menu to type again. This setting belongs to your browser for that subshell and doesn't change anyone else's input access.

Page loads but output doesn't stream

Verify WebSocket forwarding through the proxy and confirm that the API can mint the terminal's single-use token. A successful static page load doesn't test either operation.

Try the server's direct trusted address from an appropriate device to isolate a proxy problem.

Connection closes with an input limit

A terminal input limit exceeded close means one input message was too large or too much input is still waiting to finish. Wait for the node to respond before sending more. The current client splits large pastes and limits outstanding messages automatically; custom clients must do the same.

A disconnect doesn't undo commands already sent. Check the terminal before repeating a command whose result is uncertain.

Terminal becomes smaller

Everyone watching a terminal shares its size. If someone opens it in a smaller window, the terminal can shrink for everyone. Check the attached devices and close any views you no longer need.

Corrupted display

After a resize, the terminal can briefly reconnect to refresh its display from the running subshell. This doesn’t restart the agent or shell. If the display stays corrupted, note the agent and component versions, and whether the display breaks after reconnecting or resizing. Terminal connection entries in the server log can help identify sizing or output-replay problems.

Screen dumps

Attach-debug output can include secrets and project contents. Don't enable it or upload its files without reviewing what will be captured.

Next steps

Read Launch a subshell, HTTPS and reverse proxies, and Status and logs.

Edit on GitHub

Last updated on

On this page