Skip to content
ZestSSH Docs

Android Background Connections

Android allows background services but aggressively optimizes battery usage. OEM skins (MIUI, One UI, ColorOS, etc.) add additional restrictions that can kill ZestSSH’s background connections.

Battery Optimization Exemption

Section titled “Battery Optimization Exemption”

The most important step is to exempt ZestSSH from battery optimization:

Stock Android / Pixel

Section titled “Stock Android / Pixel”
  1. Go to Settings > Apps > ZestSSH > Battery.
  2. Set to Unrestricted (not “Optimized” or “Restricted”).

Samsung One UI

Section titled “Samsung One UI”
  1. Settings > Apps > ZestSSH > Battery.
  2. Toggle off Put app to sleep and Allow background activity.
  3. Settings > Device Care > Battery > Background Usage Limits.
  4. Add ZestSSH to the Never sleeping apps list.

Xiaomi MIUI / HyperOS

Section titled “Xiaomi MIUI / HyperOS”
  1. Settings > Apps > Manage Apps > ZestSSH.
  2. Tap Battery saver and set to No restrictions.
  3. Settings > Battery > App Battery Saver and set ZestSSH to No restrictions.
  4. Also enable Autostart for ZestSSH in the app settings.
  5. Lock ZestSSH in the recent apps tray (swipe down on the app card to lock).

OPPO ColorOS / Realme UI

Section titled “OPPO ColorOS / Realme UI”
  1. Settings > Battery > Battery Optimization.
  2. Find ZestSSH and set to Don’t optimize.
  3. Settings > App Management > ZestSSH.
  4. Enable Allow auto-startup and Allow background activity.

OnePlus OxygenOS

Section titled “OnePlus OxygenOS”
  1. Settings > Battery > Battery Optimization.
  2. Set ZestSSH to Don’t optimize.
  3. Settings > Apps > ZestSSH > Battery Usage and enable Allow background activity.

Huawei EMUI / HarmonyOS

Section titled “Huawei EMUI / HarmonyOS”
  1. Settings > Apps > Apps > ZestSSH > Battery.
  2. Disable Manage automatically and enable Allow background activity.
  3. Settings > Battery > App Launch and set ZestSSH to Manage manually with all toggles on.
  4. Lock ZestSSH in the recent apps tray.

Foreground Service

Section titled “Foreground Service”

ZestSSH runs a foreground service notification while SSH sessions are active. This tells Android the app is doing important work and should not be killed. The notification shows the number of active connections.

If you do not see the foreground service notification while connected:

  1. Check that ZestSSH has notification permissions (Settings > Apps > ZestSSH > Notifications).
  2. Make sure the notification channel is not silenced.

The foreground service is essential for keeping connections alive. Do not disable it.

Keep-Alive Settings

Section titled “Keep-Alive Settings”

Configure SSH keep-alive to prevent idle timeout drops:

  1. In the connection editor, set Keep-Alive Interval to 15-30 seconds.
  2. This sends periodic SSH packets that keep the connection active through NAT gateways and firewalls.

WorkManager and Scheduled Tasks

Section titled “WorkManager and Scheduled Tasks”

ZestSSH uses Android’s WorkManager for scheduled automation tasks. WorkManager is designed to run reliably even under battery restrictions, but OEM modifications can interfere.

WorkManager Issues

Section titled “WorkManager Issues”
  • Delayed execution: WorkManager may defer tasks when the device is in Doze mode. Exact timing is not guaranteed.
  • Skipped executions: Some OEMs aggressively kill WorkManager jobs. The battery optimization exemptions above help prevent this.
  • After reboot: WorkManager jobs survive reboots, but the first execution after reboot may be delayed.

Improving Reliability

Section titled “Improving Reliability”
  1. Apply all battery optimization exemptions listed above.
  2. Keep ZestSSH installed on internal storage (not SD card).
  3. Do not use “Force Stop” on ZestSSH in settings.

Common Symptoms

Section titled “Common Symptoms”

Connection drops when screen turns off

Section titled “Connection drops when screen turns off”

Cause: Battery optimization is killing ZestSSH’s process. Fix: Apply battery optimization exemptions and ensure the foreground service notification is visible.

Connection drops on network switch (Wi-Fi to cellular)

Section titled “Connection drops on network switch (Wi-Fi to cellular)”

Cause: TCP connections are tied to a specific network interface. When the interface changes, the existing TCP connections break. Fix: Enable SSH keep-alive (15 seconds) so the connection is quickly re-established if the interruption is brief. For full resilience, use tmux on the server so you can reconnect seamlessly.

Automation tasks not running on schedule

Section titled “Automation tasks not running on schedule”

Cause: OEM battery optimization is killing WorkManager jobs. Fix: Apply all battery optimization exemptions and ensure ZestSSH is in the “Never sleeping” or “Unrestricted” category.

Connection works but drops after exactly 10/15/30 minutes

Section titled “Connection works but drops after exactly 10/15/30 minutes”

Cause: Your network’s NAT gateway is dropping idle TCP connections. Mobile carriers often have aggressive NAT timeouts. Fix: Set keep-alive interval to a value less than the NAT timeout (typically 15 seconds works for most carriers).

Testing Background Reliability

Section titled “Testing Background Reliability”

To verify your setup:

  1. Connect to a server in ZestSSH.
  2. Run watch -n 5 date on the server (prints the time every 5 seconds).
  3. Switch away from ZestSSH and use other apps for 5-10 minutes.
  4. Switch back to ZestSSH. If the date output is continuous (no gaps), background connections are working.
  5. Lock the screen for 5-10 minutes, then unlock. Check if the session is still alive.

If the connection drops during these tests, review the battery optimization settings for your specific device manufacturer.

Reference: dontkillmyapp.com

Section titled “Reference: dontkillmyapp.com”

The website dontkillmyapp.com maintains a comprehensive database of OEM-specific battery optimization settings. Look up your device manufacturer for the latest instructions.