CLI tool
termux/termux-api avatar
termux/termux-api

Termux:API and the signature rule that decides whether your script runs

Termux add-on app which exposes device functionality as API to command line programs.

4,650 stars1,007 forksJavaLicense varies

At a glance

What is it?
Termux:API is a Java add-on that turns Android device functions into calls a shell script can make, and its permission model depends on a signature key match that most users never think about.
Who is it for?
Adopt Termux:API when you are already inside Termux and need a hardware or Android API call inside a script, since the socket and broadcast path is the only documented route. Do not adopt it as a remote service, a background agent or anything a web or desktop process can reach, because the receiving app only answers the main Termux app.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 60 days ago.
What is it written in?
Mainly Java, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • termux/termux-api4,650 ★ · +291
Star history
Repository2026-09-232026-11-15
termux/termux-api4.4k4.7k

291 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One broadcast, two anonymous namespace sockets

The whole transport fits in a single command. A helper binary creates two Linux anonymous namespace sockets, then hands their addresses to a Java broadcast receiver running inside the add-on app:

bash
/system/bin/am broadcast ${BROADCAST_RECEIVER} --es socket_input ${INPUT_SOCKET} --es socket_output ${OUTPUT_SOCKET}

Note what is missing. There is no port number, no daemon to start, and no HTTP endpoint. Input goes from stdin into the input socket, the API class reads it, and the result travels back through the output socket to the stdout of the helper. Every request is an `am broadcast` invocation carrying the two socket addresses as extras, while stdin travels through the sockets.

That design has a direct consequence for anyone planning an architecture around it. The API surface is reachable only from a process that can already launch Android activity manager commands inside the Termux environment. There is no listening service on the network, so there is nothing to proxy, expose on a LAN address or bind to a socket for a remote caller. The permission check is the security model, not a defence bolted onto it later.

The same signature key gates every call

Read the note near the top of the README and the project's real design constraint appears. The add-on app must be signed with the same key as the main Termux app, and only the main Termux app is permitted to call the API methods.

For anyone building or repackaging the app, the consequence is blunt: a locally built APK signed with a personal key produces an app that installs cleanly and then fails every call. Nothing in the documented transport shows where that rejection surfaces. The README describes the signature requirement in the development note and says nothing about a diagnostic message for a mismatch, so debugging it means reasoning about build configuration rather than reading logs.

For ordinary users this reads as a version compatibility question. It is one. But it is a compatibility question about keys, and the only documented remedy sits in another repository.

Getting the app, and the reinstall each source change costs

There is no install command to copy here. The README points you at F-Droid for the current release, and the package page is the project's own stated distribution channel. For anything newer, the project publishes per-commit debug builds through its GitHub Actions workflow, and the README says to pick one from the workflow runs for the master branch on push.

The cost of that option is stated plainly, and it is the part worth reading twice. Signature keys of all offered builds differ. Before switching installation source you must uninstall the Termux application and every currently installed plugin, which removes the environment, its installed packages and any scripts you had in it. A developer trying a debug build to test a pull request pays that price on both the main app and its plugins.

The README also points installation troubleshooting at the termux-app repository rather than duplicating it, so anyone hitting this wall is sent across projects mid-recovery.

The client scripts live in another repository

Argument parsing does not happen in this repository. The `termux-api` package holds the helper binary and the client scripts that turn command line flags into an API invocation, and both the binary and the scripts are documented as living in termux-api-package. This repository contains the Java app that receives the broadcast.

The split matters for reading the code and for troubleshooting. A user typing a command and seeing a usage error is looking at a package that is not here. A user who wants to know which permissions a particular API method requires is reading Java in app/src/main/java. Anyone auditing the transport has to follow the socket addresses across two codebases, because the receiver expects exactly the extras the helper sends.

Where to put things also follows from that split. The settings files and the app Gradle project are here, at the repository root alongside build.gradle and settings.gradle. Any packaged build problem is a Java build problem here.

The Ideas list is a wish list, not a capability list

The repository ends with two bullets. One asks for wifi network search and connect. The other asks for extra permissions to install and uninstall apps and to stop processes. Both sit under a heading called Ideas.

That heading does real work in the article sense. Nothing in the transport section or the installation section says that wifi scanning, app installation or process killing is available today. A reader who skims past the word and treats the bullets as a feature list will build a script that fails, and the failure will look like a permission problem rather than an unimplemented feature. The README nowhere lists the set of methods the receiver actually dispatches to, which means the honest answer to the question of what this app can do has to come from the app source rather than from its documentation.

Those two requests also explain the direction of travel. Both ask for capabilities that Android deliberately restricts, which is consistent with an add-on that currently exposes only what a same-key-signed caller is permitted to reach.

The receiver name is a shell variable, not a documented constant

Look closely at the broadcast line and 3 of its 4 values are variables: `BROADCAST_RECEIVER`, `INPUT_SOCKET` and `OUTPUT_SOCKET`. Only the two socket extras are created on the spot by the helper binary. The receiver component name has to come from somewhere else, and the README never states it as a literal value.

So a script that bypasses the client scripts has to reconstruct that intent target itself, along with the two socket paths, before any API method is reachable. Anyone maintaining shell wrappers around this transport ends up carrying a receiver name the project documents only indirectly, and a rename on the Android side would break those wrappers without changing any version number they could see.

The client scripts in the termux-api package absorb that detail, which is the argument for installing that package rather than calling the helper by hand. It is also why the helper source lives in termux-api-package rather than here: this repository holds the Java receiver that ends the request, not the shell side that begins it.

No port, no daemon, no retry path in the broadcast design

It is worth naming what this project is not, because the name invites the wrong mental model. Each call is an activity manager broadcast performed from a process that already lives inside the Termux sandbox with the main app's identity.

That is why the audience is narrow and correct: people writing scripts on an Android device who need something Android can do that busybox cannot, and who accept that the script runs on the handset. Anyone building a server-side component, a home automation hub, or a CI job that needs an Android API will find no interface to build on.

The limitations follow the same line. No retry behaviour is documented if a broadcast is dropped. No timeout or cancellation path is described for a slow API class. No version negotiation between the helper binary and the installed app is documented.

Editorial conclusion

Adopt Termux:API when you are already inside Termux and need a hardware or Android API call inside a script, since the socket and broadcast path is the only documented route. Do not adopt it as a remote service, a background agent or anything a web or desktop process can reach, because the receiving app only answers the main Termux app. Verify first that your Termux and Termux:API builds carry the same signature key, because the README says the add-on must be signed with the same key as the main Termux app for permissions to work.

Frequently asked questions

What does Termux:API do?

It is an add-on app that exposes Android device functionality to command line programs and scripts. Calls travel through a helper binary that creates two anonymous namespace sockets and passes their addresses to a broadcast receiver in the app.

How do I install Termux:API?

The README points to the F-Droid package page for the current release. There is no install command in the documentation, and per-commit debug builds are offered through GitHub Actions instead.

how to use termux api

Client scripts in the termux-api package process command line arguments and call the termux-api helper binary, which then performs the broadcast described above. The app repository itself contains the Java side that receives it.

termux api not working

The README names one concrete cause of failure: the app must be signed with the same key as the main Termux app, because only the main Termux app is allowed to call the API methods. It does not document a log message for a key mismatch.

termux api is not installed

Builds come from the F-Droid package page or from GitHub Actions workflow runs, and signature keys of all offered builds differ. Switching installation source requires uninstalling the Termux application and all currently installed plugins first.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. termux/termux-api on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/termux-termux-api.svg)](https://hysenlabs.com/projects/termux-termux-api)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/termux-termux-api.svg)](https://hysenlabs.com/projects/termux-termux-api)

Was this useful?