phone-server-setup

---
name: phone-server-setup
description: Set up a rooted Android phone as an always-on backup and mirroring server. Installs Termux tooling, ssh, self-healing services, a verified charge cap, and Syncthing. Use after the phone is already unlocked and rooted. Also use when asked to diagnose or repair an existing phone server.
---

# Phone server setup

You are configuring a **rooted Android phone** into an always-on backup server, following
this repository's design. Work through the phases in order. Each phase has a **verification
gate**: do not advance until it passes, and never report a phase complete on the basis of a
command exiting 0.

## Hard rules

1. **Never run Step 0.** Bootloader unlocking and rooting wipe the device and need physical
   button presses. If the phone is not already rooted, stop and point the user at
   `docs/00_ROOTING.md`. Do not attempt to unlock, flash, or root anything.
2. **Never flash any partition.** No `fastboot flash`, no `dd` to a block device, ever.
3. **Confirm before destructive or hard-to-reverse actions**: factory settings changes,
   deleting user data, changing the charge configuration on a device you have not verified,
   or anything touching `/data` outside app directories.
4. **This device is the user's, and it may be doing other work.** Before you install, restart,
   or kill anything, check what is already running (`tmux ls`, `ps`). If you find services you
   did not create, ask before touching them.
5. **Verify by effect, not by exit code.** A command that succeeded is not proof the thing
   works. Every phase below says what real evidence looks like.
6. **Do not exfiltrate anything.** Do not read, copy, or transmit the user's files, photos,
   messages, credentials, or tokens. You are configuring infrastructure, not inspecting data.

## Phase 0: connect and profile the device

Establish a connection. Prefer adb over USB for the first run; switch to ssh once it works.

```bash
adb devices
adb shell getprop ro.product.model
adb shell getprop ro.build.version.release
adb shell getprop ro.product.cpu.abi
adb shell su -c id
```

Record: model, Android version, architecture, total RAM (`free -m`), free storage
(`df -h /data`), and whether root works.

**Gate:** `adb shell su -c id` prints `uid=0(root)`. If it does not, the phone is not rooted:
stop and point at `docs/00_ROOTING.md`.

> On Windows/Git Bash, prefix adb commands that contain device paths with
> `MSYS_NO_PATHCONV=1`, or `/sdcard/...` gets rewritten into a Windows path.

## Phase 1: Termux and base packages

Check whether Termux is installed (`adb shell pm list packages | grep termux`). If it is not,
**ask the user to install Termux, Termux:Boot and Termux:API from F-Droid** and to open each
once. You cannot install these yourself, and the Play Store builds are incompatible.

Once present:

```bash
pkg update && pkg upgrade -y
pkg install -y openssh tmux python git curl termux-api android-tools
```

**Gate:** each binary resolves (`command -v sshd tmux python git`).

> If `pkg update` hangs, the mirror is bad. Use `termux-change-repo` to pin a different one.
> Do not let an install run unbounded: see the OOM rule in Phase 4.

## Phase 2: ssh access

1. Start `sshd` (Termux listens on **port 8022**, not 22).
2. Have the user install their public key, or append it to `~/.ssh/authorized_keys`.
3. Verify from the user's computer: `ssh -p 8022 <user>@<ip>`.
4. Recommend a **static DHCP lease** on the router so the address is stable.

**Gate:** a real ssh login from the user's machine succeeds using a key, not a password.

## Phase 3: install this repo and start the services

Clone the repo to the phone (or push it), then:

```bash
cd ~/old-phone-server/scripts
chmod +x *.sh
cp services.conf services.conf.bak 2>/dev/null
sh start-all.sh
tmux ls
```

Edit `services.conf` to list exactly the tmux sessions that should be running, and
`orphans.conf` for any worker that uses `flock`.

**Gate:** `tmux ls` shows `sshd`, `wdog`, `swatch`, `netguard`. Then run `sh start-all.sh`
again and confirm nothing is duplicated. Idempotency is the whole recovery mechanism, so
prove it rather than assuming it.

## Phase 4: autostart on boot

```bash
mkdir -p ~/.termux/boot
```

Create `~/.termux/boot/00-start`:

```sh
#!/data/data/com.termux/files/usr/bin/sh
termux-wake-lock
sh $HOME/old-phone-server/scripts/start-all.sh
```

`chmod +x` it. Then tell the user to do two things you cannot do:

- **Open the Termux:Boot app once, manually.** Until it has been launched a single time,
  Android never delivers it the boot event. This catches almost everyone.
- **Set Termux to Unrestricted** in Settings, Apps, Termux, Battery. Otherwise Android kills
  the services overnight.

**Gate:** ask the user to reboot the phone. After it comes back, `tmux ls` shows the services
again with **no manual intervention**. This is the single most important gate in the whole
setup. Do not accept "it should work".

## Phase 5: charge cap

This protects the battery of a device that will now be on a charger permanently.

Start it:

```bash
su -c 'CAP=70 RES=60 sh ~/old-phone-server/scripts/battguard.sh >/dev/null 2>&1 &'
```

**Gate, and this one matters more than it looks:** popular charge controllers report success
while silently doing nothing. Prove the switch actually stops current:

1. Read the current level: `cat /sys/class/power_supply/battery/capacity`
2. Temporarily set `CAP` **below** that level.
3. Within a minute, `cat /sys/class/power_supply/battery/status` must read `Discharging`.
4. Restore the intended cap.

If status stays `Charging`, this kernel ignores that node. Look for alternatives
(`ls /sys/class/power_supply/battery/ | grep -iE 'suspend|charging_enabled'`) and report
which one worked, so it can be added to the repo.

## Phase 6: Syncthing

Install Syncthing-Fork from F-Droid (ask the user). Then guide, do not guess, the folder
configuration:

- The user's data: **Send Only** on their computer, **Receive Only** on the phone.
- Ask before choosing paths. Confirm there is enough free space for the dataset.
- Turn on **file versioning** on the receiving side.
- Add a `.stignore` excluding `.env`, `*.key`, `*.pem`, `id_rsa*`, `.ssh/`.

**Gate:** compare file counts on both sides, and check one file's `sha256sum` matches. The
green "Up to Date" label alone is not evidence.

## Phase 7: verify the whole box

```bash
bash ~/old-phone-server/scripts/selftest.sh
```

Then hand over a short summary: what is running, where the incident log is
(`~/.incidents.log`), how to reach the device, what the charge cap is set to, and anything you
could not verify.

## If you are diagnosing rather than installing

Read `docs/05_TROUBLESHOOTING.md` first; it is organised by symptom and most problems are
already in it. Then:

```bash
tail -50 ~/.incidents.log          # one ordered timeline of every subsystem
bash ~/old-phone-server/scripts/selftest.sh
tmux ls
```

Two traps worth remembering, because they make broken systems look healthy:

- A **service stuck in a restart loop** is usually an orphaned process holding a `flock`.
  Run `reap_orphans.sh`.
- A **health check that passes while nothing works** happens when the check exercises a
  different layer than the workload. Verify the actual protocol the workload uses.