HyperBEAM on Android

Run a full HyperBEAM decentralized computing node on your Android device.

Prerequisites

Storage: Minimum 2GB free space
RAM: 2GB+ recommended (HyperBEAM uses 200-400MB when running)
Internet: Stable WiFi or mobile data (initial download: ~500MB)

Required Software

Termux: Linux environment for Android

Download Options:

Recommended: F-Droid Termux (better compatibility, official builds)
Alternative: Google Play Termux

Check Your Device Compatibility

After installing Termux, open it and run:

uname -m        # Should show: aarch64
df -h $HOME     # Should show 2GB+ free

Installation Options

Option	Difficulty	Best For
Option 1: Automated	⭐ Easy	Users who want simplicity
Option 2: Quick Manual	⭐⭐ Medium	Users who want some control
Option 3: Detailed	⭐⭐⭐ Advanced	Users who want to learn

Option 1: Automated Installation

Perfect for: Users who want a one-command installation

Install Termux

Install Termux from F-Droid or Google Play
Open Termux and allow all permissions

Run Installation Script

Beta-1 (default)

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

Wait for Completion

The script will:

✓ Verify your device is compatible (ARM64)
✓ Install all Termux dependencies
✓ Set up Alpine Linux environment
✓ Compile HyperBEAM in Alpine
✓ Deploy to Termux and compile NIFs
✓ Start HyperBEAM automatically

Progress Indicators

You'll see these phases:

================================
HyperBEAM Android Installer
================================
Installing: v0.9-milestone-3-beta-1
================================

Then compilation in Alpine, followed by:

✓✓✓ ALPINE COMPILATION COMPLETE ✓✓✓
 
================================
Deploying to Termux...
================================
 
✓ b64fast compiled
✓ lmdb_nif compiled
✓ elmdb compiled
 
✓✓✓ INSTALLATION COMPLETE ✓✓✓

Option 2: Quick Manual Installation

Perfect for: Users who want to see what's happening

Termux Setup

Install Termux from F-Droid or Google Play, then run:

pkg update && pkg upgrade -y && \
pkg install proot-distro git wget -y && \
proot-distro install alpine && \
proot-distro login alpine

Alpine Compilation

Copy and paste this entire block:

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 && \
cd /tmp && wget https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3 && mv rebar3 /usr/local/bin/ && \
cd ~ && git clone https://github.com/permaweb/HyperBEAM.git && cd HyperBEAM && \
git checkout v0.9-milestone-3-beta-1 && \
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 && \
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 && \
rebar3 compile && \
cd ~ && tar czf /tmp/hyperbeam-compiled.tar.gz -h -C HyperBEAM _build priv 2>/dev/null; \
ls -lh /tmp/hyperbeam-compiled.tar.gz && echo "✓✓✓ ALPINE COMPILATION COMPLETE ✓✓✓" && exit

Wait for "✓✓✓ ALPINE COMPILATION COMPLETE ✓✓✓" - you'll automatically return to Termux.

Termux Deployment

Copy and paste this entire block:

cd ~
cp /data/data/com.termux/files/usr/var/lib/proot-distro/installed-rootfs/alpine/tmp/hyperbeam-compiled.tar.gz .
rm -rf HyperBEAM
mkdir -p HyperBEAM && cd HyperBEAM
tar xzf ../hyperbeam-compiled.tar.gz 2>/dev/null || true
pkg install -y -o Dpkg::Options::="--force-overwrite" erlang rust clang liblmdb liblmdb-static git
sed -i '1s|#!/system/bin/sh|#!/data/data/com.termux/files/usr/bin/sh|' $PREFIX/bin/erl
 
cd ~/HyperBEAM/_build/default/lib/b64fast
rm -rf priv ebin && mkdir -p priv ebin
erlc -o ebin src/*.erl
clang -fPIC -shared -o priv/b64fast.so c_src/b64fast.c -I$PREFIX/lib/erlang/usr/include
echo "✓ b64fast compiled"
 
cd ~/HyperBEAM/_build/default/lib/lmdb
rm -rf priv && mkdir -p priv
clang -fPIC -O2 -std=c99 -finline-functions -Wall -I$PREFIX/lib/erlang/usr/include -I$PREFIX/include -fPIC -shared -o priv/lmdb_nif.so c_src/lmdb_nif.c -llmdb
echo "✓ lmdb_nif compiled"
 
cd ~/HyperBEAM/_build/default/lib/elmdb
rm -rf priv && mkdir -p priv
clang -fPIC -O2 -std=c99 -finline-functions -Wall -I$PREFIX/lib/erlang/usr/include -Ic_src -DMDB_USE_ROBUST=0 -fPIC -shared -o priv/elmdb.so c_src/elmdb_nif.c c_src/mdb.c c_src/midl.c -lpthread
echo "✓ elmdb compiled"
 
cd ~/HyperBEAM
cat > start.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
cd ~/HyperBEAM
export HB_STORE_PATH=/data/data/com.termux/files/home/data
mkdir -p $HB_STORE_PATH
 
WLAN_IP=$(ifconfig 2>/dev/null | grep -A 1 wlan0 | grep inet | awk '{print $2}')
echo ""
echo "================================"
echo "HyperBEAM Starting"
echo "WiFi IP: $WLAN_IP"
echo "Local:   http://localhost:8734"
echo "Network: http://$WLAN_IP:8734"
echo "================================"
echo ""
 
erl -pa _build/default/lib/*/ebin -eval "application:ensure_all_started(hb)."
EOF
chmod +x start.sh
echo "✓✓✓ SETUP COMPLETE ✓✓✓"
./start.sh

Option 3: Detailed Step-by-Step

Perfect for: Users who want to understand every step and learn the architecture

Data Flow

[Alpine Linux] → Compile Everything → [Archive (.tar.gz)]
                                            ↓
                                     Copy to Termux
                                            ↓
[Termux] → Extract → Recompile NIFs → [Running HyperBEAM]

Phase 1: Setting Up Termux

Install and open Termux, then update packages:

pkg update
pkg upgrade -y
pkg install proot-distro git wget -y

Phase 2: Install Alpine Linux

proot-distro install alpine
proot-distro login alpine

Notice the prompt changes from $ to localhost:~#.

Phase 3: Install Build Dependencies in Alpine

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

Install rebar3:

cd /tmp
wget https://s3.amazonaws.com/rebar3/rebar3
chmod +x rebar3
mv rebar3 /usr/local/bin/

Phase 4: Clone and Patch HyperBEAM

cd ~
git clone https://github.com/permaweb/HyperBEAM.git
cd HyperBEAM
git checkout v0.9-milestone-3-beta-1

Apply ARM64 patches:

# Target architecture
sed -i 's/WAMR_BUILD_TARGET = X86_64/WAMR_BUILD_TARGET = AARCH64/g' Makefile
 
# Type compatibility fixes
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
 
# WASM API updates
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
 
# Exception handling
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

Phase 5: 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

Phase 6: Compile HyperBEAM

rebar3 compile

Phase 7: Package and Exit Alpine

cd ~
tar czf /tmp/hyperbeam-compiled.tar.gz -h -C HyperBEAM _build priv 2>&1 | grep -v "No such file" || true
exit

Phase 8: Deploy to Termux

cd ~
cp /data/data/com.termux/files/usr/var/lib/proot-distro/installed-rootfs/alpine/tmp/hyperbeam-compiled.tar.gz .
rm -rf HyperBEAM
mkdir -p HyperBEAM && cd HyperBEAM
tar xzf ../hyperbeam-compiled.tar.gz 2>/dev/null || true

Install runtime dependencies:

pkg install -y -o Dpkg::Options::="--force-overwrite" erlang rust clang liblmdb liblmdb-static git

Fix Erlang shebang:

sed -i '1s|#!/system/bin/sh|#!/data/data/com.termux/files/usr/bin/sh|' $PREFIX/bin/erl

Phase 9: Recompile NIFs

b64fast:

cd ~/HyperBEAM/_build/default/lib/b64fast
rm -rf priv ebin && mkdir -p priv ebin
erlc -o ebin src/*.erl
clang -fPIC -shared -o priv/b64fast.so c_src/b64fast.c -I$PREFIX/lib/erlang/usr/include

lmdb_nif:

cd ~/HyperBEAM/_build/default/lib/lmdb
rm -rf priv && mkdir -p priv
clang -fPIC -O2 -std=c99 -finline-functions -Wall -I$PREFIX/lib/erlang/usr/include -I$PREFIX/include -fPIC -shared -o priv/lmdb_nif.so c_src/lmdb_nif.c -llmdb

elmdb:

cd ~/HyperBEAM/_build/default/lib/elmdb
rm -rf priv && mkdir -p priv
clang -fPIC -O2 -std=c99 -finline-functions -Wall -I$PREFIX/lib/erlang/usr/include -Ic_src -DMDB_USE_ROBUST=0 -fPIC -shared -o priv/elmdb.so c_src/elmdb_nif.c c_src/mdb.c c_src/midl.c -lpthread

Phase 10: Create Startup Script

cd ~/HyperBEAM
cat > start.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
cd ~/HyperBEAM
export HB_STORE_PATH=/data/data/com.termux/files/home/data
mkdir -p $HB_STORE_PATH
 
WLAN_IP=$(ifconfig 2>/dev/null | grep -A 1 wlan0 | grep inet | awk '{print $2}')
echo ""
echo "================================"
echo "HyperBEAM Starting"
echo "WiFi IP: $WLAN_IP"
echo "Local:   http://localhost:8734"
echo "Network: http://$WLAN_IP:8734"
echo "================================"
echo ""
 
erl -pa _build/default/lib/*/ebin -eval "application:ensure_all_started(hb)."
EOF
chmod +x start.sh

Phase 11: Launch HyperBEAM

./start.sh

Accessing the Dashboard

Once HyperBEAM is running:

Local Access (on your phone):

http://localhost:8734

From Another Device (same network):

Then navigate to:

http://YOUR_PHONE_IP:8734

From the Internet (external access):

To expose your node to the internet, use Cloudflare Tunnel:

pkg install cloudflared
cloudflared tunnel -url http://localhost:8734

This gives you a public URL (e.g., https://xxx.trycloudflare.com) that forwards to your local HyperBEAM node. Works on both WiFi and mobile data.

Testing with WAO

You can test your HyperBEAM node programmatically using WAO:

test.js

import assert from "assert"
import { describe, it } from "node:test"
import { HB } from "wao"
 
describe("HyperBEAM Mobile", function () {
  it("should get the HyperBEAM node info", async () => {
    const hb = new HB({ url: "http://192.168.x.x:8734" }) // Your phone's IP
    const { out } = await hb.get({ path: "/~meta@1.0/info" })
    assert.equal(out.node, "HyperBEAM")
  })
})

Run with:

npm install wao
node --test test.js

Restarting HyperBEAM

After initial setup, restart anytime with:

cd ~/HyperBEAM && ./start.sh