User Guide

1. Getting Started

1.1 Installation

XuTerm is available on multiple platforms. Download from the channel that suits you best:

• Huawei AppGallery — For Huawei devices, search "XuTerm" or use the direct link.
• APKPure — For all Android devices. Download and install the APK directly.
• Appteka.store — An alternative Android app store.
• App Store — iOS version is coming soon.
• Google Play — Coming soon.

1.2 Your First SSH Connection

1. Open XuTerm. On first launch, you will see the host management screen.
2. Tap the + button in the top-right corner to add a new host.
3. Fill in the required fields:
   • Name — A friendly label for this connection (e.g., "Production Web Server").
   • Host — The server IP address or domain name.
   • Port — SSH port (default: 22).
   • Username — Your login username on the server.
4. Choose an authentication method:
   • Password — Enter the password. It will be encrypted and stored securely.
   • SSH Key — Select a previously added key pair (see SSH Key Management).
5. Tap Save, then tap the host card to connect.
6. On first connection, Android may ask for notification permission — this is used for the background keep-alive service to prevent the OS from killing the connection.

2. Host Management

2.1 Adding a Host

Tap the + button on the host management screen. The host form includes the following fields:

• Name (required) — Display name for the host.
• Host (required) — IP address or domain name.
• Port — Default is 22.
• Username (required) — SSH login username.
• Password — Stored with AES-256 encryption after saving.
• SSH Key — Select a key pair for key-based authentication.
• Group — Assign to a group for organized management.
• Description — Optional notes about this host.
• Use Mosh — Toggle to connect via Mosh protocol instead of SSH (see Mosh).
• Use tmux — Automatically attach or create a tmux session on connect (see tmux).
• Auto Reconnect — Automatically reconnect when the connection drops. Configurable interval (default: 30 seconds).
• Agent Forwarding — Enable SSH agent forwarding for this host.
• Jump Host — Select a proxy host for bastion/jump connections (see Proxy Jump).
• TOTP Token — Link a TOTP token for one-tap 2FA code fill (see TOTP).
• Enable Server Monitor — Turn on real-time server resource monitoring for this host.
• trzsz Upload Path — Set a custom local directory for trzsz file downloads.

2.2 Editing & Copying a Host

Long-press a host card to open the context menu with the following options:

• Edit — Modify the host configuration.
• Copy — Duplicate the host with a new name (useful for creating similar configurations).
• Share — Generate a QR code for this host (see QR Code Sharing).
• Disconnect — Close the active SSH connection to this host.
• Delete — Remove the host (with confirmation).

2.3 Groups & Sorting

Organize your hosts with color-coded groups:

• Tap the group+ button (next to the + button) to create a new group with a custom name and color.
• Select a group from the horizontal chip bar at the top to filter hosts by group.
• Drag to reorder: Long-press a group chip and drag to reorder groups. Long-press without dragging to edit or delete a group.
• In a group view, long-press and drag host cards to reorder them within the group.
• In the "All" view, hosts are displayed grouped under their group headers, and can be reordered within their own group.
• Groups that contain hosts cannot be deleted — you must move or delete the hosts first.

2.4 QR Code Sharing

Share host configurations instantly via QR code:

1. Long-press a host card and select Share, or use batch share (see below).
2. A QR code is generated containing the host's connection details.
3. Another device can scan the QR code to import the host configuration.

2.5 QR Code Scanning & Import

Tap the QR scanner button in the toolbar to scan a XuTerm QR code. The scanned host configuration will be imported directly into your host list.

2.6 Batch Operations

Tap the checklist button in the toolbar to enter multi-select mode:

• Tap hosts to select/deselect them.
• Use Select All to select all hosts in the current group.
• Tap Share to generate a QR code for all selected hosts at once.
• Tap Cancel or the back button to exit multi-select mode.

3. Terminal

3.1 Basic Terminal Operations

After connecting to a host, you are in the terminal screen. The top bar displays the connection status and host name. Key interactions:

• Type commands — Use the on-screen keyboard or an external keyboard.
• Scroll — Swipe up/down to scroll through terminal output history.
• Back button — Returns to the host list while keeping the connection alive in the background.
• Connection indicator — Shows connection state: connected (green), reconnecting (yellow), or disconnected (red).

3.2 Terminal Search

Search within the terminal output to quickly find information:

1. Tap the search icon in the terminal toolbar to open the search bar.
2. Type your search term — all matches are highlighted in real time.
3. Use the up/down arrows to navigate between matches. The terminal auto-scrolls to the current match.
4. The match counter (e.g., "3/15") shows the current match position and total count.
5. Tap Close or the back button to exit search mode.

3.3 Gesture Zoom

Use pinch-to-zoom gestures on the terminal to adjust the font size:

• Pinch outward — Increase font size.
• Pinch inward — Decrease font size.
• The font size changes smoothly and is applied immediately. Your preferred size is remembered per session.

3.4 Select & Copy

Copy text from the terminal output:

1. Long-press on the terminal to enter selection mode.
2. Drag the selection handles to extend the selection range.
3. The selected text is automatically copied to the clipboard.
4. Paste: Long-press the terminal input area and select Paste, or use the shortcut bar Paste button.

3.5 Keyboard Shortcut Bar

The shortcut bar above the keyboard provides quick access to special keys and actions:

• Tab, Ctrl, Alt, Esc — Modifier keys for terminal commands.
• Arrow keys — Up, Down, Left, Right for navigation.
• Home / End — Jump to the beginning or end of a line.
• Page Up / Page Down — Scroll by page.
• Function keys — F1 through F12.
• Tap Ctrl or Alt to activate them as sticky modifiers — the next key press will be sent with the modifier held.

3.6 Quick Commands

Save frequently used commands for one-tap execution:

1. In the terminal, tap the Quick Commands button (rocket icon) in the toolbar.
2. Browse your saved commands, organized by category.
3. Tap a command to send it directly to the terminal.
4. To manage commands, go to the Quick Commands management screen (accessible from Settings > Terminal > Quick Commands).

Quick command management features:

• Add — Create a new command with name, content, and category.
• Edit / Delete — Long-press a command for options.
• Reorder — Drag commands to rearrange them.
• QR Code Import/Export — Share and import quick commands via QR code.

3.7 Command Snippets

Command Snippets are reusable multi-line script templates, more powerful than quick commands:

1. In the terminal, tap the Snippets button in the toolbar.
2. Browse snippets by group.
3. Tap a snippet to paste its content into the terminal input.

Snippet management (accessible from Settings > Terminal > Command Snippets):

• Add — Create a snippet with name, content, and group.
• Drag to reorder — Rearrange snippets within a group.
• Edit / Delete — Long-press for options.
• Supports custom grouping for organization.

3.8 Command History

Quickly re-run previously executed commands:

1. Tap the History button (clock icon) in the terminal toolbar.
2. Browse the list of previously executed commands for the current session.
3. Tap a command to send it to the terminal again.

3.9 sudo Password Auto-Fill

If you have stored a sudo password for a host, XuTerm detects sudo prompts automatically:

1. When the terminal shows a sudo password prompt, a fill button appears.
2. Tap the button to automatically fill in the sudo password.

3.10 TOTP 2FA Code Fill

When a host has a linked TOTP token, XuTerm can auto-generate and fill 2FA codes:

1. When the terminal shows a two-factor authentication prompt, a fill button appears.
2. Tap the button to generate and insert the current TOTP code.

See TOTP Two-Factor Authentication for setup instructions.

4. Mosh — Mobile Shell

Mosh (Mobile Shell) is an alternative to SSH that handles intermittent connections, network roaming, and high-latency networks gracefully. It provides instant responses and automatic reconnection.

4.1 Enabling Mosh

1. Edit the host configuration (see Editing a Host).
2. Toggle Use Mosh to ON.
3. Save the host. The next connection will use the Mosh protocol.

4.2 Mosh Configuration

• Mosh Port — Specify a particular UDP port for the Mosh connection. Leave empty for automatic selection.
• Mosh Server Path — If mosh-server is installed in a non-standard location, specify the full path here.

When connected via Mosh, the terminal top bar displays a "Mosh" badge indicating the active protocol.

5. tmux Integration

XuTerm provides deep integration with tmux, making multiplexer sessions feel native on mobile devices.

5.1 Enabling tmux

1. Edit the host configuration.
2. Toggle Use tmux to ON.
3. Optionally specify a tmux Session Name. If left empty, XuTerm creates a new session or attaches to the most recent session.
4. Save and connect. XuTerm automatically runs tmux attach or tmux new-session upon connection.

5.2 tmux Action Bar

When a tmux session is active, a dedicated action bar appears at the bottom of the terminal:

• Window tabs — Visual tabs for each tmux window. Tap to switch between windows instantly.
• New Window — Create a new tmux window.
• Kill Window — Close the current tmux window.
• Rename Window — Rename the current window.
• Split Pane — Split the current pane horizontally or vertically.
• Navigate Panes — Switch focus between split panes.
• Detach — Detach from the tmux session (the session continues running on the server).

5.3 tmux Theme

XuTerm applies a custom tmux theme optimized for mobile viewing. The status bar is styled to match the app theme and integrates seamlessly with the terminal display. This is applied automatically when tmux is enabled.

6. SFTP File Browser

XuTerm includes a built-in SFTP file browser for managing files on remote servers.

6.1 Browsing Files

1. While connected to a host, tap the SFTP button in the terminal toolbar to open the file browser.
2. The browser opens at the SSH session's working directory by default (or the home directory).
3. Navigate by tapping directories. Tap .. or use the path bar to go up a level.
4. The path bar at the top shows the current directory — tap any segment to jump directly to that level.
5. Tap the home icon to jump to the home directory.
6. Use the sort button to sort files by name, size, or modification time.
7. Toggle show/hide hidden files using the eye icon in the toolbar (files starting with a dot).
8. Use the search icon to filter files by name in the current directory.

6.2 Upload & Download

Upload (local to remote):

1. Tap the upload button in the SFTP toolbar.
2. Select files from your device using the file picker.
3. Files are uploaded to the current remote directory.
4. A progress bar shows the transfer status in real time.

Download (remote to local):

1. Long-press a file or directory to select it, then tap Download.
2. Or tap a file to preview it first, then use the download option.
3. Downloaded files are saved to your device's Downloads directory (or the custom trzsz upload path).

6.3 File Operations

Long-press a file or directory to access the context menu:

• Open / Preview — Open the file with the built-in viewer or an external app.
• Edit — Open the file in the built-in code editor (see File Preview & Editing).
• Rename — Change the file or directory name.
• Delete — Remove the file or directory (with confirmation).
• Permissions — View and modify file permissions (chmod).
• Download — Download to the local device.
• Copy Path — Copy the full file path to the clipboard.
• Hash — Calculate the file's MD5, SHA1, or SHA256 checksum.

Additional toolbar actions:

• New File — Create a new empty file in the current directory.
• New Directory — Create a new folder.

6.4 File Preview & Editing

XuTerm can preview and edit various file types directly:

• Text / Code files — Open in the built-in code editor with syntax highlighting for many languages (Python, JavaScript, Go, Rust, YAML, JSON, etc.). The editor supports find/replace, line numbers, and direct save back to the remote server.
• PDF files — View with the built-in PDF viewer. Supports zoom and page navigation.
• Excel / CSV files — Preview spreadsheet data in a tabular view.
• Images — View images (PNG, JPG, GIF, BMP, WebP, SVG) with pinch-to-zoom.
• Markdown — Render and preview Markdown files with proper formatting.
In the code editor, use the Find feature to search within the file. Matched results are highlighted and you can navigate between them with previous/next buttons. The editor auto-detects the file language for syntax highlighting.

6.5 Cellular Data Transfer

By default, XuTerm warns you before transferring files over a cellular (mobile data) connection:

1. When you initiate a file transfer on cellular data, a confirmation dialog appears.
2. You can choose to proceed or cancel.
3. To always allow cellular transfers, enable Allow Cellular Transfer in Settings > Connection.

6.6 File Hash Verification

Verify file integrity by calculating checksums:

1. Long-press a file and select Hash.
2. Choose the algorithm: MD5, SHA1, or SHA256.
3. The hash value is displayed and can be copied to the clipboard.

7. trzsz File Transfer

trzsz provides a terminal-based file transfer experience similar to lrzsz (rz/sz), but with tmux compatibility and better progress display.

1. Ensure the remote server has trzsz installed (the Python package trzsz or trzsz-go).
2. Upload: Type trz in the terminal. XuTerm opens a file picker. Select files and confirm.
3. Download: Type tsz <filename> in the terminal. The file is downloaded to your device.
4. A real-time progress bar is displayed during the transfer, showing the file name, percentage, and transfer speed.

You can configure the default download directory in Settings > Connection, or per-host via the trzsz Upload Path field.

8. Port Forwarding

XuTerm supports SSH port forwarding with three modes.

8.1 Local Port Forwarding (-L)

Forward a local port to a remote address through the SSH tunnel. This is the most common type.

Example: Access a remote database that only listens on localhost:

• Bind Address: 127.0.0.1
• Bind Port: 3306 (local port on your device)
• Target Address: 127.0.0.1 (from the remote server's perspective)
• Target Port: 3306 (the remote service's port)

After enabling, connect to 127.0.0.1:3306 on your device to access the remote database.

8.2 Remote Port Forwarding (-R)

Forward a port on the remote server to a local address. Useful for exposing a local service to the remote network.

8.3 Dynamic (SOCKS) Forwarding (-D)

Create a SOCKS proxy that tunnels traffic through the SSH connection. Specify a local bind address and port, then configure your apps to use it as a SOCKS5 proxy.

8.4 Auto-Start on Connection

Port forwarding rules can be configured to start automatically when you connect to a host:

1. Create port forwarding rules in the Port Forwarding screen (accessible from the terminal toolbar or Settings).
2. Toggle the Enabled switch for each rule to control whether it auto-starts.
3. When connecting, all enabled rules are established automatically.

9. Proxy Jump (Bastion Host)

Connect to a target server through an intermediate bastion host / jump server:

1. First, add the bastion host as a regular host in XuTerm.
2. Edit the target host configuration.
3. In the Jump Host field, select the bastion host you added.
4. Save and connect. XuTerm establishes an SSH connection to the bastion first, then tunnels through to the target server.

10. SSH Key Management

10.1 Generating a Key

1. Navigate to the SSH Keys management screen (accessible from Settings or the host form).
2. Tap Add and select Generate New Key.
3. Choose the key type:
   • RSA — Widely compatible, 2048/3072/4096 bit.
   • ECDSA — Modern, efficient, 256/384/521 bit.
   • Ed25519 — Recommended for new deployments, strongest security with smallest key size.
4. Optionally set a passphrase for the private key.
5. Tap Generate. The key pair is created and stored securely on the device.
6. You can copy the public key to add it to the server's ~/.ssh/authorized_keys.

10.2 Importing a Key

1. Tap Add and select Import Key.
2. Paste the private key content or select a key file from your device.
3. If the key is encrypted, provide the passphrase.
4. The key is imported and stored with AES-256 encryption.

10.3 Assigning a Key to a Host

1. Edit a host configuration.
2. In the SSH Key dropdown, select the key pair you want to use.
3. Clear the password field if you want key-only authentication.
4. Save and connect.

11. TOTP Two-Factor Authentication

11.1 Adding a TOTP Token

1. Navigate to the TOTP Tokens management screen.
2. Tap Add to create a new token.
3. Enter the token details:
   • Name — A label for this token (e.g., "GitHub 2FA").
   • Secret — The base32-encoded secret from the service.
   • Group — Organize tokens into groups.
4. Alternatively, scan a QR code to auto-fill the secret.
5. Save the token. The current code and countdown timer are displayed.

Token management features:

• Edit / Delete — Modify or remove tokens.
• Groups — Organize tokens with custom groups and colors.
• QR Code Sharing — Share token configurations via QR code (secret is encrypted).

11.2 Using TOTP in Terminal

1. Link a TOTP token to a host in the host's configuration (TOTP Token field).
2. When the terminal displays a 2FA prompt, a fill button appears.
3. Tap the button to generate and auto-fill the current 6-digit code.

12. Server Monitoring

Monitor server resources in real time during an SSH session.

1. Enable Server Monitor in the host configuration.
2. When connected, a monitoring bar appears at the top of the terminal showing:
   • CPU usage — Real-time percentage with sparkline chart.
   • Memory usage — Used vs. total with percentage.
   • Disk usage — Used vs. total with percentage.
   • Load average — 1-minute, 5-minute, 15-minute.
3. Tap the monitor bar to open the detailed monitoring view, which includes:
   • CPU, memory, disk, and load details with visual charts.
   • Process list — View running processes sorted by CPU or memory usage.
   • Kill process — Select a process and send a kill signal.

Configure the refresh intervals in Settings > Server Monitor:

• Bar interval — How often the top-bar summary refreshes (3-60 seconds, default: 5).
• Detail interval — How often the detailed view refreshes (1-30 seconds, default: 3).

13. Session Snapshots

Save and restore terminal session states for quick recovery:

1. While connected, tap the Snapshot button in the terminal toolbar.
2. A snapshot of the current session is saved, including:
   • The host connection details.
   • The terminal scrollback buffer (visible output).
   • The timestamp.
3. Access saved snapshots from the Session Snapshots management screen.
4. Tap a snapshot to restore the session state and reconnect to the host.
5. Delete snapshots you no longer need.

14. Multi-Session Management

XuTerm supports connecting to multiple servers simultaneously:

• Connect to multiple hosts — Each connection opens a new terminal tab.
• Switch between sessions — Use the tab bar at the top of the terminal screen to switch between active connections.
• Background sessions — Connections stay alive in the background when you navigate away. The host list shows active connections with a badge counter.
• Re-enter a session — Tap a connected host in the host list to return to its terminal.

15. Settings

15.1 Biometric Lock

Protect XuTerm with biometric authentication:

1. Go to Settings and toggle Biometric Unlock.
2. The app will use your device's biometric hardware (Face ID, Touch ID, or fingerprint).
3. After enabling, you'll need to authenticate each time you open the app.

15.2 Terminal Settings

Access via Settings > Terminal. Configure:

• Quick Commands — Manage your saved quick commands.
• Command Snippets — Manage command snippet groups and entries.
• Shortcut Keys — Customize which keys appear in the shortcut bar. Enable/disable individual keys, add custom key bindings.
• tmux — Configure tmux integration behavior.

15.3 Font Settings

Access via Settings > Terminal Font. Configure:

• Font Size — Default terminal font size (adjustable from 8 to 28).
• Line Height — Spacing between terminal lines (1.0x to 2.0x).
• Font Family — Choose from built-in monospace fonts:
  • Source Code Pro
  • JetBrains Mono
  • Fira Code
  • Cascadia Code

15.4 Color Bar

The color bar is a vertical colored strip on the left side of the terminal that visually distinguishes user input from server output:

• Go to Settings > Color Bar to configure.
• Enable/Disable — Toggle the color bar on or off.
• Input Color — The color for lines you typed.
• Output Color — The color for server response lines.

15.5 Connection Settings

Access via Settings > Connection. Configure:

• Port Forwarding Auto-Start — Whether to automatically establish port forwarding rules when connecting.
• SFTP Show Hidden Files — Default visibility of hidden files in the SFTP browser.
• Allow Cellular Transfer — Skip the cellular data warning when transferring files.
• trzsz Settings — Configure default upload/download directories for trzsz.

15.6 Monitor Settings

Configure server monitoring refresh intervals (see Server Monitoring).

15.7 Theme & Appearance

Go to Settings and configure:

• Theme Mode — Choose from:
  • Light Mode
  • Dark Mode
  • Follow System
• Screen Orientation Lock — Lock the screen orientation to prevent rotation.

15.8 Language

XuTerm supports multiple languages:

• Simplified Chinese
• Traditional Chinese
• English
• Japanese
• Russian
• Follow System

Go to Settings > Language to change the display language. The change takes effect immediately.

16. Data Management

16.1 Exporting Configuration

Back up your XuTerm configuration to a file:

1. Go to Settings > Data Management > Export.
2. Select which data to export:
   • Hosts
   • SSH Keys
   • Quick Commands
   • Command Snippets
   • Port Forwarding Rules
   • TOTP Tokens
3. Optionally encrypt the export with a password for security.
4. Tap Export to save the configuration file to your device.

16.2 Importing Configuration

Restore a previously exported configuration:

1. Go to Settings > Data Management > Import.
2. Select the configuration file from your device.
3. If the file is encrypted, enter the password to decrypt it.
4. Review the contents and confirm the import.
5. Imported data is merged with existing data — duplicates are handled intelligently.

16.3 iCloud Sync (iOS)

On iOS devices, XuTerm supports iCloud sync to keep your configuration consistent across all your Apple devices:

1. Go to Settings > Data Management > iCloud Sync.
2. Enable iCloud sync. Your configuration is uploaded to iCloud automatically.
3. On another iOS device with the same Apple ID, enable iCloud sync to download the configuration.
4. Changes are synced bidirectionally.

17. Security & Privacy

XuTerm is designed with security and privacy as top priorities:

• AES-256 Encryption — All sensitive data (passwords, SSH keys, TOTP secrets) is encrypted with AES-256 before storage.
• Secure Key Storage — SSH private keys and passwords are stored in the device's secure hardware (iOS Keychain / Android Keystore) when available.
• Biometric Protection — Optional Face ID / Touch ID / fingerprint lock prevents unauthorized access.
• Zero Data Collection — XuTerm does not collect, transmit, or share any personal data. There are no analytics, trackers, or ads.
• Local-Only Storage — All data is stored locally on your device. iCloud sync is optional and encrypted.
• Encrypted Exports — Configuration exports can be password-protected for safe transfer.