Documentation

For app developers

Open Linux apps and run commands in Breadstick Linux from your own Android app, with the user's permission.

Your Android app can ask Breadstick Linux to open an app installed in Linux, or to run a command there. Both need a permission the user grants, the same way they grant camera or location access, and the user can take it back at any time.

The two permissions

Permission	Lets your app
`io.breadstick.permission.OPEN_APPS`	open apps already installed in the user's Linux system
`io.breadstick.permission.RUN_COMMAND`	run any command in Linux, as the user's Linux account

Ask for the smaller one if it is enough. RUN_COMMAND reaches everything the Linux user can: their Linux files, and their Android storage when Breadstick has been given access to it.

Declare the permission in your manifest, and request it at runtime before the first use:

<uses-permission android:name="io.breadstick.permission.OPEN_APPS" />
<queries>
    <package android:name="io.breadstick" />
</queries>

requestPermissions(arrayOf("io.breadstick.permission.OPEN_APPS"), REQUEST_CODE)

If Breadstick is installed after your app, request the permission again: Android only knows about it once Breadstick is on the device.

Open a Linux app

Name the app by its desktop entry, the file name Linux uses for it in /usr/share/applications.

startActivity(
    Intent("io.breadstick.action.OPEN_APP")
        .setClassName("io.breadstick", "io.breadstick.api.OpenApp")
        .putExtra("io.breadstick.extra.APP", "org.gnome.Calculator.desktop"),
)

Breadstick starts its Linux session if it is not running, in the mode the user last used, and opens the app. An app that is not installed is reported to the user and nothing else happens.

Run a command

Pass the command as separate arguments, and Breadstick keeps each one intact: no quoting, and no shell unless you start one yourself.

startActivity(
    Intent("io.breadstick.action.RUN_COMMAND")
        .setClassName("io.breadstick", "io.breadstick.api.RunCommand")
        .putExtra("io.breadstick.extra.ARGV", arrayOf("xdg-open", "/home/me/notes.md")),
)

The command runs as the user's Linux account, inside the running desktop session, so a program with a window opens as a window. Nothing is returned to your app yet: no output and no exit status.

What the user sees and controls

Android asks the user before your app gets either permission, and the permission can be revoked from your app's page in Android's settings.
In Breadstick, Settings > Other apps lists every app that has made a request, with a link to that page, and has a switch that turns away every request from every app.
A request that arrives any other way can only open an app that is already installed. Any other command is shown to the user, who decides whether it runs.