Termux Background

Version 1.1.0 (VERSION): test/debug builds only, not released and not device-qualified. CI is set up to build test APK and DEB artifacts (Actions → latest successful build → artifact), but as of 2026-10-27 no Outer-Void Actions job starts (account billing lock), so build locally (below). No device has passed the device checklist yet. This is a standalone utility; it does not use BLUX.

Termux Background provides an Android controller and a Termux CLI. The companion uses Termux's supported RUN_COMMAND interface to invoke the CLI; all configuration writes stay inside Termux. Apply/Reset wait for command results.

The companion targets Termux Monet's documented wallpaper interface: ~/.termux/background/background.jpeg and background-overlay-color. Enable Background Image under Monet Settings → Termux → Termux Style; after Reset, Monet may disable that switch, so enable it again for the next Apply. Opacity uses a black overlay. Blur and scroll animation are unsupported by this backend and disabled in the companion. Upstream Termux has no wallpaper interface.

Device qualification remains outstanding: the Monet adapter is based on its implementation and documented wallpaper support, but no exact device/distribution/version has passed the device checklist. CLI completion confirms files and reload, not rendering.

Requirements

• Android 7.0 (API 24) or later; builds target SDK 35.
• Initialized Termux Monet retaining Termux >=0.109 the com.termux RUN_COMMAND API.
• The CLI DEB from this release and termux-tools, file, coreutils in Termux.
• Companion Run commands in Termux permission and user-enabled allow-external-apps=true in ~/.termux/termux.properties, followed by termux-reload-settings. This permits authorized apps to execute with Termux's privileges; grant only to trusted apps. Termux:API is not required.

Install

There is no current release of 1.1.0. Install a CI test build, or build the APK yourself (below).

The GitHub Releases page still lists four historical builds from 2025-07-31 (v1.0.0, v1.0.1, v1.0.3, version-1.0.0). They predate the 2026 rebuild, are unsupported, and have open reports that the app closes when tapped. They are signed with certificate SHA-256 7bd3603d…ab4a, which is not the compromised key described under Build from source (checked 2026-11-04).

adb install termux-background-1.1.0-debug.apk     # CI artifact name; a local build is app/build/outputs/apk/debug/app-debug.apk

Install the Debian package from inside Termux:

pkg install termux-tools file coreutils
dpkg -i ./termux-background_1.1.0_all.deb

Open the companion, tap Authorize, grant the permission, then Re-check. Diagnostics checks CLI protocol, image transport, configuration and reload. Installations are manual; the app never downloads or silently installs code. Select a PNG/JPEG (up to 20 MiB / 40 megapixels); Apply transfers a resized JPEG up to 120 KiB.

CLI usage

termux-background --backend monet set --image ~/Pictures/terminal.png --opacity 0.8
termux-background --backend monet status
termux-background --backend monet reset

# Existing legacy CLI remains available for forks implementing its keys:
termux-background set --image ~/Pictures/terminal.png --opacity 0.8 --blur false --animation scroll
termux-background status
termux-background reload
termux-background reset
termux-background help
termux-background version

Without --backend monet, the legacy set accepts PNG or JPEG images, opacity from 0 through 1, true/false blur, and none/scroll animation. It installs the selected image at ~/.termux/background.png, updates only the background keys in termux.properties, and reloads settings. reset removes those managed keys and image while retaining unrelated properties. A reload failure is reported even though the files may already have been written.

Exit codes: 0 success, 1 general failure, 2 invalid arguments, 3 missing dependency, 4 file access failure, 5 configuration failure, 6 reload failure after write, 7 temporary cleanup failure, and 8 a missing engine dependency. The companion also uses probe (protocol 1) and set --image-stdin with bounded base64 input.

Build from source

Requires JDK 17 and Android SDK platform/build tools 35:

git clone [email protected]:Outer-Void/termux-background.git
cd termux-background
./gradlew clean assembleDebug
./gradlew assembleRelease
./build-deb.sh
./tests/cli_test.sh

Release APKs are unsigned unless signing credentials are supplied externally. Set ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, and ANDROID_KEY_PASSWORD in the environment. Never commit keystores or credentials. GitHub Actions accepts the same values through repository secrets (ANDROID_KEYSTORE_BASE64 for the keystore file). The previously committed signing key is removed and must be considered compromised; apps signed with a replacement key cannot update installations signed by that old key, so those installations must be uninstalled before installing a newly signed build.

Uninstall

Removing the package does not touch your Termux settings, so restore them first:

termux-background --backend monet reset      # or `termux-background reset` for the legacy backend
dpkg -r termux-background

Then uninstall the companion app from Android settings. If you enabled allow-external-apps=true only for this app, set it back to false in ~/.termux/termux.properties and run termux-reload-settings.

Troubleshooting

• Termux missing: install Termux before using its configuration tools.
• Reload command missing: install/update Termux tools so termux-reload-settings is available.
• Image type check unavailable: install the Termux file package (also declared as a Debian dependency).
• CLI says image unreadable: use a path readable by the Termux shell, such as a file in $HOME; Android picker URIs are not shell paths.
• Reload failed: the config was written but may not yet be active; run termux-background reload after resolving the Termux command issue.
• Execution rejected: grant the companion command permission and enable allow-external-apps=true in Termux.
• Timeout/interrupted operation: completion is unknown. Force-stop and reopen Termux, then confirm Recover in the companion and run diagnostics.
• CLI completed but no background: enable Background Image in Termux Monet settings; upstream Termux cannot render it; see the compatibility limitation above.

The companion's Diagnostics option provides app, OS, and dependency information for bug reports. It does not include file contents or credentials.

See bridge design and security and the device checklist. On an ARM host, a native AAPT2 may be required: ./gradlew -Pandroid.aapt2FromMavenOverride=/path/to/native/aapt2 lint test assembleDebug assembleRelease.

Debug builds are debuggable test APKs with application ID com.termuxbackground.test, version suffix -test, and label “Termux Background Test”. They can coexist with the production app and require their own Termux command permission grant.

License

Outer-Void Proprietary License (proprietary). Copyright (c) 2026 Outer-Void / Justadudeinspace (JADIS). All rights reserved. See LICENSE.

Copies and releases obtained before 2026-10-25 remain available under the MIT License they were published with; every change and release from that date on is proprietary.

Third-party components keep their own licenses; see THIRD_PARTY_NOTICES and licenses/.

Contact: [email protected] (main) · [email protected] (fallback)