Host controls
The Ctrl+] command prefix — end a session, grant typing, and take it back.
While porthole host is running, you are typing into the shared shell. Your
prompt, your history, your working directory — the viewer is watching the same
terminal you are using.
That leaves one problem: if every key goes to the shell, how do you talk to Porthole? Through a prefix.
The prefix
Ctrl+] is the local command prefix. The key you press after it is a command to Porthole and never reaches the shell.
| Keys | Does |
|---|---|
| Ctrl+] q (or .) | End the session |
| Ctrl+] w | Let the viewer type |
| Ctrl+] r | Stop the viewer typing, now |
| Ctrl+] ? | Print this list |
| Ctrl+] Ctrl+] | Send a literal Ctrl+] to the shell |
An unrecognised key after the prefix prints a hint rather than being swallowed, so a mistype is never mistaken for Porthole hanging.
Ctrl+C goes to the shell, not to Porthole
Hosting puts your terminal in raw mode, which clears ISIG — the same thing
SSH does. Ctrl+C therefore interrupts the command
running inside the shared session, which is what you want when you are
driving it. It will not stop sharing. Use Ctrl+]
q.
The emergency stop
Ctrl+] r revokes viewer input immediately — not at the next prompt, not once the current command finishes. Input already queued is discarded.
This matters because permission is re-checked in the writer goroutine immediately before the PTY write, not only when input is accepted. A viewer can control how long input sits in that queue by stalling the shell, so a check made only on arrival would let revoked keystrokes still run.
Pressing r when the viewer already cannot type is harmless and reports as much.
Granting write access
Ctrl+] w lets the viewer type. It is the same grant a viewer gets when you approve their request, and it survives a reconnection — see Write access.
--readonly constrains the viewer, never you. Host keystrokes go through
a separate path with no permission check, so revoking input never locks you
out of your own shell.
Pastes are never commands
If pasted text happens to contain the prefix byte, it is treated as text — the prefix is never honoured inside a paste.
This is deliberate and it is a security boundary, not a convenience: Ctrl+] w grants a remote viewer write access to your shell, and pasted text is routinely written by somebody else. A snippet copied from a chat message or a web page must not be able to grant access on its way through your clipboard.
Porthole owns the host terminal's bracketed-paste mode to make this work, re-asserting it whenever the shared shell clears it, so the guarantee does not depend on which shell you run.
Non-interactive hosting
With stdin or stdout redirected, the agent stays non-interactive: no raw mode,
no host typing, and no output mirroring. The same applies when you pass
--no-input explicitly.
porthole host --no-inputUse it when the session is a long-running job you want to stream rather than drive — a CI tail, a migration, a build. There is no prefix in this mode; stop the process the usual way.