Skip to content
cyenitePublic

About

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.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

annex

CI License: Apache-2.0

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.

A terminal running annex up, ls, freeze, thaw, snap save and install, next to the instance's Android 15 home screen

Install

annex is a single binary. You need Rust 1.88 or newer to build it:

cargo install --git https://github.com/cyenite/annex
annex setup

Tagged 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.

What annex setup does

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.

annex setup listing what is already set up, the one step that needs sudo and the step that doesn't

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.

annex doctor reporting each requirement as ok or warn

Requirements

  • 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 setup installs.

Quick start

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:5600

annex 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.

Why annex

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.

Using annex

Commands that act on one instance take its name. Leave the name out to mean default, or the only running instance.

Instances

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 data

Instances 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.

Freeze, snapshots and reset

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 boot

Snapshots are taken while the instance is frozen, so they are consistent without a reboot. reset and rm always need the instance's name.

Apps, windows and files

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.pdf

To target a specific instance, put its name first: annex install pixel app-debug.apk.

Location

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 position

To 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.

CI and scripts

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
  • --ephemeral deletes a new instance and its data volume at annex down, so every run starts from first boot. Without it, down keeps the instance and its data, including its device id: apps and servers that remember the device see the same one next time.
  • --wait-boot also waits until the package manager answers, so adb install works at once.
  • --timezone sets the time zone and turns automatic time zone off; --locale sets the system language (a change restarts Android's framework once, about 15 s); --animations off turns 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, and annex ls --json lists every instance with its serial, state and whether it's ephemeral. Ports are handed out in order, so don't hardcode 127.0.0.1:5600 when other instances may exist.
  • Without a desktop session (SSH, CI), annex up opens no window and adds no app launcher entry; ephemeral instances never get one.
  • In a container (systemd-detect-virt --container), annex doctor and annex setup say 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 if annex net slow and lossy are needed and its kernel doesn't load them on demand.
  • setup --ci needs root or passwordless sudo, and exits non-zero when something is left for a person to do.

Network conditions

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 normal

offline 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.

Recordings and logs

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 terminal

A 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.

On your desktop

Annex Manager

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.

Annex Manager listing two running instances, each with Show, Freeze and Stop buttons

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).

App launcher

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.

Desktop bridge and panel menu

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 foreground

The 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.

Two modes

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.

Security

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 is unauthorized, 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.

Limits

  • 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.

Troubleshooting

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.

How it works

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.

Contributing

Bug reports, fixes and new ideas are welcome. Start with CONTRIBUTING.md.

License

Apache-2.0

About

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.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages