Skip to content
ZestSSH Docs

Android Background Service

ZestSSH uses an Android foreground service to keep SSH sessions running when you switch to other apps. This page explains how the background service works and how to troubleshoot issues.

How It Works

Section titled “How It Works”

When you have an active SSH session and switch away from ZestSSH:

  1. ZestSSH starts an Android foreground service.
  2. A persistent notification appears in your notification shade, indicating an active SSH session.
  3. The SSH connection stays alive as long as the service is running.
  4. Tapping the notification returns you to ZestSSH.

This is the Android-recommended approach for long-running background operations. Unlike iOS, Android allows apps to maintain background network connections through foreground services.

Troubleshooting

Section titled “Troubleshooting”

Sessions Still Disconnecting

Section titled “Sessions Still Disconnecting”

If your sessions drop despite the foreground service:

  1. Disable battery optimization for ZestSSH:

    • Go to Android Settings > Apps > ZestSSH > Battery.
    • Select Unrestricted or No restrictions.
    • Some manufacturers (Samsung, Xiaomi, Huawei, OnePlus) have aggressive battery optimizers that kill foreground services. You may need to whitelist ZestSSH in manufacturer-specific battery settings.

  2. Check manufacturer-specific settings:

    • Samsung: Settings > Battery > Background usage limits > Never sleeping apps > Add ZestSSH.
    • Xiaomi/MIUI: Settings > Apps > ZestSSH > Battery Saver > No restrictions. Also: Security app > Battery > App battery saver > ZestSSH > No restrictions.
    • Huawei/EMUI: Settings > Battery > App launch > ZestSSH > Manage manually > Enable all toggles.
    • OnePlus: Settings > Battery > Battery optimization > ZestSSH > Don’t optimize.

  3. Enable keep-alive: Set keep-alive interval in your connection settings to prevent idle disconnections.

Notification Not Appearing

Section titled “Notification Not Appearing”

If you do not see the foreground service notification:

  1. Check that ZestSSH has notification permissions enabled in Android Settings.
  2. Ensure the notification channel is not muted or hidden.

High Battery Usage

Section titled “High Battery Usage”

The foreground service is lightweight — it maintains the TCP connection with minimal overhead. If you notice unusual battery drain:

  1. Check if keep-alive is set too aggressively (very short intervals).
  2. Consider using server-side tmux or screen sessions and disconnecting when not actively working, rather than keeping sessions open indefinitely.

Best Practices

Section titled “Best Practices”
  • Use tmux or screen on the server for long-running tasks. This way, you can safely disconnect and reattach later without losing work.
  • Disconnect sessions you are not using to save battery and network resources.
  • Set reasonable keep-alive intervals (30-60 seconds) to balance connection stability with battery life.
Section titled “Related”