Fast Android instances for Linux developers. An instance boots in about 20 seconds, freezes and thaws in a fifth of a second, and shows up in Android Studio, Flutter and adb as an ordinary device.
annex is a single binary. You need Rust 1.88 or newer to build it:
cargo install --git https://github.com/cyenite/annex
annex setupTagged releases also publish a prebuilt x86_64 Linux binary on the Releases page.
To update later, run annex update. It installs the latest release after checking its SHA-256, or rebuilds the latest source while no release is published; annex update --check only looks.
annex setup checks the machine, then shows what it will change, split into what needs administrator access and what doesn't, and asks once. It can:
- load the Android binder kernel module now and at every boot;
- install the container engine, the Android debug tools and the window helper with your distribution's package manager (apt, dnf, pacman or zypper);
- let your user run containers without sudo;
- keep the disk images Android mounts inside each instance from showing up as drives in your dock and file manager;
- download the Android 15 image, with live speed and time left;
- on a desktop, run the desktop bridge with your session (clipboard, notifications, panel menu) and install Annex Manager, the window app;
- with
--window-mode, set up window mode.
On a desktop, annex setup is the only step: everything below is in place when it finishes. --no-bridge and --no-manager leave those out, and over SSH they're skipped anyway.
sudo asks for your password once; annex never sees it. Setup is safe to re-run: anything already in place is skipped. --dry-run shows the plan without changing anything, --yes skips the question for scripts, and --repair resets window mode's system service when it gets out of sync.
You can also check without changing anything: annex doctor.
- x86_64 Linux with a kernel that has Android binder support. Ubuntu's kernel, Arch's linux-zen and Fedora's kernel do.
- An Intel or AMD GPU for hardware rendering. NVIDIA works with software rendering.
- Everything else,
annex setupinstalls.
annex setup # check this machine, show the plan, fix what's missing
annex up # start the `default` instance (Android 15) and open its window
flutter run -d 127.0.0.1:5600annex up prints the instance's adb serial and opens its window; --no-window skips the window, and none opens outside a desktop session, so scripts and CI are unaffected. Android Studio lists the instance in the device picker like any phone, and it appears in your desktop's app launcher.
annex runs Android in a container on your own kernel instead of a virtual machine. On the reference machine, the edit, install and launch loop was about 8x faster than an Android Studio emulator, and idle memory was about a third.
| Android Studio emulator | annex | |
|---|---|---|
| Cold boot | 70.7 s | 17.9 s |
| Resume | 6.6 s | 0.16 s |
| Reinstall + launch an app | 17.3 s | 2.0 s |
| Idle memory | 1.39 GB | 0.53 GB |
Medians of 3 runs on an i7-1365U laptop with Intel graphics. Method and raw data: phase0/RESULTS.md.
Commands that act on one instance take its name. Leave the name out to mean default, or the only running instance.
annex up # create or start `default` (Android 15), open its window
annex up old --android 13 # another instance, on Android 13
annex up tablet --display 1600x2560/320 # screen size and density
annex ls # list instances
annex down old # stop; data is kept
annex rm old # delete the instance and its dataInstances listen for adb on 127.0.0.1:5600 and up, outside the 5555-5585 range that adb scans for emulators. Changing --display on an existing instance rebuilds it and keeps its data.
annex freeze # pause in memory, about 0.1 s
annex thaw # resume, about 0.1 s
annex snap save logged-in # save all app data under a label
annex snap ls
annex reset default --to logged-in # restore that snapshot (about 20 s)
annex reset default # back to first bootSnapshots are taken while the instance is frozen, so they are consistent without a reboot. reset and rm always need the instance's name.
annex install app-debug.apk # install or update, permissions granted
annex show # a window with the whole screen
annex open com.example.app # one app in a desktop window of its own
annex push ~/fixtures/photo.jpg # into /sdcard/Download by default
annex pull /sdcard/Download/report.pdfTo target a specific instance, put its name first: annex install pixel app-debug.apk.
Apps see GPS location, reported through Android's own GPS service like a real receiver, so it isn't marked as a mock location. An instance starts at the Android emulator's default position; move it, or let it follow this computer:
annex location # where the instance is
annex location -1.2921,36.8219 # a fixed position, kept across restarts and snapshots
annex location "https://maps.app.goo.gl/..." # or a Google Maps link, in quotes
annex location host # this computer's location, through the desktop bridge
annex location default # back to the default positionTo pin an exact spot, right-click it in Google Maps and click its coordinates to copy them, or copy the place's link; annex location takes either. A place link puts the instance on the place's pin.
host is opt-in per instance and needs the desktop bridge and your desktop's Location Services; GNOME asks once whether Annex may use your location. A computer without GPS finds itself by looking up nearby Wi-Fi networks, and where the lookup service doesn't know them it guesses from the IP address, which can be tens of kilometers off. annex location shows how close the computer's position is; for anything that depends on being at an address, pin the spot instead. The position is only shared with instances you set to host from this computer; that choice is kept here, not in the instance, and annex rm withdraws it.
annex runs on CI runners and headless machines, including inside a privileged LXD container. A typical end-to-end job:
annex setup --ci # never prompts; no bridge, no Annex Manager
annex doctor --json # every check as JSON; exits non-zero when one fails
annex up e2e --ephemeral --wait-boot --timezone Africa/Nairobi --locale en-KE --animations off
serial=$(annex serial e2e) # 127.0.0.1:5600, or the next free port
flutter test integration_test -d "$serial"
annex down e2e # an ephemeral instance is deleted with its data--ephemeraldeletes a new instance and its data volume atannex down, so every run starts from first boot. Without it,downkeeps the instance and its data, including its device id: apps and servers that remember the device see the same one next time.--wait-bootalso waits until the package manager answers, soadb installworks at once.--timezonesets the time zone and turns automatic time zone off;--localesets the system language (a change restarts Android's framework once, about 15 s);--animations offturns window, transition and animator animations off. They are saved on the instance's data, like a change made in Settings.annex serial [NAME]prints an instance's adb serial, andannex ls --jsonlists every instance with its serial, state and whether it's ephemeral. Ports are handed out in order, so don't hardcode127.0.0.1:5600when other instances may exist.- Without a desktop session (SSH, CI),
annex upopens no window and adds no app launcher entry; ephemeral instances never get one. - In a container (
systemd-detect-virt --container),annex doctorandannex setupsay what to do on the host: the container shares the host's kernel, so the host loads binder (sudo modprobe binder_linux, and at boot through /etc/modules-load.d/), and the container must be privileged and nested. The host also loads the traffic shaping modules ifannex net slowandlossyare needed and its kernel doesn't load them on demand. setup --cineeds root or passwordless sudo, and exits non-zero when something is left for a person to do.
Test how an app behaves offline or on a poor connection:
annex net offline # every installed app loses its network
annex net slow # about 1 Mbit/s each way, 300 ms added latency
annex net lossy # one packet in ten lost, 50 ms added latency
annex net # show the current condition
annex net online # back to normaloffline blocks every installed app through Android's own firewall, so Android tells the apps they have no network, as a phone with no signal would; apps installed afterwards aren't blocked until you run annex net offline again. slow and lossy shape the instance's network connection. adb is never affected, so IDEs and test runners stay connected. A condition lasts until the instance restarts. slow and lossy need the kernel's traffic shaping modules, which most kernels load on demand; annex setup loads them where they don't. Container mode only.
Keep evidence of a test run:
annex record e2e start -o run.mp4 # record the screen in the background, no window
annex record e2e stop # finish the video
annex logs e2e -o logcat.txt # Android's log, logcat's threadtime format
annex logs e2e --since 10m # only the last 10 minutes, to the terminalA recording has no time limit (Android's own screen recorder stops at 3 minutes) and needs no desktop session, so it works on CI runners; stop works from any shell or a later CI step. Android keeps only its most recent log, so for a long run, save it before the instance stops.
Annex Manager is a window app for everything above: every instance as a card with its state and actions, a page per instance with its details, screen size and snapshots (save, restore, delete), a New instance dialog, and settings for the bridge and for opening Annex when you log in. Drop an APK on a running instance's card to install it.
Open it from your app launcher ("Annex"), from the panel menu, or with annex manager. annex setup installs it on a desktop, and annex update keeps it current. It needs GTK 4 and libadwaita 1.5 or newer, which GNOME 46 and later include (Ubuntu 24.04 and newer).
Every instance gets an entry in your app launcher and dock. Clicking it starts the instance if needed and opens its screen; right-click for Freeze, Thaw, Stop and Reset to any snapshot. annex up adds the entry and annex rm removes it; annex launcher install and annex launcher remove do it by hand. Launchers report problems as desktop notifications.
The bridge keeps one clipboard across your desktop and every running instance, shows Android notifications as desktop notifications, shares this computer's location with instances set to annex location host, and puts an annex menu in your panel. The menu lists every instance with its state and offers Show, Freeze or Thaw, Snapshot now, Reset to, Stop, and New instance.
annex bridge install # run it with your desktop session (annex setup does this)
annex bridge status
annex bridge run --verbose # or run it in the foregroundThe bridge attaches to instances as they start and detaches when they stop or freeze. On GNOME, the panel menu needs the AppIndicator extension, which Ubuntu enables by default; KDE shows it natively. Logs: journalctl --user -u annex-bridge -f.
Instances run in container mode unless you ask for window mode:
annex up desk --mode window
annex open desk com.example.app # opens in a native desktop window| Container mode (default) | Window mode | |
|---|---|---|
| Instances | as many as you like | one |
| Android versions | 13, 14, 15 | from its system image |
| App windows | annex open, mirrored |
native desktop windows |
| Freeze and thaw | yes | yes |
| Snapshots and reset | yes | no |
| Clipboard and notifications | through the desktop bridge | built in |
Set window mode up first with annex setup --window-mode.
Container-mode instances run as privileged containers, so each one is root-equivalent on the host. annex keeps them closed to other local users:
- adb only accepts your adb key (
~/.android/adbkey.pub). Any other key isunauthorized, including through the container's network address. - Nothing else listens: the simulated Bluetooth service, which opens network ports, is disabled.
- Snapshots, which contain every app's private data, are readable only by you.
- The bridge never logs clipboard contents, only sizes.
Anyone in the docker group can still open a shell in an instance, as with any container. See SECURITY.md to report a vulnerability.
- No Google Play. Apps that need Play Integrity (banking, some games) will not run. Use a real device or an emulator for those. Firebase Cloud Messaging can't register either, so push notifications from a server never arrive; notifications an app posts itself still show.
- Location is simulated. Positions come from annex, not a GPS receiver (see Location). There is GPS location but no network location.
- No Bluetooth. Instances can't reach this computer's Bluetooth adapter yet.
- No camera. Instances report that they have no camera, like a phone without one, so apps can't take photos or scan codes on them yet. An app that assumes every phone has a camera needs to handle the case where it finds none.
- No Android 16 yet. Its system services need a kernel feature (ashmem) that mainline kernels no longer have.
- x86_64 Linux only for now.
| Symptom | Fix |
|---|---|
annex up fails at once |
Run annex doctor, then annex setup to fix what it reports. |
annex doctor in a container says binder must be loaded on its host |
Load it on the host (sudo modprobe binder_linux, and list binder_linux in /etc/modules-load.d/), and make the container privileged and nested. |
| The device shows up twice in adb | Something published adb on 5555-5585. annex uses 5600 and up; remove the other mapping. |
| Android Studio loses its devices | Two adb versions on one machine kill each other's server. Point Studio and your PATH at the SDK's adb. |
| A Flutter debug build crashes on launch | The APK was built for a phone (arm64). Let flutter run build for the instance, which is x86_64. |
| Window mode won't freeze, saying its state is out of sync | Run annex setup --repair. |
| An app says location is off although it's on in Settings, or rejects it as a mock location | Run annex up for that instance: an instance that was already running when you updated annex gets its GPS on its next annex up (data kept). An app that recorded mock locations before may need its data cleared. |
| Opening the camera crashes an app, or the Camera app stops | Run annex up for that instance: an instance that was already running when you updated annex reports that it has no camera from its next annex up (data kept). |
| No annex menu in the panel | On GNOME, enable the AppIndicator extension; annex doctor checks for it. |
| Dozens of small drives fill the dock while an instance runs | Run annex setup. Android mounts each of its system modules as a disk image, and setup tells your desktop to ignore them. |
annex is a thin, stateless layer. A container-mode instance is a container named annex-<name> with a data volume; its port, Android version and display live in the container's labels, so there is no state file to drift. Freezing pauses the container's processes in place. Snapshots stream the data volume out of the frozen container. The desktop bridge runs a small helper on each instance and speaks its control protocol to share the clipboard, and it watches Android's notification service for new notifications.
annex builds on several open-source projects; annex about --licenses and THIRD_PARTY_NOTICES.md list them with their licenses. The plan and what comes next: ROADMAP.md. Changes by version: CHANGELOG.md.
Bug reports, fixes and new ideas are welcome. Start with CONTRIBUTING.md.



