starbrightlab/immortal/immortal-fleet

Immortal Fleet management (fleetctl)

fleetctl is a fast, zero-dependency CLI (single-file Rust, std-lib only) that drives the in-app Fleet Agent HTTP API of Immortal-flashed Meta Portals over WiFi. It is the persistent management channel that survives reboots — unlike adb-over-WiFi, which can't on these non-root Android 9/10 devices. Use it to manage a wall of Portals without a USB cable per device.

• Source: provisioning/fleet.rs (std-lib only, no crates)
• Binary: provisioning/fleetctl
• Agent docs: docs/features/fleet.md, provisioning/README.md (Fleet sections)

Build / locate the binary

A prebuilt provisioning/fleetctl usually exists. If missing or stale, rebuild from provisioning/:

rustc -O fleet.rs -o fleetctl     # no Cargo needed
# or: cargo build --release       # -> target/release/fleetctl

Run it from provisioning/ (so it finds the fleet/ registry by default):

cd provisioning && ./fleetctl <command> [--device NAME|serial|all] [options]

Device targeting (read this first)

Targets come from the device registry: fleet/<serial>.json files that ./provision.sh --fleet records for each provisioned Portal — {serial, name, model, ip, agentPort, token}.

• --device NAME — match by friendly name (case-insensitive) or serial.
• --device all — fan out to every registered device (output is sectioned per device).
• (omit `--device`) — a single registered device is used automatically; with multiple

devices the CLI errors and lists known names.

• Not in the registry? Skip it entirely with --host <ip> --token <token> [--port 8723].
• Point at a different registry folder with $IMMORTAL_FLEET_DIR.

Auth & secrets: every request carries Authorization: Bearer <token>; a wrong/absent token gets 401. The per-device token lives in fleet/<serial>.json, which is git-ignored and a secret (the repo is public). Never print token values or commit that folder.

Exit codes: 0 success · 1 HTTP/transport error (non-2xx or device down) · 2 usage error. Default agent port is 8723.

Commands

Read-only / inventory:

./fleetctl devices                       # list devices in the local registry
./fleetctl info   --device all           # identity, version, install/presence state
./fleetctl apps   --device "Living Room" # catalog apps + what's installed
./fleetctl diag   --device all           # diagnostics snapshot

App install / update:

./fleetctl install org.videolan.vlc --device all          # install a catalog package
./fleetctl install com.example.app --apk-url https://…/app.apk   # or a direct APK URL
./fleetctl update --check                # dry-run: which apps have updates
./fleetctl update --all  --device all    # update everything
./fleetctl update org.videolan.vlc       # update one package

Config (Immortal's free-form agent config):

./fleetctl config                        # read current config
./fleetctl config --name "Living Room Left"
./fleetctl config --set key=value --set other=value   # repeatable

Screensaver photo frame (GET reads; set pushes a partial update — only fields you pass change). Display changes apply on the next screensaver cycle; --enabled and the overnight window apply immediately:

./fleetctl screensaver get --device "Living Room"
./fleetctl screensaver set --enabled true --fit fill --interval 45 --shuffle true --device all
./fleetctl screensaver set --album-url 'https://www.icloud.com/sharedalbum/#…' --device all
./fleetctl screensaver set --overnight true --overnight-start 22:00 --overnight-end 07:00 --device all

screensaver set options: --enabled BOOL --source default --folder PATH --album-url URL --album-refresh MIN --fit fill|fit --interval SEC --shuffle BOOL --videos BOOL --now-playing BOOL --battery-saver BOOL --presence always_on|presence --idle-min N --overnight BOOL --overnight-start HH:MM --overnight-end HH:MM.

Calendar widget (its own endpoint; applies live on next refresh):

./fleetctl calendar get --device "Living Room"
./fleetctl calendar set --url 'https://…/basic.ics' --range week --device all
./fleetctl calendar set --range agenda            # re-range without resending the link
./fleetctl calendar enable|disable --device …     # toggle the widget, keep the link
./fleetctl calendar off --device "Living Room"    # clear the link entirely

--url = Google "secret address in iCal format" or Apple iCloud public / webcal:// link. --range day|3day|week|agenda · --size small|medium|large · --side left|right.

Files / logs:

./fleetctl ls   /sdcard/Android/data/com.immortal.launcher/files
./fleetctl cat  /sdcard/some.txt
./fleetctl push ./frame.jpg /sdcard/Android/data/com.immortal.launcher/files/frame.jpg
./fleetctl pull /sdcard/some.log ./some.log        # local "-" or omit = stdout
./fleetctl logcat --lines 200 --device Kitchen

pull to a local file path targets one device; with --device all write to stdout (-).

Device actions:

./fleetctl action reaffirm --device all   # re-assert launcher/screensaver ownership
./fleetctl action identify --device …     # flash a banner to find the physical device
./fleetctl action reboot   --device …

Escape hatch — call any agent endpoint directly (keeps working as the API grows):

./fleetctl raw GET  /info
./fleetctl raw POST /calendar '{"range":"agenda"}'   # body must be valid JSON

Dev mode — iterate on Immortal itself over WiFi

When hacking on Immortal, avoid cutting a GitHub release per change and stop the official self-updater (UpdateManager) from clobbering your test build:

./fleetctl dev status --device "Living Room"   # dev mode + installed version
./fleetctl dev on     --device "Living Room"   # pause the official self-updater
./fleetctl dev update ./app/build/outputs/apk/release/app-release.apk --device "Living Room"
./fleetctl dev off    --device "Living Room"   # resume official updates

dev update enables dev mode first (unless --no-pause), pushes the local APK, and installs it over Immortal via the same silent path the store uses. --package PKG / --path REMOTE override the defaults (com.immortal.launcher and a temp path in the app's files dir).

CRITICAL — sign with the same key. An in-place update is signature-checked by Android. The local build must be signed with the same key as the installed Immortal, or the install is rejected. Switching a Portal onto a differently-keyed build requires an uninstall (which wipes app data) — snapshot first with provisioning/fleet-backup.sh and restore with fleet-restore.sh.

Scope — what the CLI can and can't touch

The agent runs as the app user, so fleetctl reaches everything the agent exposes: install/update apps, read/write shared and app-external storage (push/pull/ls/cat), Immortal's config and screensaver/calendar, logcat, diagnostics. It is not a full adb shell — it cannot read other apps' private data dirs or run pm / appops / settings directly. Those need the shell user (USB adb or the provisioning kit). The token can only install known catalog apps unless dev mode is on (403 dev_mode_required otherwise).

Quick recipes

• Inventory the whole fleet: ./fleetctl info --device all then ./fleetctl apps --device all.
• Roll an app to every Portal: ./fleetctl install <pkg> --device all.
• See pending updates, then apply: ./fleetctl update --check → ./fleetctl update --all --device all.
• Point a wall of frames at one calendar: ./fleetctl calendar set --url '<ics>' --range week --device all.
• Test a local build on one device: ./fleetctl dev update <app.apk> --device "<name>" (same signing key!).
• A device looks down: check it's on WiFi and registered (./fleetctl devices); transport errors exit 1.