HiSH and running a real Linux shell on a HarmonyOS device

A HarmonyOS app that boots a Linux machine under QEMU

HiSH runs a Linux Shell on HarmonyOS devices, and the implementation is not an emulator of a shell but an actual virtual machine. It is based on qemu-ohos, the project's own QEMU port for the platform, and it supports 2in1 PC style devices, tablets and phones.

That distinction decides everything about the project. A shell reimplementation would be a parser with a few builtins, fast but a fiction. HiSH instead gives you a full arm64 Linux kernel, an Alpine Linux root filesystem, networking with port forwarding, shared folders between the guest and the device, and virtual keys for Tab, Ctrl, Esc, Shift, Fn and the arrow keys. The guest is a real Linux system with a real package manager, which is the point for the people who use it.

The cost of that realism is that you are running a machine inside a machine, on a phone. Everything the guest does goes through emulation, and the project is explicit about the performance tiers rather than pretending the problem does not exist.

The repository is MIT licensed and the last push was on 2026-10-11, so the work is current. The recent release tags are release-20260516, release-20260419 with support for a custom VNC port, and release-20260418 with native VNC support, which is a useful hint that remote screen access was a substantial piece of recent work. The project pages live under docs/guide, and the code is organised as a standard HarmonyOS application with a feature directory, a product directory, a deps directory for the QEMU sources and hvigor as the build tool.

JIT support is the dividing line between the three install routes

There are three ways to get HiSH, and the documentation attaches a performance condition to each one. The choice is not about convenience alone, it determines how fast the guest runs.

The first is the app market. The app gallery listing is the easiest route, and the note attached to it is that because of app market policy restrictions JIT is not supported there, so running efficiency is average.

The second is downloading a hap file from the Releases page, self signing it and installing it on a device or emulator. This route supports JIT and runs more efficiently, with installation instructions in a linked tutorial discussion. Self signing means producing a certificate and configuring the device to accept it, which is a real amount of work for a non developer.

The third is building the source with DevEco Studio, which also supports JIT and runs more efficiently.

That third route is a full HarmonyOS application build, and the build guide spells out the steps. You install DevEco Studio, clone the code, pull the submodules with git submodule update --init --recursive, copy build-profile.template.json5 to build-profile.json5, and download a set of prebuilt files into fixed locations: a libraries archive that unpacks into feature/hish_main/libs, a kernel image at feature/hish_main/src/main/resources/rawfile/vm/kernel_aarch64 and a root filesystem image at feature/hish_main/src/main/resources/rawfile/vm/rootfs_aarch64.qcow2.

Then you build in DevEco Studio, where the default target is product/tablet, and uncommenting the phone module in build-profile.json5 builds the phone variant as well. After signing, you run it on a device or emulator.

The tablet and phone split in the build profile is not a cosmetic detail, because JIT is listed as supported on Pad and 2in1 devices but not on Phone devices. A phone user therefore has the slower path no matter how they install, unless they rebuild QEMU in the interpreter-only configuration described later.

The QEMU library is the piece you can rebuild yourself

Building the libqemu-system library is optional, and the documentation is clear that you do this on Ubuntu or in a Windows WSL2 environment to produce a custom libqemu-system-aarch64.so.

The dependency list for that build is long and specific:

sudo apt install -y build-essential cmake curl wget unzip python3 libncurses-dev \
    git flex bison bash make autoconf libcurl4-openssl-dev tcl \
    gettext zip pigz meson 

The build itself is a make in the deps directory, and the targets decide what you get:

cd deps 
make

The default build targets the x86_64 emulator. For a real device you need the arm64-v8a target, and for a phone that does not support JIT you can build with the aarch64-tci target, which uses the QEMU TCG interpreter instead and produces libqemu-system-aarch64-tci.so. The documentation is blunt about the trade-off: TCI performance is lower than JIT, but it does not depend on JIT support.

That target is the interesting one, because it is the only documented route to a usable phone experience outside the app market. The build output lands in the deps/output directory, and the whole exercise requires the Huawei developer Command Line Tools, downloaded from the developer site, with the TOOL_HOME environment variable pointing at the extracted directory.

In other words, the performance tier you get is a build-time decision, not a runtime setting. The project is effectively asking you to choose a target rather than configure a switch.

The kernel is a v6.12 arm64 build tuned for Neoverse

Building the Linux kernel is also optional, and it is the part of the project that shows how much thought went into the guest configuration.

The kernel dependencies are a second apt line:

sudo apt install build-essential gcc bc bison flex libssl-dev \
 libncurses5-dev libelf-dev gcc-aarch64-linux-gnu \
 clang lld llvm make 

The source is a shallow clone of the upstream kernel at a specific tag:

git clone --depth=1 -b v6.12 https://github.com/torvalds/linux 

And the configuration is not a stock one, it is fetched from the project's own configuration repository:

curl https://raw.githubusercontent.com/harmoninux/linux-config/refs/heads/master/arm64_virt > .config 

The compile flags are the part worth reading, because they tell you what the guest is optimised for. KCFLAGS enables a specific set of armv8.5-a extensions including crc, crypto, lse, rcpc, rng, sm4, sha3, dotprod and fp16, tunes for neoverse-n1, and sets alignment and vectorisation options with a forced vector width of two. The build itself is a standard cross-compile with the LLVM toolchain:

export KCFLAGS='-march=armv8.5-a+crc+crypto+lse+rcpc+rng+sm4+sha3+dotprod+fp16 -mtune=neoverse-n1 -O2 -falign-functions=64 -fno-strict-aliasing -mllvm -vectorize-loops -mllvm -force-vector-width=2'
env KCFLAGS="$KCFLAGS" make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- LLVM=1 LLVM_IAS=1 menuconfig
env KCFLAGS="$KCFLAGS" make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- LLVM=1 LLVM_IAS=1 -j$(nproc)

Neoverse is a server core, and fp16 plus dotprod are the instruction sets you would want for a fast virtualised workload. The resulting image is at arch/arm64/boot/Image and is copied into the project directory. The menuconfig step is left in place, which means the configuration is a starting point you are expected to adjust rather than a sealed artefact.

The root filesystem is built by hand into a qcow2 image

The last optional piece is the root filesystem, and the documented flow is the clearest description of the whole guest image lifecycle in the project.

You start from the Alpine minirootfs archive for aarch64, extract it into a directory, then create a raw disk image and format it as ext4:

qemu-img create -f raw rootfs.img 8G 
mkfs.ext4 rootfs.img 

The image is then mounted as a loop device, populated by copying the Alpine tree into it, and unmounted. The next step converts the raw file to qcow2, which is the format the application expects because qcow2 supports dynamic space allocation:

qemu-img convert -p -f raw -O qcow2 rootfs.img rootfs.qcow2 

Finally the image is placed where the application will read it, under feature/hish_main/src/main/resources/rawfile/vm/, and named rootfs_aarch64.qcow2.

The whole sequence is a few minutes of work with a Linux host and a handful of standard tools, and it produces exactly the artefact that the Releases route ships prebuilt. That symmetry is the point: if the prebuilt image does not suit you, or you want a different distribution, you can build your own and drop it in the same place.

This is also where the image import feature comes from. The core features list includes image import, with an Ubuntu 24.04 image and a Debian 12 image published by the related linux-config repository, and the naming convention with the aarch64 suffix and the qcow2 extension means any image you build yourself can replace the default.

What the guest gives you that a HarmonyOS terminal cannot

The feature list is short enough to read as a summary of the useful parts of a Linux shell, and it is worth reading for what it implies about day to day use.

A complete arm64 Linux kernel and an Alpine Linux root filesystem are the foundation, and Alpine is a deliberate choice for an image of this kind: it is small, it starts quickly, and its package manager is apk, so a guest environment can be created and configured in a few commands over the network or from a shared folder.

Networking with port forwarding is the feature that changes what the guest is for. A port forward means a service listening in the guest, a web server or a database, is reachable from the HarmonyOS side, and from the network if you forward to the right place. That turns the device into something you can ssh into or serve from, and it is the reason someone would run a full Linux rather than a shell.

Shared folders give you the other half: move files between the guest and the device without a network transfer. For a tablet that is docked and used as a small workstation, being able to read a file from the device filesystem inside the guest is the difference between a demo and a usable environment.

The virtual keys are the detail that shows the guest is meant for a touchscreen device. Tab, Ctrl, Esc, Shift, Fn and the arrow keys have to be reachable from a touch screen, and there is no physical keyboard to fall back on. The native VNC support and the custom VNC port in a recent release are the other detail, since a remote display is how you would realistically use the guest on a device whose screen is a touchscreen.

The guest is not a sandboxed toy. It is a Linux machine with a package manager and a network, running under emulation, and the boundary between the guest and HarmonyOS is the interesting part of the design.

Where HiSH is the wrong tool

The first wrong case is a phone that needs to compile anything. JIT is not supported on Phone devices in the shipped configuration, so the guest runs under interpretation, and the documentation states plainly that TCI performance is lower than JIT. Interpreted execution of a full Linux system on a phone is fine for a shell session, reading a file, or checking a configuration. It is not fine for a build, a package install with compilation, or anything else that asks the CPU to do real work.

The second wrong case is when you want a desktop. This is a Linux shell with a shared folder and a virtual keyboard, not a graphical Linux session. The emulated machine has no display, no window manager and no sound. If the goal is a Linux desktop on a HarmonyOS tablet, this is the wrong project, and no amount of configuration will change that.

The third wrong case is a device without HarmonyOS at all, or an application that needs to run in the background under a strict battery policy. The app is an emulator inside a mobile application, and the app market version of it is explicitly restricted from using JIT, which tells you something about the platform's policy towards this kind of workload.

The realistic alternative is to use a real Linux machine, a container on a server, or a cloud shell, and connect to it from the device. The difference in approach is worth stating clearly. HiSH keeps the whole environment on the device, offline, with no account and no server, and the cost is that you are emulating hardware on hardware that was never built for it. A remote shell keeps the compute on hardware that can do the job and costs you a network dependency and a device that is now a thin client. The choice is about where the CPU work happens, and for anything compute heavy the answer is obvious.

A third option, for a developer who only needs a Linux userland rather than a kernel, is a terminal emulator on the device with a statically linked toolset, or a container runtime if the platform offers one. That is lighter, but it is not Linux, and the moment you need to install a package or bind a low port, you are back to the same question.

Maintenance, the licensing convention and the cost of building it yourself

The project is MIT licensed, and the README adds a convention on top of it. Using the code of this project requires, by custom practice, noting in the software's own about screen that it is based on this project, HiSH, together with the repository address. That is a request rather than a licence term, and it is a small and reasonable one for a project that is largely a packaging of other people's work, QEMU and the Linux kernel among them.

The maintenance state is current, with the last push on 2026-10-11 and the most recent release in May 2026. The release notes show the direction of travel, with native VNC and custom VNC port support landing in April 2026, which suggests the project is working on making the guest usable as a remote environment rather than only on the device screen.

The upgrade cost differs by install route. A user of the app market build gets updates through the store and does nothing. A user of a self signed HAP from Releases updates by replacing a file and re-signing it. A builder of the source has the heaviest path, because the three optional artefacts, the QEMU library, the kernel and the root filesystem, are each built separately and each has to be rebuilt and re-integrated when upstream moves.

That last point is the real ongoing cost of the project. You are not just maintaining an app, you are maintaining a small distribution of an operating system: a kernel, a root filesystem and an emulator, kept in step with each other and with the HarmonyOS version you are targeting. The project makes each piece buildable on its own, which is a good design, and it also means each piece is a separate thing that can break independently.

Editorial conclusion

HiSH fits a HarmonyOS developer who needs a genuine Linux environment on a tablet or 2in1 device for shell tooling, or a phone user prepared to accept slower execution without JIT. It is the wrong choice if you need a phone to run compilation at usable speed, or if you want a full desktop rather than a shell with a shared folder. Before you install, check whether the app market build or a self signed HAP suits you, since only the latter enables JIT on tablet and 2in1 hardware, and read the guide under docs/guide for the shared folder and virtual key details.

Frequently asked questions

Official sources

1. harmoninux/HiSH on GitHub
2. Issues
3. License: MIT
4. README
5. Releases