HyperBEAM on iOS

Run a HyperBEAM node on your iPhone or iPad using UTM SE virtualization.

Requirements

iPhone/iPad with iOS 14+
At least 15GB free storage
Android device with Termux (for building)
Both devices on the same WiFi network

Overview

iOS doesn't allow direct Linux execution, so we use UTM SE to run Alpine Linux in a virtual machine. Building HyperBEAM inside UTM is very slow, so we build on Android and transfer the compiled binary.

┌─────────────────┐          ┌─────────────────┐
│  Android/Termux │          │   iOS/UTM SE    │
│                 │          │                 │
│  1. Build       │   WiFi   │  3. Download    │
│  2. Serve ──────┼──────────┼► 4. Run         │
│     :8080       │          │     :8734       │
└─────────────────┘          └─────────────────┘

Installation

Install UTM SE on iOS

Install UTM SE from the App Store
Open UTM SE

Download Alpine Linux

Open Safari and go to: https://alpinelinux.org/downloads/
Download Standard → aarch64 ISO (~200MB)
Or direct link: alpine-standard-3.23.0-aarch64.iso

Create Virtual Machine

Open UTM SE and tap + (plus button)
Tap "New Machine"
Select "Linux"
On Hardware screen:
- Select "ARM64 virtual machine (2014, ARM64)"
- Set Memory to 1024 MiB (or higher)
- CPU Cores: Default
- Tap Continue
On Linux screen:
- Select "Boot from ISO image"
- Tap Browse... and select the Alpine ISO
- Tap Continue
On Storage screen:
- Set size to 10 GiB
- Tap Continue
On Shared Directory screen:
- Skip (just tap Continue)
On Summary screen:
- Change name to "HyperBEAM" (optional)
- Tap Save

Install Alpine Linux

Start the VM (tap play button)
Login as root (no password)
Run the installer:

setup-alpine

Follow the prompts:
- Keyboard layout: none
- Hostname: localhost
- Network interface: eth0
- IP address: dhcp
- Manual network config: n
- Root password: set one (min 5 characters)
- Timezone: your timezone (e.g., UTC)
- Proxy: none
- NTP client: busybox
- APK Mirror: 1 (or f for fastest)
- Setup a user: no
- SSH server: openssh
- Allow root ssh login: prohibit-password
- SSH key: none
- Disk: none
Run disk setup:

setup-disk

Disk: vda
Install mode: sys
Erase disk: y

After install completes, power off the VM:

poweroff

Long-press the VM and tap Edit
In DRIVES section:
- Drag VirtIO Drive above USB Drive (reorder so VirtIO is first)
In Network section:
- Tap New under PORT FORWARD
- Set:
  - Protocol: TCP
  - Guest Address: 10.0.2.15
  - Guest Port: 8734
  - Host Address: 0.0.0.0
  - Host Port: 8734
- Tap Save
Tap Save to save VM settings
Start the VM again and login with your root password

Build on Android

On your Android device with Termux installed:

Beta-1 (default)

curl -sL https://hb-mobile.vercel.app/compile.sh | bash

This will:

Build HyperBEAM in Alpine (proot)
Create hyperbeam.tar
Start an HTTP server on port 8080
Display your Android's WiFi IP

Keep the Android terminal open - it needs to keep serving the file.

Manual Compilation (for learning)

If you want to understand the build process, run these steps manually in Termux:

# Setup Alpine
pkg update -y && pkg install proot-distro python -y
proot-distro install alpine 2>/dev/null || true
proot-distro login alpine

Inside Alpine:

# Install dependencies
apk update
apk add build-base cmake git pkgconfig ncurses openssl openssl-dev curl ca-certificates erlang27 erlang27-dev rust cargo linux-headers lmdb lmdb-dev wget
cd /tmp && wget https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3 && mv rebar3 /usr/local/bin/
 
# Clone HyperBEAM
cd ~ && rm -rf HyperBEAM && git clone https://github.com/permaweb/HyperBEAM.git && cd HyperBEAM
git checkout v0.9-milestone-3-beta-1
 
# Apply ARM64 patches
sed -i 's/WAMR_BUILD_TARGET = X86_64/WAMR_BUILD_TARGET = AARCH64/g' Makefile
sed -i '172s/long ptr, size;/long ptr;\n        int size;/' native/hb_beamr/hb_beamr.c
sed -i '178s/long size_l = (long)size;/size_t size_l = (size_t)size;/' native/hb_beamr/hb_beamr.c
sed -i '179s/char\* wasm_binary/const char* wasm_binary/' native/hb_beamr/hb_beamr.c
sed -i '472s/uint64_t argc/uint32_t argc/' native/hb_beamr/hb_wasm.c
sed -i '473s/uint64_t\* argv = malloc(sizeof(uint64_t)/uint32_t* argv = malloc(sizeof(uint32_t)/' native/hb_beamr/hb_wasm.c
sed -i '476s/for (uint64_t i/for (uint32_t i/' native/hb_beamr/hb_wasm.c
sed -i '477s/argv\[i\] = prepared_args.data\[i\].of.i64;/argv[i] = (uint32_t)prepared_args.data[i].of.i64;/' native/hb_beamr/hb_wasm.c
sed -i 's/wasm_runtime_get_exception(proc->exec_env)/wasm_runtime_get_exception(wasm_runtime_get_module_inst(proc->exec_env))/g' native/hb_beamr/hb_wasm.c
 
# Clone and patch WAMR
git clone https://github.com/bytecodealliance/wasm-micro-runtime.git _build/wamr -b WAMR-2.2.0 --single-branch
sed -i 's/find_package(Threads REQUIRED)/set(CMAKE_THREAD_LIBS_INIT "-lpthread")\nset(CMAKE_HAVE_THREADS_LIBRARY 1)\nset(CMAKE_USE_PTHREADS_INIT 1)\nset(Threads_FOUND TRUE)/' _build/wamr/CMakeLists.txt
 
# Compile
rebar3 compile
 
# Create tar and exit
cd ~ && tar cvf /tmp/hyperbeam.tar HyperBEAM
exit

Back in Termux, serve the file:

mkdir -p ~/hyperbeam-server
cp /data/data/com.termux/files/usr/var/lib/proot-distro/installed-rootfs/alpine/tmp/hyperbeam.tar ~/hyperbeam-server/
cd ~/hyperbeam-server
python -m http.server 8080

Download and Run on iOS

With the Android server running, go to your iOS UTM VM and run:

wget -qO- https://hb-mobile.vercel.app/ios.sh | ANDROID_IP=192.168.x.x sh

Access the Dashboard

Once HyperBEAM starts (you'll see HTTP request logs), you can access it:

From your iPhone (same device):

http://localhost:8734/~hyperbuddy@1.0/dashboard

From another device on the same network:

Find your iPhone's WiFi IP in Settings → WiFi → tap your network, then:

http://IPHONE_IP:8734/~hyperbuddy@1.0/dashboard

Manual Installation

If the script doesn't work, run these commands manually:

# Install dependencies
apk update
apk add wget curl erlang27 lmdb
echo "https://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
apk update
apk add erlang27 lmdb --upgrade
 
# Download from Android (replace with your Android's IP)
cd ~
wget http://192.168.x.x:8080/hyperbeam.tar
tar xf hyperbeam.tar
 
# Start HyperBEAM
cd ~/HyperBEAM
export HB_STORE_PATH=/root/data
mkdir -p $HB_STORE_PATH
erl -pa _build/default/lib/*/ebin -eval "application:ensure_all_started(hb)."

Restarting HyperBEAM

After the initial setup, you can restart HyperBEAM anytime with:

cd ~/HyperBEAM && ./start.sh

Or manually:

cd ~/HyperBEAM
export HB_STORE_PATH=/root/data
mkdir -p $HB_STORE_PATH
erl -pa _build/default/lib/*/ebin -eval "application:ensure_all_started(hb)."