Connection guide
From your phone to your host.
Start with a computer you can reach over SSH. Termcat connects using the credentials you already have.
1. Add a connection
Open Hosts and tap +. Choose SSH. Enter the host address, a name, your username and the SSH port. Port 22 is the default. Choose Password, Private key or Interactive authentication.
Test connection checks the connection independently of saving. Review the host fingerprint against a trusted source on your computer before accepting it. Save the profile to use it again.
Your host must have an SSH server enabled, and your phone must be able to reach it over your network or VPN.
Using Tailcat
On a host with Tailcat installed, run tailcat --serve=no-auth-ssh. In Termcat, choose Tailcat Quick Connect and enter the tc… token from that host.
Termcat saves a reusable connection and opens a shell. Keep the host process running. Treat its token as private connection information.
2. Choose a shell or session
Open a saved connection to discover tmux and Herdr sessions. Start a plain shell or attach to an existing session. Use the session controls to switch windows and panes.
Use a host-owned tmux or Herdr session for long-running work. Minimizing Termcat keeps the app session open, but the operating system can still suspend its network connection. Reconnect to your host to resume.
3. Organize your Work inbox
Work is the default screen. Search work and host names, or filter Agents and Terminals. Swipe right for priority and rename. Swipe left for archive and delete.
Archive removes a row from the main inbox without disconnecting it. Find it under Archived when you need it again. Offline observations show when the host was last checked.
Use the shared agent chat
Termcat uses one chat view for recorded Claude/Codex conversations and live Codex/OpenCode sessions. Recorded history comes from the selected host session. Live chat connects to an agent server on that same host and supports streaming replies, tool results, images and approval requests.
For live chat, install Python 3 and the agent CLI on your host. Configure the agent's own account or model provider there. Termcat supplies a Python helper over SSH; the agent still runs your tools and model requests.
For Codex, run codex app-server --listen ws://127.0.0.1:4500 on the host and keep it running.
For an OpenCode terminal, start it with opencode --hostname 127.0.0.1 --port 4096. For a server without a terminal interface, use opencode serve --hostname 127.0.0.1 --port 4096.
In the connected terminal's Chat source screen, choose Codex or OpenCode, enter the matching Host port, and tap Choose conversation. Select an existing conversation or create one in a host directory. If the OpenCode server requires a password, enable Use server password and enter its credentials.
These addresses refer to your host's local interface. Termcat reaches them through SSH, so you do not need to expose the agent port to your network. Supported controls depend on the selected source and its server version. If the source is unavailable, use the terminal.
Dictation and inserted commands stay in your draft until you tap Send. Use Stop to cancel a live reply. Leaving the chat does not stop the agent's work on the host.
Type, compose or dictate
Type directly into the terminal, or open Write to prepare a message before sending. Saved commands enter the draft so you can review and edit them first.
Configure the toolbar, gestures and hardware keyboard in settings. Ctrl and Alt apply modifiers; hold to lock them. The direction pad makes terminal navigation easier on a touch screen.
Choose a speech engine in settings. Local engines keep transcription on the device. A provider engine sends audio to the provider you configure. Review the draft before sending it to your host.
Files, projects and Git
Open Files from a connected terminal to browse directories or transfer files and photos. Upload to your chosen directory, then insert the quoted path into your draft. Direct transfers use SSH.
Use Projects to return to recent directories. Git inspection shows the repository state and changes. Host web previews connect through an SSH tunnel.
If a connection fails
A timeout means your host did not answer. Check the address, port, SSH server and network or VPN connection. Authentication failures happen after the host responds; check the username and credentials.
A changed host key needs a separate identity check. Compare the new fingerprint with the host before trusting it. Do not approve an unexplained change.
Optional services
Closed-app alerts require separate enrollment, host pairing and a notification relay. Hosted file links require a configured sharing service. Neither service is required for core SSH.