Connecting

A server in PocketCmd is a saved connection. You fill in the server form when you add a server (New Server) or tap the edit button in a server’s sheet (Edit Server). This page covers the form and the app-wide settings under Settings › Connection.

The server form

Field	Notes
Display Name	Required. The name shown on the home screen and in sessions.
Group and Tags	Optional. See Server Organization.
Hostname	Required. A hostname or IP address.
Port	22 by default; 23 when Telnet is selected.
Username	The login user.
Protocol	SSH or Telnet. Mosh and ET appear after Test Connection finds them on the host. See Compare Protocols.
Authentication	Password, SSH Key or None.
Enable tmux	Starts each new terminal inside a tmux session. Appears after a test or when editing. See tmux Integration.
Show in Files	SSH servers only, when editing a saved server. See System File Manager.
Advanced	Jump Host, Terminal type (TERM), Startup command and Forward SSH agent. Collapsed unless one of them is set.

If the server belongs to a group, the hostname, port, username, authentication, password, key, jump chain and agent forwarding can come from the group’s settings. The form shows which group a value is inherited from, and editing the field overrides it for this server only.

The bar at the top of the form mirrors the connection as an ssh command line. Type or paste arguments such as -p 2222 -A [email protected] into it to fill in the form; changes to the form update the bar.

Authentication

Password

The password is sealed with your vault key before it is written to the device’s secure storage.

SSH key

Choose Use Saved Key to pick a key from your key library, or Add new key to generate or import one. Keys are entered and managed on the key management screen, not in the server form. See Key Management.

None

For servers that accept a login without credentials. The form warns: “Not recommended. Only for servers allowing unauthenticated access.”

Two-factor and keyboard-interactive

Servers that ask for a one-time code through PAM, Duo, Google Authenticator or another keyboard-interactive method work without extra setup:

• When the server asks only a single hidden question (the usual Password: prompt), PocketCmd answers it with the stored password and shows nothing.
• When there is a further round, such as a request for a code, PocketCmd shows a dialog with the server’s own prompts and instructions. Any number of prompts is supported, and each is masked if the server asks for it.
• You have two minutes to answer, which leaves time for a push approval on another device.
• Dismissing the dialog cancels the login instead of sending empty answers.

After three failed connection attempts in a row, PocketCmd waits 30 seconds before trying that server again (“Too many failed connection attempts. Wait a moment, then try again.”). A rejected password or code does not count toward this; the server’s own limit applies instead.

Test Connection

Test Connection sits directly above the save button and checks the configuration as entered:

1. It connects to the host and port, through the server’s jump chain if one is set.
2. On the first connection to a host, it shows the host key fingerprint for you to confirm. No credentials are sent until you accept it.
3. It logs in with the chosen credentials, using the same two-factor dialog as a terminal session.
4. After a successful login, it checks the server for mosh-server, etserver and tmux, and offers Mosh, ET and Enable tmux accordingly.

A failed test shows the reason. Dismissing a two-factor dialog reports that authentication was canceled rather than blaming the password. Save without testing stores the server without a test.

For a Telnet server, the test opens the TCP connection, runs auto-login if it is on, and checks for tmux.

Advanced

Jump Host

Route the connection through one or more saved servers. See Multi-Hop SSH.

Terminal type (TERM)

The terminal type PocketCmd reports to the server, for all four protocols. It defaults to the app-wide Default Terminal Type (xterm-256color). The value must name a terminfo entry installed on the server.

Startup command

A command typed into each new shell once it starts, for example a cd into a project directory or export COLORTERM=truecolor. Only the first line is used.

The command runs whenever PocketCmd starts a new shell: on the first connection and when an SSH reconnect has to open a fresh shell. It does not run again when a Mosh or ET session is resumed, or when PocketCmd reattaches to a tmux session it already set up, so it is never typed into a program that is running there.

Startup commands require PocketCmd Pro. On Free, a saved command stays on the server but does not run.

Forward SSH agent

Lets commands on the server sign with keys held in PocketCmd; the keys never leave the device. SSH only.

Finding a server after its IP address changed

A server saved with a LAN address stops answering when its DHCP lease moves. PocketCmd can scan the local network and recognize the machine by its pinned SSH host key, so the match needs no credentials and cannot pick the wrong host. When you accept the match, PocketCmd updates the server’s address and keeps the host key pinned.

The scan is available from:

• the Scan the local network for addresses button on the Hostname field
• Scan network for its new IP in the server sheet, shown when a server saved with an IPv4 address does not answer
• the connection-failure screen, when a private IPv4 address timed out

If more than one network could be scanned, you choose which:

Network	Behavior
Wi-Fi or Ethernet	Offered and preselected
VPN or tunnel	Offered under VPN and tunnels, never preselected, with a longer timeout per host
A range you type	Accepted as a CIDR between /22 and /30, for example 10.8.0.0/24
Cellular	Never scanned

The scan itself only reads host keys: it never logs in and never changes what PocketCmd trusts.

Finding a server that moved requires PocketCmd Pro. On Free, the Hostname button and the server sheet entry open the upgrade sheet, and the connection-failure screen does not offer a scan.

Connection settings

These apply to every server and live under Settings › Connection:

Setting	Default	Range
SSH Connect Timeout	10 s	5–60 s
Idle Connection Timeout	5 min	1–30 min
SSH Keepalive Interval	30 s	0–60 s (0 turns keepalive off)
Default Terminal Type	xterm-256color	Presets or a custom value
Advertise Truecolor	On	n/a

Idle Connection Timeout controls the shared SSH connection, not your shell. PocketCmd keeps one connection per server for terminals, Files, port forwards and dashboard polling, so exit ends the shell while the connection stays open until it has been idle this long. On a two-factor host, you are not asked for a new code while it is open. Lower the value if you want exit to feel like a logout sooner.

Advertise Truecolor sets COLORTERM so programs on the server use 24-bit color. Many SSH servers refuse that environment request; if colors look flat, put export COLORTERM=truecolor in the server’s startup command or your shell profile. Over Mosh the variable is passed on the mosh-server command line and always arrives.

On Android, Keep Alive Service controls the foreground service that keeps connections open in the background. See Session Management.

What happens when you connect

Tapping a server’s tile on the home screen opens a new terminal with the server’s protocol and tmux setting, or with the last pick made in its server sheet. For SSH, PocketCmd resolves the host, opens the TCP connection, checks the host key, logs in and opens a shell (inside tmux if enabled). Mosh and ET start through an SSH login first; see How Mosh and ET connect.

On the first connection to a host you confirm its fingerprint (Verify host key). If a pinned key later changes, the session stops with Host key changed and shows both fingerprints. Choose Trust new key only if you know the server’s key was rotated.

If the connection drops, PocketCmd reconnects on its own. How it does that depends on the protocol; see SSH reconnection and Session Management.

On Free, only one saved server is active. A server that is paused by the Free limit, or one whose jump host is paused, cannot connect or run a connection test; PocketCmd explains why (“This server is paused”, “Its jump host is paused”). See Free and Pro.

Connection errors

Message	Likely cause
Connection refused by … Is the service running on that port?	Nothing listens on that port, or a firewall rejects the connection.
Connection to … timed out.	The host is unreachable, or the address or port is wrong.
Could not resolve …	The hostname does not resolve. Check the spelling and DNS.
Authentication failed. Check the credentials for …	Wrong password or key, or the user may not log in over SSH.
The server’s host key does not match the one saved for it.	The server’s key changed since the last connection.
Too many failed connection attempts. Wait a moment, then try again.	Three attempts in a row failed; PocketCmd pauses that server for 30 seconds.

More fixes are in Troubleshooting.