Making a custom distro Linux Terminal app (github)

OutlawSanZhang

Update: I just released the new version with serial console capability and the Alpine image:
https://github.com/outlawsanzhang/koiTerminal/releases/tag/2026012800
It has some rough edges, but I am very happy to reach this milestone. Plus, splash screen ASCII art!

AcclaimSublevel19

Hey @OutlawSanZhang! I've installed the app, but the image download fails. Here's the relevant part of the log:

02-05 06:07:48.583 29648 29648 I VmTerminalApp: installing..
02-05 06:07:48.589 29648 32192 I VmTerminalApp: Entering downloadFromSdcard with /storage/emulated/10/linux/images.tar.gz
02-05 06:07:48.592 29648 32192 D VmTerminalApp: Install started. source: https://example.com/android/ferrochrome/4000000/aarch64/images.tar.gz, destination: /data/user/10/com.android.virtualization.koiterminal/files/linux
02-05 06:07:48.600 29648 29648 D VmTerminalApp: Starting service ...
02-05 06:07:49.565 29648 32192 E VmTerminalApp: Installation failed
02-05 06:07:49.565 29648 32192 E VmTerminalApp: java.io.FileNotFoundException: https://example.com/android/ferrochrome/4000000/aarch64/images.tar.gz
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.okhttp.internal.huc.HttpURLConnectionImpl.getInputStream(HttpURLConnectionImpl.java:255)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.okhttp.internal.huc.DelegatingHttpsURLConnection.getInputStream(DelegatingHttpsURLConnection.java:211)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.okhttp.internal.huc.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionImpl.java:30)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at java.net.URL.openStream(URL.java:1072)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.virtualization.koiterminal.ImageArchive.getInputStream(ImageArchive.kt:100)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.virtualization.koiterminal.ImageArchive.installTo(ImageArchive.kt:119)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.virtualization.koiterminal.InstallerService.downloadFromUrl(InstallerService.kt:192)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.virtualization.koiterminal.InstallerService.access$downloadFromUrl(InstallerService.kt:47)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at com.android.virtualization.koiterminal.InstallerService$requestInstall$2.run(InstallerService.kt:140)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1154)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:652)
02-05 06:07:49.565 29648 32192 E VmTerminalApp: 	at java.lang.Thread.run(Thread.java:1563)

Seems to be a misconfigured domain. Do you think you can push a fix?

OutlawSanZhang

AcclaimSublevel19
Did you put the images.tar.gz in the linux folder and grant it file access? If not, please follow the How to use section in the README. It does not work out of the box.

AcclaimSublevel19

OutlawSanZhang Yeah, I gotta learn how to read. I'll try it out now. Thanks for the quick reply!

OutlawSanZhang

AcclaimSublevel19
No problem! It would be very appreciated if you could detail the errors you encountered with the Alpine and Debian images, for example by opening an issue.

AcclaimSublevel19

OutlawSanZhang the errors I described are nothing new, you mention both in the README. Debian gets kernel logs in between console output (and it also seems like I can't type in there). Alpine fails to mount storage and as such almost nothing works. I can't even set up internet. I totally understand that this is experimental software, I was just pointing out what to expect. I really want this project to succeed and I'd love to help test in any way!

OutlawSanZhang

AcclaimSublevel19
Thank you for the kind support! And ouch, neither issue was supposed to happen. Right now I can reproduce the Debian serial console not working (only ttyd works), which I will fix for the next release. But from my current testing, Alpine should mount storage and boot normally, instead of being stuck in initrd. A bug report would be very helpful towards fixing Alpine.

void0

@OutlawSanZhang I found a couple bugs and had a few ideas looking through the code. Would you prefer I make 5 different issues on your github, consolidate them all into a single issue or post them here, I just don't want to spam you.

The addition of a serial console is incredible (you are incredible lol), I genuinely cannot wait until this is upstreamed and honestly I am surprised google went with ttyd + a custom web ui instead of a serial console in the first place. The ominous loading wheel while the terminal boots tells me nothing about where it's hanging.

I read through the codebase and would love to contribute but I am not an android dev and building AOSP every time I make a small iteration sounds tedious. What is the process like and what are the build times after the initial build in your experience?

Also since you are supporting alternative distros/images there is a preexisting nixos image here that should probably work out of the box. https://github.com/nix-community/nixos-avf

OutlawSanZhang

void0
Thank you for your kind words, it means a lot!

Yes, 5 different issues is fine and helps tracking things. The compiling is slow the first time, but subsequent builds take about 2 minutes, or maybe 1 minute if you Ctrl+C when it starts to build the OS image. It does require that _400GB storage, though.

https://github.com/nix-community/nixos-avf

I did not know about this, this sounds cool. If only I knew before I took on the quest of compiling kernels! I tried it and it has does indeed boot out-of-the box, but it runs into the same virtiofs issue that the Google Debian image has. I'll have to work on it a bit to support it, but the same fix probably works.

OutlawSanZhang

Update:
At long last, Secureblue on GrapheneOS.

https://github.com/outlawsanzhang/koiTerminal/blob/koiterminal/IMAGES.md#secureblue

^ Screenshot

This one was really hard. OSTree systems are no fun to customize. Plus there was the kernel issue, which I still need help on. My Pixel 8 cannot run on the latest kernel, and using a one-year-old kernel from Fedora 41 defeats the purpose of using Secureblue.
I will make a separate post once I fix a few bugs and outdated UI in the app itself.
(And NixOS is now supported too, thanks to nixos-avf)

OutlawSanZhang

Update: there's a new release for bug fixes that solves most issues I found with the app.

Also, @void0 I found the right way to build just the app and its dependencies, and I have updated the build guide accordingly.

AcclaimSublevel19

@OutlawSanZhang have you seen this? https://github.com/ExTV/Podroid

void0

OutlawSanZhang I haven't taken a look at this yet simply because building AOSP is a bit more daunting than compiling a gradle/flutter app lol. If you added a non-aosp build script I would start tearing through the codebase that same night.

I am planning on writing a patch to force wifi calling through a userspace vpn. When I find some time to do so I will look into building aosp, and I'll circle back.

OutlawSanZhang

AcclaimSublevel19
No, but from what the README they use QEMU TCG, which is CPU emulation (even if running arm64 on arm64). That will be quite slow. It is a real VM, though.

void0
That reminds me. I can look into how to build just the virtualization apex.

OutlawSanZhang

The app has been ported to Android 17.

OutlawSanZhang

Two new experimental features that are very exciting (to me) has been added: sharing the host's VPN connection via a socks5 proxy, and port forwarding.

Currently requires some manual set up, but I'll build a Secureblue image with these included out of the box soon.

These are backed by vsock connections. Since I got vsock working, I'll probably add some sort of remote desktop feature so we can have GUI afterwards. The vanilla Linux Terminal app uses a display API that seems to be only available to privileged apps, unfortunately.

NetRunner88

OutlawSanZhang
Noice

chemical_cinema

Hi, I've been a user of your app for some time. Recently though I did a fresh grapheme install I've been unable to get the Debian image to load. I put the images.tar.gz file in the Linux folder and open the program. It loads the files and then crashes. Any attempts to reopen the app immediately crash.

I double checked the special permissions are granted in ADB

I'm using storage scopes to the Linux folder

Any advice appreciated.

Also thanks for making this app it's really cool.

type: crash
osVersion: google/akita/akita:17/CP2A.260805.005/2026090701:user/release-keys
userType: full.secondary
package: com.android.virtualization.koiterminal:2026090700, targetSdk 37
process: com.android.virtualization.koiterminal
processUptime: 49969 + 716 ms
installer: dev.imranr.obtainium.fdroid

java.lang.NoSuchMethodError: No virtual method setConsoleInputDevice(Ljava/lang/String;)Landroid/system/virtualmachine/VirtualMachineConfig$Builder; in class Landroid/system/virtualmachine/VirtualMachineConfig$Builder; or its super classes (declaration of 'android.system.virtualmachine.VirtualMachineConfig$Builder' appears in /apex/com.android.virt/javalib/framework-virtualization.jar)
	at com.android.virtualization.koiterminal.ConfigJson.toConfigBuilder(ConfigJson.kt:95)
	at com.android.virtualization.koiterminal.new2.core.VmController$start$1.invokeSuspend(VmController.kt:185)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
	at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:100)
	at kotlinx.coroutines.internal.LimitedDispatcher$Worker.run(LimitedDispatcher.kt:113)
	at kotlinx.coroutines.scheduling.TaskImpl.run(Tasks.kt:89)
	at kotlinx.coroutines.scheduling.CoroutineScheduler.runSafely(CoroutineScheduler.kt:586)
	at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.executeTask(CoroutineScheduler.kt:820)
	at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.runWorker(CoroutineScheduler.kt:717)
	at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.run(CoroutineScheduler.kt:704)
	Suppressed: kotlinx.coroutines.internal.DiagnosticCoroutineContextException: [StandaloneCoroutine{Cancelling}@e70800, Dispatchers.IO]
```
`

« Previous Page