ServerBox README

The project's README from github.com/madeye/ServerBox. As one markdown file: README.md.

ServerBox

Turn a used Android phone into a Linux server, no root required.

An old phone is a small, quiet, low-power computer with a battery backup and Wi-Fi built in. ServerBox puts a real Linux distribution on it and keeps an SSH server running, so you can use it like any other box on your network: host services, run scripts and cron jobs, or tinker.

ServerBox is a fork of UserLAnd by CypherpunkArmory (UserLAnd Technologies, LLC) and, like UserLAnd, is licensed under the GPLv3.

What it does

Screenshots

Apps New filesystem Server settings
Apps tab listing the Linux distributions and the coding agents Creating a filesystem with a user name and password Server settings: start on boot, SSH from the network, authorized keys

Download

Get the APK from Releases. ServerBox needs Android 8.0 or later. Every distribution is available for 64-bit ARM (nearly all current phones) and x86_64; 32-bit support varies by distribution.

Releases are signed with this certificate (SHA-256), which you can check with apksigner verify --print-certs serverbox-<version>.apk:

55:40:C1:F2:4F:5D:44:86:C5:96:EF:76:0A:8C:E9:8C:8E:68:FE:45:AF:C9:E9:54:1C:C6:3D:EF:3E:7A:76:B5

Builds from before 1.0 were signed with a different key, so Android can't update them to a release: uninstall the old build first. Uninstalling deletes its distributions and sessions.

Getting started

  1. Install ServerBox and open it.
  2. Pick a distribution on the Apps tab. ServerBox downloads it (the setup log shows each step) and opens a terminal.
  3. Open the Sessions tab for the SSH command, user and password.
  4. To connect from your computer, turn on Settings → Allow SSH from the network, then run the command shown on the Sessions tab.

Keeping the server running

Android pauses background apps to save battery, which makes a server stop answering once the screen is off. When ServerBox first runs a server it asks to be exempted from battery optimization; allow it. Some vendors add their own restrictions on top:

Keep the phone on a charger, and consider reserving its IP address in your router so the SSH address stays the same.

Building

Builds need JDK 17.

./gradlew :app:assembleServerBoxDebug
./gradlew testServerBoxDebugUnitTest :terminal:testDebugUnitTest lintServerBoxDebug

Instrumented tests (Room migrations and DAOs, the terminal's PTY) run on a connected device or emulator:

./gradlew :library:connectedServerBoxDebugAndroidTest :terminal:connectedDebugAndroidTest

./gradlew :app:assembleServerBoxRelease signs the release APK when a keystore is configured in local.properties (or the same names as environment variables); without one it builds unsigned:

KEYSTORE_PATH=/path/to/keystore
KEYSTORE_PASSWORD=...
KEY_ALIAS=...
KEY_PASSWORD=...

The distribution images are built in madeye/ServerBox-Images and published to ghcr.io/madeye/serverbox-<distro>.

Credits

ServerBox is forked from UserLAnd and its library (UserLAndLibrary) by CypherpunkArmory (UserLAnd Technologies, LLC), who hold the copyright on the original code. ServerBox's changes are copyright Max Lv. Like UserLAnd, ServerBox is released under the GNU General Public License v3; the full text is in LICENSE and the copyright notices are in COPYRIGHT.

ServerBox (madeye/ServerBox)

Searching Database…

264 ·GitHub
ServerBox
What is this?ServerBox is an Android app that turns an old phone into a Linux server without rooting it, running Alpine, Arch, Debian, Kali or Ubuntu with an always-on SSH server.
Is this a rooting tool or does it work on a stock phone?No root needed: the Linux distributions run entirely in user space through PRoot, like a container on top of stock Android.
How do I get a Linux server running on my phone?Install the APK, pick a distribution on the Apps tab (it downloads and opens a terminal), then check the Sessions tab for the SSH command, user and password.
Does my old phone need to be a specific model?Any phone running Android 8.0 or later works; distributions are built for 64-bit ARM (most current phones) and x86_64, with varying 32-bit support.
Does the SSH server keep running with the screen off?Android's battery optimization normally kills background apps once the screen is off, so you have to exempt ServerBox, and some vendors (e.g. Xiaomi/MIUI) need extra Autostart and battery-saver settings to keep sessions alive.
Does it come with AI coding agents preinstalled?The Claude and Codex apps are Debian images with Anthropic's Claude Code or OpenAI's Codex CLI preinstalled, plus Node.js, git and ripgrep. You just SSH in and sign in with your own account or API key.
Can I make a service start automatically with the server?Yes, drop executables into /etc/serverbox/autostart.d inside the distribution and they run every time its server starts, with logs in /var/log/serverbox-autostart.log.
Can a distribution run as a real VM instead of PRoot?On phones that support the Android Virtualization Framework, distributions can also run as a full virtual machine through a companion app.
Can I access files from the phone's storage inside the Linux distro?Yes, shared phone storage is mounted at /sdcard inside each distribution, and ServerBox prompts for folder access the first time a program needs it.
What are similar projects?ProxmoxVE, Podroid, distrobox, DroidDeck, termux-app, openvpn-install, setup-ipsec-vpn, VirtualXposed
Which topics is it in?alpine-linux, kali-linux, pty, archlinux, debian, ubuntu, apk, virtual-machine, homelab, virtualization, ssh, android-app
Creator
madeye
Size
41.5 MB
Stars
264
Updated
CommitOct 10Releasev1.1Oct 01
Age
21d
Commits · 90 Days