The adb steps from Breadstick's guides, done from your browser over a USB cable. Nothing to install on the computer, nothing uploaded, no account.
Some things Breadstick cannot change from inside Android: the background process limit that closes the Linux desktop, the freeform-windows switch some phones need for Floating mode, and the two permissions the virtual machine engine needs. Android only lets a computer change them, through a developer tool called adb. Breadstick Tools is that computer side, as a web page: Chrome talks to the device over the cable, you click a button, the page runs the exact command shown on the card and reads the result back.
Everything happens in your browser. The page connects to your device directly over USB (a browser feature called WebUSB). Nothing about your device is sent to breadstick.io or anyone else, there is no account and no sign-in. The page stores two things in this browser only: the checkbox below, and the key your device uses to recognize this computer. This page carries the same Google Analytics as the rest of breadstick.io, which never sees anything from your device: privacy policy.
Before you start
Checking your browser... This page needs WebUSB: Chrome, Edge or Opera on a computer. Firefox and Safari cannot do it. Chrome on Android with a USB OTG cable may work; it is not tested.
Please read this first
You use these tools at your own risk. They change Android system settings and app permissions on your device, the same ones the manual adb commands in our documentation change. Each change here is reversible with its own Turn on / Turn off, Grant / Revoke button, and the exact command is shown before it runs. Breadstick Linux and its author are not responsible for problems caused by changing these settings. Nothing here deletes your Linux system, your files or Breadstick's data, and nothing here can.
Two of the settings reach beyond Breadstick: the process limit applies to every app on the device, and the freeform-windows switch changes how Android opens windows for every app. Each card says so.
Step 1: Developer options and USB debugging
adb works only when the device allows it. Both switches live in Android's Settings and stay on until you turn them off.
Samsung (Galaxy phones and tablets)
Settings, About phone or About tablet, Software information, then tap Build number seven times and enter your PIN. Go back to the Settings list: Developer options is now at the bottom. Open it and turn on USB debugging.
Google Pixel and most other Android phones
Settings, About phone, tap Build number seven times, enter your PIN. Then Settings, System, Developer options, USB debugging.
Googlebooks (computers running Android)
Settings, About, tap Build number seven times, then Developer options, USB debugging. Two things to know: a Googlebook runs your apps as a second Android user (user 10), and this page finds the right one for every command. And the Googlebooks we have tested have no USB device mode: they are reached over Wireless debugging, which a browser page cannot do. For a Googlebook, run the commands each card shows with adb on another computer, adding --user 10 where the card says <user>.
Other brands
The path differs a little, but it is always About phone, Build number seven times, then Developer options and USB debugging. A search for your brand's name and "developer options" finds the exact steps.
Then connect the cable. Use a cable that carries data (some charging cables do not), plug the device into the computer and unlock its screen. The first time this computer talks to the device, the device asks Allow USB debugging? and shows the computer's RSA key fingerprint, 16 pairs of letters and digits. That key is made by this browser the first time and kept in it; the fingerprint appears on this page when you connect, so you can check it is the same one. Tap Allow, or Always allow from this computer to skip the question next time. When you are done, turning USB debugging off again is a reasonable habit.
Step 2: Connect
The button is enabled once you have accepted the note above and the browser can do WebUSB. A picker opens listing the USB devices the browser can see; choose yours.
Not connected.
If connecting does not work
"The device is already in use" or the picker shows nothing after you choose. Another program on this computer holds the device, nearly always an adb server left running by Android Studio, scrcpy or a terminal. Run adb kill-server in a terminal, or close Android Studio, then try again. Only one program can hold the adb connection at a time, so this page and a terminal's adb take turns.
Nothing happens and the status says to look at the device. The device is waiting for you: unlock it and answer Allow USB debugging?. If you tapped Deny, connect again.
The device is not in the picker. USB debugging is off, the cable does not carry data, or the device is locked. On Linux, your user may also need permission to open the USB device (a udev rule for Android devices).
It disconnected halfway. Usually the cable. The page tells you; plug it back in and connect again. A setting that was being changed is either changed or not, never half: read its card again.
The tools
Each card shows the current state, what the setting does, the exact command it runs, and how to undo it. Nothing runs until you click that card's button, and after every change the card reads the state back from the device.
Device check
Which device this is, which Android it runs, whether Breadstick is installed and for which Android user, and where every setting below stands. Read-only.
Connect a device to read this.
The report is plain text for a support email to hello@breadstick.io: device model, Android version, Breadstick version and the settings. No serial number, no logs, nothing that could hold a password.
What it is. Android limits how many processes one app may have running in the background, 32 on most devices. A Linux desktop is made of processes, and to Android all of them belong to Breadstick. When the total passes the limit, Android kills processes until it is under again, and when the one it picks is the one hosting Linux, the whole desktop closes at once. A browser is usually what tips it over. The full story.
What changes. Turning the limit off tells Android to stop counting, for every app on the device, not only Breadstick. The limit exists to stop apps from quietly running work in the background and draining the battery; without it, a misbehaving app can. That is a fine trade on a device you use for development and a poor one on a phone you depend on. This is your choice to make, which is why Breadstick does not make it for you, and why it cannot: no app can change this setting about itself.
Steam on Breadstick needs the limit off: a desktop and Steam together run more processes than it allows, and the Steam card in Recommended apps refuses to install until it is.
Connect a device to read this.
Afterwards. The change applies to new sessions: restart the Linux session (Stop, then Start in Breadstick). Breadstick reads this switch and, with the limit off, shows no process warnings and no count. An Android update may turn the limit back on; come back here if the desktop starts closing again.
To undo, click Turn the limit back on, or run the second command below.
The exact commands
Read the state (the setting, the Developer options switch's property, and the limit value if it was ever changed):
adb shell settings get global settings_enable_monitor_phantom_procs
adb shell getprop persist.sys.fflag.override.settings_enable_monitor_phantom_procs
adb shell device_config get activity_manager max_phantom_processes
Turn off:
adb shell settings put global settings_enable_monitor_phantom_procs false
Turn on:
adb shell settings put global settings_enable_monitor_phantom_procs true
What ran on the device
Floating windows on phones
What it is. Floating mode gives each Linux app its own window. On Samsung DeX and on a Googlebook's desktop windowing that is built in. On most other phones and tablets, Android keeps freeform windows switched off, and Floating mode can only open apps full screen until the switch is on. It is the same switch as Enable freeform windows in Developer options; some builds hide it, and this card sets it directly. More in the docs.
What changes. Android allows apps to open resizable windows that float over the home screen. This affects every app that asks for one, not only Breadstick; most apps never do. If the device already has freeform windows built in, the card says so and the switch changes nothing.
Connect a device to read this.
Afterwards. Close Breadstick fully and open it again. Breadstick reads the switch directly, but Android itself may need a restart before it opens its first freeform window.
To undo, click Turn off, or run the last command below.
The exact commands
Read:
adb shell settings get global enable_freeform_support
adb shell settings get global force_resizable_activities
Turn on:
adb shell settings put global enable_freeform_support 1
Turn off:
adb shell settings put global enable_freeform_support 0
What ran on the device
Virtual machine permissions
What it is. Besides its Standard engine, which runs Linux as ordinary processes, Breadstick can run your Linux system in a real virtual machine on devices whose Android has a virtualization framework for apps (Pro, Breadstick 3.0). Android guards that framework with two permissions no app can ask for in a dialog: MANAGE_VIRTUAL_MACHINE and USE_CUSTOM_VIRTUAL_MACHINE. Only a computer can grant them. Until both are granted, the VM engine in Breadstick stays dormant and never runs.
What changes. Breadstick, and only Breadstick, is allowed to create and run virtual machines through Android's own virtualization service. Nothing else on the device changes. The grant survives app and Android updates; Revoke takes it away again. Android restarts Breadstick when a permission changes.
Checked first. This card asks the device whether it can run virtual machines at all: Android 14 or later, the virtualization framework feature, a hypervisor that runs non-protected VMs (a device that runs only protected VMs cannot boot a Linux of your own), and the service itself. If it cannot, the card says so and offers no Grant button: the Standard engine is the one to use. It also checks the installed Breadstick version, since VM mode needs 3.0.
Connect a device to read this.
Afterwards. Open Breadstick again; with Pro, Settings offers the Engine choice. Your Linux system is not changed by the grant itself.
To undo, click Revoke, or run the two revoke commands below.
These talk to the installed Breadstick app (2.1 and later) through the same door its own tests use. The Linux-side parts need Breadstick to be open with a Linux session running. On a device that runs Breadstick as a second Android user, such as a Googlebook, Android's own information is still collected, but the Linux side shows as not available: adb cannot read that user's files.
Collect logs
What it does. Gathers what a support email needs into one text file: the device report above, Android's own log lines about Breadstick (including the lines Android writes when it closes processes over the limit), Android's record of why Breadstick last exited, Breadstick's package information (version and permissions, never its signing keys), the build fingerprint, the last lines of Breadstick's session log, and from inside Linux the installed Breadstick packages, the feature and GPU files, and the end of Steam's log if there is one.
What is in it. File names and app names can appear, because that is what logs contain. Passwords and keys do not: nothing here reads them, and lines that look like one are dropped anyway. The whole file appears on this page first so you can read it before you save it. Saving is a download to your computer; nothing leaves the browser otherwise.
Four things that are otherwise done from inside Breadstick or by hand. Each asks you to confirm and shows its command first. None of them deletes anything: no Linux system, no files, no app data.
Stop the Linux session. The same as Stop in Breadstick. Terminal tabs and floating apps close with the session; your files are untouched. Start it again from Breadstick.
Repair Linux packages. Runs, as root inside Linux, the steps Breadstick's own Repair (Settings, Troubleshooting) runs when a package install was interrupted: finish pending configuration, fix broken dependencies, then reinstall the breadstick-desktop package so its files are whole. Needs a Linux session running and an internet connection; can take several minutes. Its output appears below as it runs.
Restart audio. Restarts the sound server inside Linux, the same as Restart audio in Breadstick's Settings. Apps that already went silent may need to be reopened.
Force-stop Breadstick. Android closes the app and everything running in Linux at once, like swiping it away. For when Breadstick itself is stuck. Nothing is deleted; open it again from the launcher.
Connect a device first.
The exact commands
Stop the Linux session (Breadstick's adb door; --user 10 is added on a Googlebook):
adb shell am start -n io.breadstick/.api.Adb -a io.breadstick.action.STOP_DESKTOP
How a Linux command reaches Breadstick: the script goes to Breadstick's shell door as base64 (so no quoting can go wrong), Breadstick runs it as the Linux user or root, and the page reads the output file and the exit code back until the exit code appears:
adb shell am broadcast -n io.breadstick/.api.AdbShellReceiver -a io.breadstick.adb.SHELL --es cmd 'echo <script as base64> | base64 -d | sh' --es id <id>
adb shell cat /sdcard/Android/data/io.breadstick/files/adb/<id>.out
adb shell cat /sdcard/Android/data/io.breadstick/files/adb/<id>.rc
What ran on the device
Backup and restore
Backing up a Linux system to the computer from this page needs Breadstick 3.0, which is coming. Today, Breadstick itself does it: Settings, Backup has Back up now and Restore, writes the whole Linux system to one file in a folder you choose, and can run automatic encrypted backups. Backup and restore in the docs. This card reads the installed version and will enable itself when a Breadstick that supports it is found.
Connect a device to read the installed version.
Doing it by hand
Every command on this page is an ordinary adb command, written out on its card, and adb from Android's developer tools runs them exactly as well. The troubleshooting guide keeps the manual instructions. This page exists for people who would rather not install a developer toolkit to flip one switch.
The page is built from open source libraries (Tango ADB, MIT) and is itself part of Breadstick Linux. If something here does not behave as its card describes, write to hello@breadstick.io with the report from the Device check.