Session Management
A session is what opens when you connect to a server: one terminal, or up to four panes in split screen. Sessions keep running while you move around the app, and you can hold as many open as you like, to different servers or several to the same one.
Opening and finding sessions
Section titled “Opening and finding sessions”- Tap a server tile on the home screen to open a new terminal with the server’s saved protocol and tmux choice.
- New terminal in the server sheet does the same, with a protocol and tmux pick for this launch.
- Active Sessions at the top of the home screen shows every open session as a preview of its panes. Tap one to open it. Long-press for Open, Rename and Close Session.
On desktop, open sessions are tabs in the content pane.
Switching between sessions
Section titled “Switching between sessions”- Swipe sideways in the session view to move to the next or previous session.
- Session switcher. Tap the Session settings icon (the sliders in the breadcrumb bar) and choose Session switcher. Swipe through the open sessions, select a pane and tap Open. The switcher also offers Rotate, Layout, Close Session and Close All. With a hardware keyboard, ⌘E (macOS and iOS) or Ctrl+Shift+E (Windows, Linux and Android) opens it; see Keyboard Shortcuts.
- Floating button. Session settings › Session switcher button adds a floating button with the session count. It’s off by default.
Switching sessions doesn’t open the soft keyboard. If the keyboard was up it stays up; with a hardware keyboard, typing goes to whichever session is visible.
Session settings
Section titled “Session settings”The Session settings sheet (the sliders icon in the breadcrumb bar) holds the controls for the current session:
- Rename session.
- Split screen / Add pane, Add Browser, Change layout, Resize panes. See Split Screen and Browser Preview.
- Session switcher.
- Keyboard options: Auto-focus keyboard, Sticky keyboard toolbar.
- Voice: Microphone button and Auto-enter after voice.
- Compose mode and Sticky compose bar.
- Floating buttons: Session switcher button and Microphone button.
- Close session.
Keyboard and compose bar
Section titled “Keyboard and compose bar”A single row of keys sits above the soft keyboard. In a terminal it holds the terminal toolbar (customize it in Settings › Terminal › Keyboard Toolbar). When a code editor pane has focus, the editor’s keys take the same row. With the keyboard open, Back hides the keyboard first.
The compose bar is on by default. Type a whole command, edit it and send it with Enter, instead of sending each keystroke as you type. Sticky compose bar (also on by default) keeps it visible while the soft keyboard is hidden. Turn Compose mode off in Session settings; Sticky compose bar is also in Settings › Terminal.
Voice input
Section titled “Voice input”On iOS and Android, Session settings › Microphone button adds a floating button that dictates text into the focused pane. It’s off by default. Auto-enter after voice sends Enter after the dictated text.
Attachments
Section titled “Attachments”The compose bar’s Attach button uploads a file to ~/.pocketcmd/uploads on the server and inserts its absolute path into the command. Sources are Photos, Camera, Files and Clipboard, depending on the platform. Attachments need an SFTP connection, so Telnet sessions don’t offer them.
Attachments require PocketCmd Pro. On Free the button is grayed out and opens the upgrade sheet.
Running in the background
Section titled “Running in the background”Android
Section titled “Android”When PocketCmd goes to the background with work in progress, the Keep Alive Service shows a persistent notification so Android doesn’t freeze the app and drop connections. Configure it in Settings › Connection › Keep Alive Service:
| Toggle | Protects |
|---|---|
| Terminal connections | SSH, Mosh, Telnet and ET sessions |
| SFTP connections | Open file browser and workspace sessions |
| SFTP transfers | Running uploads and downloads |
| Port forwardings | Active forwarding rules |
With a category turned off, its connections are dropped when the app goes to the background: SSH, Telnet and SFTP sessions and forwards disconnect, and transfers pause and resume on return. Mosh and Eternal Terminal reconnect by design.
With the service running, an Eternal Terminal session keeps reading output while backgrounded, so it survives any length of time in the background, including under heavy output and resumes without a reconnect.
On Android 13 and later PocketCmd asks for notification permission only when you set up a push alert. Without the permission the service still runs; its notification appears in the system’s list of active apps instead of the notification shade.
iOS suspends apps shortly after they leave the foreground, so PocketCmd can’t hold connections in the background.
- Mosh and Eternal Terminal sessions are released cleanly when the app goes to the background and restored when you return. Eternal Terminal pauses the remote output first, so a session backgrounded in the middle of heavy output survives.
- SSH and Telnet connections drop once iOS suspends the app and reconnect when you return, which starts a new shell. Run your work in tmux to keep it across reconnects.
After the app restarts
Section titled “After the app restarts”Your open sessions and their split layouts are saved. After PocketCmd restarts, Mosh and Eternal Terminal sessions from the last seven days come back under Active Sessions and reattach to the same server-side session when you open them. The four most recently used are reconnected in the background right after start, so they’re ready when you tap them.
SSH and Telnet sessions end with the app process. Use Mosh, Eternal Terminal or tmux for work that must outlive the app.
Reconnecting
Section titled “Reconnecting”When a connection drops, PocketCmd recovers it with steps that depend on the protocol:
- Mosh heals short drops itself. The session shows as reconnecting and continues without a new login.
- Eternal Terminal reattaches to the same server-side session and replays the output you missed.
- SSH reconnects and opens a new shell. If the session was attached to tmux, the new shell reattaches the same tmux session.
- Telnet reconnects with a new connection.
If those steps fail while the device is online, PocketCmd retries after 1, 2, 4, 8 and 15 seconds, then every 30 seconds, up to 12 attempts, and then shows the session as failed with a Reconnect button. While the device is offline it waits for the network instead of using up attempts.
When the network changes (Wi-Fi to cellular, for example), Mosh moves to the new network at once, and sessions that dropped because the network went away retry as soon as it’s back.
Closing sessions
Section titled “Closing sessions”- Session settings › Close session, or Close Session in the switcher or the Active Sessions long-press menu.
- Close All in the session switcher closes every session.
- On a hardware keyboard, ⌘W (Ctrl+Shift+W on Windows, Linux and Android) closes the innermost thing that’s open: an editor tab if the pane has one, otherwise the session. ⌘⇧W (Ctrl+Shift+Q) always closes the session.
Closing a session ends its shells and any process running in them; PocketCmd asks first when a pane is still connected. For Mosh and Eternal Terminal, closing also ends the session on the server. A tmux session keeps running on the server, detached and you can reattach to it from the server sheet’s Sessions. The server itself stays saved.