Tools for bringing up and testing Linux phones, not tied to one device: each takes what any phone gives (a WAV recording, a log) and does the work on the lab machine, so a new device needs no toolchain of its own. Surya (Xiaomi POCO X3 NFC) is the first device they serve; the flows that use them live in its lab (linux-phone-oco/surya-lab).
One program under two names: lpoco lab (the program lpoco-lab) and devlab run the same code; likewise lpoco tone (lpoco-tone) and tone. The family has one version (lpoco list). The old names stay.
The device lab, for any phone: everything it knows about a device comes from the device's
manifest, device.toml, in its lab repository (found like cargo finds Cargo.toml, or --device).
Secrets and what is learned at run time stay outside repositories: ~/.config/devlab/CODENAME/
(the password, mode 600) and ~/.local/state/devlab/CODENAME/ (the Wi-Fi address).
lpoco lab phone find which address answers (the manifest's, then the remembered one)
lpoco lab phone sh < script commands as the user - on standard input, so no quoting layer
lpoco lab phone root < script commands as root
lpoco lab phone put LOCAL REMOTE
lpoco lab phone reboot reboot, and wait until it answers again
lpoco lab flash now IMAGE BOOT the manifest's fixes baked in, the device tree fingerprinted -
by [fastboot] serial, only where the manifest says writes = true
lpoco lab fastboot state | getvar NAME | boot now BOOT.IMG | reboot now [--bootloader]
a phone in fastboot, by its serial: read it, boot from memory
lpoco lab provision now a freshly flashed phone: packages, files, Wi-Fi
lpoco lab test | health | watch its checks; regressions against what worked; after every boot
lpoco lab suite put now puts the health suite on the phone - the lab's checks and manifest as its main has them (devlab's own clone; --here takes this clone's, to try a check before it lands): lpoco-health - the
runner (a small static Rust program) and the generic checks in health/suite/checks/ - from
lab-tools' signed repository (its key and repository added to the phone once), then the phone's own
checks from its lab repository and what the manifest's [health] expects of this phone. With
--built-runner devlab builds the runner (health/build.sh aarch64-unknown-linux-musl) in the lab-tools it
was itself built from and copies it with that tree's checks instead, to try what is not released yet;
--runner FILE copies a runner built elsewhere. A timer runs the suite 120 s after
every boot; lpoco lab suite run runs it now and passes on what the phone says; lpoco lab suite latest
reads its latest report.
Each check is a small shell file in postmarketOS's test shape that prints pass|fail|skip TEST COMPONENT detail, base layer first (the hardware and the system, no shell in the way), then the
shell layer, then the telephony layer: what costs something to run. A call or an SMS runs at most once a
day (once_a_day NAME in lib.sh, skipping with "ran today" after); mobile data (mobile-data) runs every
boot over the modem's own interface, about 150 kB, 5 MB once a week for throughput, each run's bytes kept
in the month's ledger (lpoco-health data) and skipped once the month has spent the manifest's
data_budget_mb (250 by default). Each run is one report on the phone, /var/lib/lpoco-health/RUN.jsonl, a line per test
in the shape of the device base's test_results (docs' when the lab has no base); an unhealthy run keeps its evidence beside it
(kernel log, errors, failed units) and says what is wrong, in plain words, in the journal. A part the
phone never had working is a gap in the manifest: still measured, not ill health; a gap that starts
to pass is said.
lpoco-health awake [--once] hold the kernel wake lock `lpoco-awake` (every 5 s; --once: one step)
The package's unit lpoco-awake.service runs it (the device enables it; the package only carries it). The lock is
held always, so sxmo's autosuspend, which blocks on it, never suspends a phone on USB (a suspend that completes
while the port blips leaves the idle phone silent). Deliberate suspends (suspend cycle) write /sys/power/state
themselves and are not held back. With /etc/lpoco/allow-autosleep (a battery test) the lock is held only while the
UDC is configured or while a gate the manifest names says unsafe: [health] awake_gates = ["bluetooth-not-up"]
(hci0 not UP, or an rfkill stuck in D state). A gate the package does not know is named on stderr; with autosleep allowed it is refused (exit 2, nothing held), otherwise the phone stays awake. The lock was devlab-usb and the allow file /etc/devlab-allow-autosleep before: a phone moving over drops the old file and script by hand.
The suite's check awake-wakelock-held reads the lock and the unit, not an installed script.
lpoco-health suspend plan what a cycle would do, or why it would refuse - changes nothing
lpoco-health suspend cycle [--seconds 15] [--settle 2]
one suspend (s2idle) ended by an RTC wake alarm, counted
The device declares in its manifest's [health] its way back - suspend_guard, a command that succeeds while
the phone's watchdog is armed (surya: the kept-armed watchdog) - and the wake sources to quiet for the cycle,
suspend_quiet (wakeup files, e.g. a UART's power/wakeup, put to disabled and put back after, however the cycle
ends). Without a way back, or with one that is not armed, the cycle is refused (exit 2, nothing suspended). It
reads before and after the SoC's own counters (qcom_stats), the suspend counter, the cpu idle states (cluster states
among them, summed over the cpus) and the wakeup sources, prints one JSON report and keeps it as this boot's cycle
(/var/lib/lpoco-health/suspend/cycle.json); exit 0 when the SoC slept, 1 when it did not. The check soc-sleeps
--seconds is at least 5 (the RTC counts whole seconds); a wake long before the alarm is reported woke_early, not slept; a declared source that cannot be quieted is named in not_quieted; sources left quiet by a cut-off cycle are put back by the next. plan always exits 0: read would_cycle. The check soc-sleeps
reads that cycle - of this boot, no other - and says pass or fail where it used to skip. The cycle is never part of
a scheduled run: somebody (a keeper) asks for it. Every path lies under LPOCO_HEALTH_ROOT (empty on the phone), which
is how the fixture tests run it on a made-up phone.
What the phone finds out by itself is a condition, worked out at the start of every run by
conditions/*.sh (no SIM card, no modem, no network): a check says skip_on no-sim TEST COMPONENT && exit 0
and reports "not measured: no SIM card". Nothing is written down - put the SIM back and the next run measures
again. What somebody chooses is a switch: lpoco-health off TEST --reason WORDS [--by WHO], lpoco-health on TEST, lpoco-health list (tests, switches with who and when, conditions found now), kept in
/etc/lpoco-health/switches on the phone and reported as skip: switched off: REASON (by WHO, WHEN). A test
is never off without a reason. From the lab: lpoco lab suite off|on|list, and the MCP door's
health_switch_off, health_switch_on, health_switches. The phone's state never goes into docs; docs keep
the hardware's facts and the results. The command line is declared once with argenv (health/src/cli.rs).
lpoco lab suite put now moves a phone from the old devlab-health (reports, month's data ledger, once-a-day
marks) to lpoco-health and leaves devlab-health as another name of the program.
The package is released by release-plz (a lpoco-health-vX.Y.Z tag) and published by the package
conveyor (packaging/, .github/workflows/packages.yml) at https://linux-phone-oco.github.io/lab-tools/,
for postmarketOS v26.06 (Alpine 3.24): any postmarketOS phone can take it with the lines on that page.
The same page holds sxmo-utils, our fork's lab build of the phone's shell (packaging/sxmo-utils/): it is
published when a tag sxmo-utils-v<pkgver> (the APKBUILD's pkgver, made by hand once per lab tag of
grenudi/sxmo-utils; release-plz does not make it) is pushed, and each package is kept when the other is rebuilt.
lpoco lab kernel install NAME VMLINUZ DTB MODULES.tgz | try NAME | log | remove NAME - the safe test-kernel boot (one try by boot
counting, a stalled boot saves its log and falls back to stock), proven on surya.
lpoco lab mcp is devlab's door for agents: an MCP server on standard input and output, with the tools
run (commands as the user or root, no quoting layer), put and get (files), health_report and
health_run (the phone's own suite, with its verdict), kernel_install, kernel_try (once, falling
back by itself, then the health of the boot it came to), kernel_status, and reboot (and wait, and
the new boot's health). Each calls what the command line calls.
lpoco mcp is the family's one door: the same server, every program's tools under its name - lab_run, lab_put,
lab_get, lab_kernel_*, lab_reboot (the bare names above still answer), health_*, and bringup_image_info and
bringup_image_check (boot images read and counted against the manifest).
claude mcp add --scope user phone -- devlab --device /path/to/LAB/device.toml mcp
claude mcp add --scope user lpoco -- lpoco mcp
Make a test tone, and find it in a recording - a device's speaker tests its microphone:
lpoco tone make --freq 1000 --level -20 tone.wav # gentle: -20 dBFS by default
lpoco tone find --freq 1000 recording.wav # JSON; exit 0 when found, 1 when not
find measures the frequency by the Goertzel algorithm (Hann window) and compares it with
neighbouring frequencies, off the tone and its harmonics: found means it stands --min-snr dB
(20 by default) above them.
On the phone the same crate answers as lpoco-health tone make|find (no clap: the runner stays small;
--raw makes or reads s16le mono as pacat/parecord --raw do, --from/--to keep the seconds where
the tone sounds): a check that plays a tone and listens hands the numbers to this tested code instead of
awk, and reads its JSON line with json_field from the suite's lib.sh. Analysis that counts, times or
keeps a state joins lpoco-health as a subcommand the same way (decision 2026-11-17-health-checks-shell-and-rust).
Development: nix-shell (nixpkgs pinned, as in lab-agent), cargo test. The command line uses clap
for now; moving it onto argenv, as lab-agent uses, is a contained change.
lpoco lab guard tool is what Claude Code's PreToolUse hook on the lab calls, so that changing the phone
outside devlab is refused when it is tried, not remembered: a Bash command that reaches a phone by ssh,
scp, sftp, rsync or sshpass exits 2, saying why. So does raw fastboot with any verb but devices, getvar and
help (and -w or --set-active with any): it would change whichever phone it reaches. It needs no manifest.
The ways every project shares - no git push to main, no Python, the practices and the inbox at every session start - are the hooks of the ideal-agent plugin (https://github.com/grenudi/ideal-agent), installed on the lab since 2026-11-17; devlab keeps only what is its phone's.
A phone's addresses are the ones devlab has met: every manifest it loads leaves its addresses in
~/.local/state/devlab/CODENAME/addresses, beside the Wi-Fi address it learned. In the lab's
~/.claude/settings.json:
"hooks": {
"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "~/.local/bin/devlab guard tool", "timeout": 10}]}]
}
A phone's manifest names what harms it to touch, each with what it did:
[[hazard]]
path = "/sys/kernel/debug/gpio"
why = "read while LPASS is idle it stalls the bus and the phone hangs until a person holds power"
devlab refuses any command it carries to the phone - lpoco lab phone sh|root, the MCP door - that names
one, saying why; the phone is never reached for it.
lpoco lab kernel keep NAME now makes an installed test kernel the phone's default: its entry sorted
ahead of stock with three tries and boot blessing on, so its first good boot is blessed (the default
from then on), and three bad boots in a row put stock back by themselves - the initramfs timeout still
guards each boot. lpoco lab kernel unkeep NAME now gives the default back to stock; the kernel stays
installed. One kernel is kept at a time.
lpoco lab kernel try NAME --dtb FILE boots installed kernel NAME - its kernel, initramfs and modules -
once with another device tree, as the entry NAME-dt: a device-tree change is one boot, even on the kept
kernel. A try is judged by the entry the bootloader says it booted (LoaderEntrySelected).
A phone that speaks only fastboot until Linux runs on it (google-walleye), or any phone sitting in its bootloader, is reached by its manifest's serial - never "whichever phone is in fastboot", as a lab may hold two:
[fastboot]
serial = "FA81N1A00790" # as fastboot devices lists it
writes = false # the default: devlab flash refuses this phone; say true only by a decision
slot_switch = false # the default: devlab fastboot set-active refuses; true only by a decision
lpoco lab fastboot state says whether it is in fastboot and what its bootloader says of itself (product,
unlocked, slot-count, current-slot, versions); getvar NAME reads one. boot now BOOT.IMG boots an
Android boot image from memory - devlab writes nothing - reading the slots' flags before, then saying where
the phone went (back to fastboot, Android's adb, Linux on its USB network) and what the flags became: the
bootloader keeps A/B flags of its own and may change them on a failed boot (google-walleye, 2026-11-17: a RAM
boot ended on slot b with slot a unbootable). set-active now SLOT changes the active slot (metadata only)
where the manifest says slot_switch = true, by a recorded decision only. reboot now goes to the active slot, --bootloader
back to fastboot. None of them writes a partition or erases. The lease and the hold are the
phone's own (by codename), so one phone's keeper never blocks another's.
One session owns a phone's flow at a time - its keeper, taking up the phone's queue (docs: tad q phone-queue) one change at a time; devlab still holds the phone for every change. lpoco lab keeper take NAME takes the lease (refused while another keeper is live), renew NAME as the keeper works, release NAME as it ends, status says who keeps the phone. A lease left unrenewed for 90 minutes has lapsed: its
keeper ended or was cut off, and the next one may take it.
A build or a test that must outlive the session that starts it (a kernel build, an image, a sleep test) is a user
unit of the lab's own, lpoco-job-NAME.service, made with systemd-run --user. The unit's own process holds an
idle and sleep inhibitor for as long as the job runs, so the lab stays awake for the build and nothing else keeps it
awake. systemd is the runner: its journal is the log, a name is claimed once, no daemon, no queue.
lpoco-lab job start NAME SCRIPT run the executable SCRIPT (a name already claimed is refused)
lpoco-lab job status NAME running since T | finished ok at T | failed (exit N) at T | not found
lpoco-lab job log NAME the output of its current run
lpoco-lab job stop NAME end it if it runs, and free the name
lpoco-lab job list every job and its state
It needs no device manifest. The unit gets the caller's PATH and runs in the directory start was called from; a
script that needs more sources it. The user manager keeps its units after logout (lingering is on at the lab).
lpoco NAME args... finds lpoco-NAME beside itself or on PATH and runs it, returning its exit code
(lpoco health latest). The family is released together under one version (release-plz version_group):
a program whose --version differs from lpoco's is refused, naming both. lpoco list shows the
programs found with versions; lpoco completions SHELL and lpoco man come from the argenv declaration.
Lab-side only: the phone runs lpoco-health directly and gets no dispatcher.
lpoco-bringup (run as lpoco bringup ...) makes the files that bring a phone up, on the host; devlab puts them
on the phone. First piece, boot images with header v0, the header facts read from the [boot] table of the
device's device.toml (postmarketOS deviceinfo's words: kernel_offset, ramdisk_offset, tags_offset,
pagesize, cmdline, partition_size, msm_id, os_version, os_patch_level, ...):
lpoco bringup image pack --kernel K [--dtb DTB] --ramdisk R --out IMG byte for byte as mkbootimg writes it
lpoco bringup image check IMG count it against [boot]: magic, v0, size, offsets, os words, cmdline,
the appended dtb and its qcom,msm-id; exit 1 on a miss
lpoco bringup image info IMG the header's facts as a [boot] table
lpoco bringup image unpack IMG --out DIR
--device FILE (or LPOCO_DEVICE) names the manifest; device.toml in the current folder otherwise. The packer
is proven against mkbootimg by test (bringup/tests/pack_v0.rs; where android-tools is absent the test says
"not measured: no mkbootimg"). Swap, initramfs and the rest are their own items.
From the release tags, with cargo; the family has one version, so the tags of one release agree:
cargo install --locked --git https://github.com/linux-phone-oco/lab-tools --tag lpoco-v0.2.0 lpoco
cargo install --locked --git https://github.com/linux-phone-oco/lab-tools --tag lpoco-bringup-v0.2.0 lpoco-bringup
lpoco --version is the tag's version and lpoco list shows bringup. Proof: lpoco/tests/install_from_tag.rs
installs the newest release into a clean root and checks both, and that bringup refuses a wrong pin.
lpoco-host (run as lpoco host ...) prepares the machine the lab runs on from two declarations: the lab's own
lab.toml (--lab FILE / LPOCO_LAB; default ~/Projects/lab-machine/lab.toml: devices a glob or a list of globs, default
~/Projects/linux-phone-oco/*/device.toml; root a prefix; [tools] each host tool at its pin) and each device's
device.toml [host] (modules, and a [[host.gadget]] per serial with access = ["block", "tty"]).
A top-level gadget_group = "users" in lab.toml (a group the lab user already holds, so no re-login) adds GROUP and MODE="0660" to
every gadget rule line beside TAG+="uaccess": access then does not wait on the seat's ACL, nor need the active seat session.
check says which group and whether the lab user is in it.
A gadget's net_name = "lpoco-NAME" gives its USB network a stable interface name (a udev rule by serial, at the next plug-in);
net_address = "10.55.0.1/24" (IPv4 CIDR, needs net_name) adds the host's address on it as a link config for the manager the host
runs: a NetworkManager keyfile (/etc/NetworkManager/system-connections/NAME.nmconnection, mode 0600, nmcli connection reload)
when /run/NetworkManager exists, else a systemd-networkd file (/etc/systemd/network/70-NAME.network, networkctl reload) when
/run/systemd/netif exists; with neither, plan says so and writes nothing. Planned in the diff, written only by prepare now.
The NetworkManager directory is root-only, so the lab user cannot read an existing keyfile: it is planned as new and rewritten at each prepare now (same content, one nmcli connection reload).
A device that wants its health watched says watch = true in its [host] (devlab-watch@NAME-lab user unit, enabled and restarted by prepare);
without it no watcher is enabled for it, and an instance already enabled for a device that does not ask is named in the plan and left running.
lpoco host [plan] a diff per file and the exact root commands; changes nothing
lpoco host prepare now write /etc/udev/rules.d/70-lpoco-CODENAME.rules and /etc/modules-load.d/lpoco.conf,
reload and trigger udev, modprobe, install the tools - only where they differ
lpoco host check the lab user opens each declared node that is present; each tool is at its pin; the phone share is started and stopped
by the lab user with no password (the polkit rule's own test), its interfaces found from the device's address
lpoco host revoke now removes /etc/sudoers.d/lab-agent, the standing grant: refuses unless check passes, the share was measured and the
root prefix does not name lab-agent; `prepare now` ends with the same share check
Root is one prefix, LPOCO_ROOT, then the lab declaration's root, then sudo (the author's typed password: no standing grant, decision of 2026-11-18); the commands are a fixed
list the plan prints. lab.toml tools: lpoco = "0.2.0" installs the family from its release tags with cargo into
~/.local; [tools.NAME] with git, path, rev, version installs a script of another repository at a commit (version is a label only; the pin is rev)
into ~/.local/bin and stamps the rev in ~/.local/share/lpoco-host/rev-NAME: a script is judged by that stamp (never by --version; on PATH without a stamp it is "rev not known"). A device whose [tools] lpoco the lab's pin does not meet is named and nothing is prepared for it.
lpoco = "X.Y.Z" must be a full version (it names the release tags); a tool with no source yet is oco-work = "unknown"
and is listed as "not known yet". Codenames, serials, module and tool names that reach a root command or a file name are
refused unless letters, digits, ., _, -. /etc/udev/rules.d/51-android.rules is named as a wide rule and kept:
prepare never edits or removes it. An old devlab/tone first on PATH that is off the pin is named by plan and check.