This project started as an effort to get the Cuttlefish Android Emulator running on Fedora Asahi Remix. ika (イカ) is the Japanese word for cuttlefish (or squid) and the name stuck, even as it evolved to include x86-64 support.

Ika consists of two components: The Android OS disk image (the device ROM, informally) and a virtual machine player (Cuttlefish) that runs Android on x86-64 or ARM64 (Asahi) Linux hosts.

Prebuilt packages for Fedora Linux (.rpm) and Debian/Ubuntu (.deb) are linked below from the latest release (260629). Pick the row for your package and the column for your distro and CPU architecture.

The Mesa packages supplied by Debian 13 and Ubuntu 26.04 are too old for Ika; install the supported Mesa stack from a suitable backport or PPA archive.

On Debian 13 (trixie), enable trixie-backports and install the Mesa stack from backports using the Debian Backports instructions.

On Ubuntu-family hosts, use the Kisak Mesa PPA instructions.

You will need a minimum of 16 GB RAM, 500 GB of free storage, and some patience for the build to complete. ika-build handles the installation prerequisites.

# 1. Clone:
git clone https://github.com/DesktopECHO/ika.git
cd ika

# 2. Build:
#    Prepares signing certificates, installs build dependencies, downloads
#    LineageOS 23.2 source, applies the overlay and source patches in lineageos,
#    builds the Cuttlefish target for the host arch, creates RPM or Debian packages
#    and prints the package installation command when the build is complete.

./ika-build

# 3. Reboot.
#    Required so group memberships, limits, udev rules, and device permissions
#    are picked up cleanly. Logging out is not enough.

sudo reboot

# 4. Launch
ika start

A few seconds after the virtual device starts, the bundled ika virtual console opens automatically against the running Cuttlefish instance. The virtual console uses Cuttlefish raw frames for both windowed and fullscreen sessions.

Once you have an initial build, use the narrowest command that matches the work you changed:

• Full build — re-run ./ika-build, then run the installation command it prints. Extra arguments are forwarded to the ROM build, for example ./ika-build x86_64, ./ika-build --microg arm64, or ./ika-build --mtg x86_64. With no arguments, ika-build prompts for microG, MindTheGapps, or DeGoogled with no App Store before building the host-native ROM.
• ROM only — re-run ./lineageos/scripts/build_lineageos_desktop.sh (or pass arm64 / x86_64 to limit it to one target). Use this after editing patches or overlays under lineageos/. Pass RESET_PATCHED_PROJECTS=1 if you want patched source projects in the workspace reset before re-applying.
• Host packages only — re-run ./tools/buildutils/build_packages.sh. Use this after editing host sources under base/ or frontend/, after editing the package metadata under base/rpm/, base/debian/, frontend/rpm/, or frontend/debian/, or whenever you've finished a fresh ROM rebuild and want to repackage ika-lineageos with the new contents. Install those outputs directly with your distribution's package manager.

See lineageos/README.md for ROM-build options (provider selection, target subsets, microG release pinning, native-bridge sources, workspace overrides) and tools/buildutils/cw/README.md for the optional containerized RPM build.

After the packages are installed, ika is available on your PATH and can be used to start, stop, and restart the packaged Cuttlefish environment.

# Start a windowed VM
ika start 

# Check whether the VM is running
ika status

# Stop the VM
ika stop

# Factory reset the VM and clear instance state
ika reset

# Restart with new launch arguments
ika restart --gpu_mode=gfxstream --cpus=8 --memory_mb=8192

# Explicitly force the GLES+Vulkan gfxstream context set
ika restart --gfxstream_vulkan=on

# Factory reset and use a 128 GB userdata image on the next start
ika reset --data_gb=128
ika start

# Show the built-in usage text
ika help

ika start and ika restart pass extra arguments directly to cvd_internal_start, so you can override launch settings on the command line. ika stop calls the matching low-level stop helper and then cleans up local Cuttlefish processes. ika reset is the destructive variant; it passes --clear_instance_dirs and removes the local Chromium-install stamp.

By default ika uses:

• host tools from /usr/lib/cuttlefish-common
• the packaged LineageOS tree from /usr/share/cuttlefish-common/lineageos
• instance state under ~/ika
• a ~64 GB thin-provisioned ext4 userdata image
• guest vCPUs set to the available/performance-core count minus two, capped at 12
• guest RAM set to about one quarter of host RAM, rounded to 2 GB steps and capped at 32 GB
• gfxstream GPU acceleration
• Ethernet-only guest networking by default; Wi-Fi, Bluetooth, NFC, UWB, GNSS, and the modem simulator remain off unless explicitly enabled

gfxstream is the preferred GPU mode for the packaged workflow. Use guest_swiftshader only as a troubleshooting fallback when host GPU acceleration is not usable. The launcher selects EGL's surfaceless platform for gfxstream so an unavailable X11 display inherited from SSH cannot redirect host renderer initialization. The desktop product also leaves gfxstream's optional program-binary link-status feature disabled; shader source compilation remains available and avoids corrupt cached-program rendering on affected games.

Pass --data_gb=128 to ika reset to choose the size, in decimal gigabytes, of newly created userdata. The selected size is stored under ~/ika and takes effect on the next ika start. It remains the configured size for later factory resets until changed by another ika reset --data_gb=....

ika has a launcher-level switch for the gfxstream Vulkan context:

ika start --gfxstream_vulkan=auto
ika restart --gfxstream_vulkan=off
ika restart --gfxstream_vulkan=on

auto is the default. When the primary host Vulkan device is llvmpipe, auto requests GLES-only gfxstream (gfxstream-gles:gfxstream-composer). On Apple Silicon hosts with 16 KiB pages, auto leaves Cuttlefish's normal GLES+Vulkan selection in place and routes host-visible guest Vulkan memory through the udmabuf-backed path the Apple GPU supports. On other hosts, auto leaves the normal Cuttlefish gfxstream defaults alone, so systems with hardware Vulkan keep Vulkan enabled.

Use --gfxstream_vulkan=on to re-enable gfxstream Vulkan for testing, or --gfxstream_vulkan=off to force GLES-only gfxstream. The same policy can be set with GFXSTREAM_VULKAN=auto|off|on; an explicit --gpu_context_types=... argument takes precedence.

The guest advertises OpenGL ES 3.2 through gfxstream, including ANDROID_EMU_gles_max_version_3_2, with fallback to ES 3.1, 3.0, and 2.0 when the host translator cannot provide 3.2. Vulkan remains the preferred accelerated API for applications that support it.

The repo currently builds these host package names. On RPM distributions, outputs land under rpmbuild/RPMS/; on Debian-family distributions, outputs land under deb/. Non-primary packages are moved into an extras/ subdirectory by tools/buildutils/build_packages.sh.

• ika-base - Core host binaries, networking helpers, system services, and the bundled virtual console used by the ika launcher
• ika-user - Browser-facing operator service
• ika-orchestration - Host Orchestrator service and nginx config
• ika-integration - Cloud integration utilities
• ika-defaults - Optional defaults override service and config
• ika-metrics - Metrics transmitter binary
• ika-lineageos - Bundled lineageos/ tree installed under /usr/share/cuttlefish-common/lineageos
• ika-common - Compatibility metapackage for the primary host packages

For the local workstation workflow, ika-base and ika-lineageos are the key packages; ika-base includes the virtual console used by the ika launcher. On RPM distributions, the specs also provide and obsolete the old cuttlefish-* package names for upgrades, but newly built package files use the ika-* names.

On ARM64 Asahi Linux, this fork keeps gfxstream as the forward path. The default auto policy keeps Cuttlefish's GLES+Vulkan contexts enabled on Apple Silicon 16 KiB-page hosts and applies the required udmabuf-backed external-memory path. guest_swiftshader remains a fallback for isolating host GPU issues.

ika expects your login session to be in kvm, cvdnetwork, render, and video. The ika-base package adds the installing user to these groups during package configuration, but the active session, its PAM resource limits, and the live /dev/kvm udev permissions don't pick up the new state without a reboot — see step 3 of the Quick start for the full list of what's deferred.

Bazel is installed automatically through Bazelisk by ./ika-build, which runs tools/buildutils/installbazel.sh during its dependency step. That step (tools/buildutils/lib/dependencies.sh) handles the main build dependency install near the start of a build rather than partway through. The signing-key bootstrap may install its small certificate tool set first if needed. The standalone build scripts (build_lineageos_desktop.sh, build_packages.sh) assume dependencies are already installed and fail fast when one is missing.

The networking helper uses nftables exclusively — both the host-side bridge/NAT setup in cuttlefish-host-resources.sh and the per-user cvdalloc daemon manage their rules via native nft commands against a shared ip cuttlefish table. iptables (and iptables-nft) and ebtables are no longer runtime dependencies.

The current GCE image tooling in this fork lives under tools/baseimage/. See tools/baseimage/README.md for the current workflow.