DEV Community: Sulthon Zainul Habib

Run Real Docker on Android — No Root, No Tricks, Just QEMU

Sulthon Zainul Habib — Sun, 14 Jun 2026 04:00:44 +0000

Run Real Docker on Android — No Root, No Tricks, Just QEMU

You have an old Android phone in a drawer. It has 8 cores, 8–12 GB of RAM, and a fast SSD. It's collecting dust because the screen is cracked or the battery is tired. Meanwhile, you're paying $5/month for a 1 GB VPS to run the same Docker containers you could run on that phone for free.

The problem: Android doesn't run Docker. Docker needs the Linux kernel's cgroups, namespaces, and overlay filesystem. Android's kernel has those features compiled out for unprivileged apps, and there's no way to add them back without rooting the device.

The workaround everyone recommends is udocker or proot-distro. Those work for some things — pulling an image and chrooting into it — but they don't give you a real Docker daemon. You can't docker build. You can't run docker compose with networking. You can't use any tool that expects the Docker API to actually behave like Docker.

This tutorial shows the only path I've found that gives you a real Docker daemon running real containers on a non-rooted Android phone: run Debian in a QEMU virtual machine inside Termux. It's slow (10–25× overhead from software emulation), but it works — and it survives phone reboots.

By the end, you'll have:

✅ A Debian 12 VM running inside your phone
✅ Real dockerd + Docker Compose v2
✅ SSH access from your computer to the VM
✅ Auto-start on phone reboot (no manual intervention)
✅ A docker context so docker --context phone compose up works like it's local

Tested end-to-end on a Samsung Galaxy Note 10+ (SM-N975F, Exynos 9825, 12 GB RAM, Android 12, kernel 4.14.113) — not rooted.

What you'll need

Requirement	Why	Cost
An Android phone (ARM64, 6+ GB RAM)	The host. Must be ARM64 — x86 phones don't exist, but just in case.	Free (you have one)
A computer (macOS, Linux, or Windows with WSL)	To SSH in from. The phone is the server, your computer is the client.	Free
Both devices on the same Wi-Fi	For SSH. (You can do this remotely later with Tailscale, but that's out of scope here.)	Free
A USB-C cable (for the initial ADB setup, optional)	One-time setup. You can also do it entirely on-device if you prefer.	Free
~2 hours of patience	QEMU's first boot takes 20–30 minutes under software emulation. There's no way around this.	Priceless

Phone battery tip: If your phone has a "Protect Battery" or "Maximum 85%" setting (Samsung does), turn it on. The phone will be plugged in 24/7, and capping the charge doubles the battery's lifespan.

The architecture (mental model)

Here's what we're building:

┌────────────────────────────────────────────────────┐
│ Your Android phone (not rooted)                    │
│                                                    │
│  ┌──────────────────────────────────────────────┐  │
│  │ Termux (regular Android app)                 │  │
│  │  - QEMU binary (qemu-system-aarch64)         │  │
│  │  - The .qcow2 disk image                     │  │
│  │  - Boot scripts                              │  │
│  │  - sshd (port 8022) → your computer SSHes   │  │
│  │                       in here for management │  │
│  └─────────────────┬────────────────────────────┘  │
│                    │ launches                       │
│  ┌─────────────────▼────────────────────────────┐  │
│  │ QEMU VM (looks like real ARM64 hardware)     │  │
│  │  - Debian 12 (bookworm)                      │  │
│  │  - Real dockerd + Docker Compose v2          │  │
│  │  - sshd (port 22 → forwarded to 2222)        │  │
│  │  - systemd works (unlike in proot)           │  │
│  └──────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────┘
              ↑
              │ SSH from your computer
              │   ssh phone-vm      → port 2222 → Debian VM
              │   ssh phone-termux  → port 8022 → Termux shell

Two SSH targets. phone-vm drops you into Debian where Docker lives. phone-termux drops you into Termux itself (the Android-side layer), useful for troubleshooting the VM or restarting QEMU.

Why QEMU and not just proot-distro? Three reasons:

proot-distro has no systemd. No systemd means no systemctl enable docker. You'd have to manually start the daemon on every login.
proot-distro has no cgroups. No cgroups means no container resource control. Docker will refuse to start.
proot-distro has no real namespaces. No namespaces means no isolation. Containers would see each other.

QEMU gives us a real Linux kernel with all three. The cost is speed — every instruction is translated by QEMU's TCG (Tiny Code Generator) software emulator. That's why boot takes 20–30 minutes.

Step 1: Install Termux (the right way)

Do not install Termux from the Play Store. The Play Store version is frozen at v0.101 from 2020 and has a known security vulnerability. Install from F-Droid or the GitHub releases — but pick one and stick with it, because they're signature-incompatible with each other.

The cleanest option is F-Droid. Go to f-droid.org/en/packages/com.termux on your phone and install the APK.

While you're at it, also install Termux:Boot from F-Droid: f-droid.org/en/packages/com.termux.boot. This is what makes QEMU auto-start when the phone reboots. We'll configure it in Step 7.

After installing Termux:Boot, open it once. Just tap the icon, then close. This registers it with Android's BOOT_COMPLETED broadcast. If you skip this, the auto-start script in Step 7 won't fire.

Now open Termux. You should see a $ prompt. Run:

pkg update -y && pkg upgrade -y

This updates the package lists and upgrades everything. First run takes 1–2 minutes.

If it hangs on a mirror, run termux-change-repo, pick "Main repository", and select a mirror close to you. Indonesian users: linux.domainesia.com and mirror.nevacloud.com are in the Asia group.

Step 2: Set up SSH so you can work from your computer

Typing long commands on a phone keyboard is miserable. Let's fix that by setting up SSH from your computer.

2.1 Grant storage access (one-time)

In Termux:

termux-setup-storage

A dialog pops up on your phone asking for storage permission. Tap "Allow". This creates ~/storage/ symlinks to shared storage — not strictly needed for QEMU, but useful later if you want to back up your disk image.

2.2 Set a Termux password

passwd

Type a password twice. You'll need this for SSH (though we'll set up key-based auth in a moment).

2.3 Add your computer's SSH public key

On your computer, get your public key:

# macOS / Linux / WSL
cat ~/.ssh/id_ed25519.pub

If you don't have one, generate it:

ssh-keygen -t ed25519 -C "your-email@example.com"
# Press Enter through all the prompts

Copy the output (a string starting with ssh-ed25519 AAAA...).

Back in Termux on the phone:

mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo 'PASTE_YOUR_PUBLIC_KEY_HERE' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Replace PASTE_YOUR_PUBLIC_KEY_HERE with the key you copied. Keep the single quotes around it.

2.4 Start the SSH server

sshd

No output means it started. Termux's sshd listens on port 8022 (not the usual 22 — Android reserves 22 for the system).

2.5 Find your phone's IP

ip addr show wlan0 | grep inet

You'll see something like inet 192.168.0.9/24. Note the IP (without the /24).

2.6 Set up SSH config on your computer

On your computer, edit ~/.ssh/config and add:

Host phone-termux
  HostName 192.168.0.9
  Port 8022
  User u0_a892
  IdentityFile ~/.ssh/id_ed25519
  ControlMaster auto
  ControlPath ~/.ssh/controlmasters/%r@%h:%p
  ControlPersist 10m

Replace 192.168.0.9 with your phone's IP. The User looks weird (u0_a892) — that's Termux's Android UID, which is also its Linux username. The number after u0_a varies per install; to find yours, run whoami in Termux.

Create the controlmasters directory (needed for connection multiplexing, which makes repeated SSH commands nearly instant):

mkdir -p ~/.ssh/controlmasters

Now test:

ssh phone-termux whoami
# → u0_a892

If that works, you're set. From now on, you can run commands in Termux from the comfort of your computer's keyboard.

Step 3: Download Debian and build the cloud-init seed

Back in Termux (either on the phone directly, or via ssh phone-termux from your computer):

3.1 Install QEMU and friends

pkg install -y qemu-system-aarch64 openssh curl wget genisoimage

This installs:

qemu-system-aarch64 — the emulator itself (~400 MB, includes UEFI firmware)
openssh — for the SSH server we already started
curl / wget — for downloading the Debian image
genisoimage — for building the cloud-init seed ISO

3.2 Acquire a wake lock (CRITICAL — do not skip)

termux-wake-lock

This tells Android "don't kill this process when the screen is off." Without it, Android's Doze mode will murder QEMU 5–10 minutes after your screen goes dark, and your VM will die mid-boot. You only need to run this once per Termux session — but it's easiest to put it in your boot script (Step 7) so it's always active.

3.3 Download the Debian cloud image

mkdir -p ~/qemu-vm && cd ~/qemu-vm
wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-arm64.qcow2

This is a 500 MB qcow2 file — Debian's official "generic cloud" image for ARM64. It's built for exactly this use case (cloud VMs), so it has cloud-init pre-installed and no desktop environment.

3.4 Resize the disk

qemu-img resize debian-12-genericcloud-arm64.qcow2 16G

The downloaded image is ~2 GB (logical size). We resize to 16 GB so there's room for Docker, containers, and pulled images. The qcow2 format only allocates disk space as it's used, so this won't actually consume 16 GB on your phone immediately.

Rename it for clarity:

mv debian-12-genericcloud-arm64.qcow2 debian-12-arm64.qcow2

3.5 Create the cloud-init seed

Cloud-init is how we configure the VM on first boot: set hostname, create users, add SSH keys. It reads from a "seed" — in our case, a small ISO file attached as a virtual CD-ROM.

Create user-data:

cat > user-data <<'EOF'
#cloud-config
hostname: docker-phone
users:
  - name: sulthon
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    ssh_authorized_keys:
      - ssh-ed25519 AAAA...YOUR_KEY_HERE... your-email@example.com
ssh_pwauth: false
disable_root: false
package_update: true
packages:
  - qemu-guest-agent
  - ca-certificates
  - curl
growpart:
  mode: auto
  devices: ['/']
  ignore_growroot: false
EOF

Edit the SSH key to match your actual ~/.ssh/id_ed25519.pub from Step 2.3. This is what lets you SSH into the Debian VM later. Change the username sulthon to whatever you like — just remember it for later steps.

Create meta-data:

cat > meta-data <<'EOF'
instance-id: docker-phone-001
local-hostname: docker-phone
EOF

Build the seed ISO:

genisoimage -output seed.iso -volid cidata -joliet -rock user-data meta-data

The -volid cidata is critical — cloud-init looks for a volume labeled exactly cidata (or CIDATA). If you get this wrong, cloud-init won't run and you'll have no users, no SSH keys, no nothing.

Step 4: The QEMU launcher script

This is the script that boots Debian. There's a lot going on, so let's break it down carefully.

Copy the UEFI firmware variables first (one-time):

cp $PREFIX/share/qemu/edk2-aarch64-vars.fd ~/qemu-vm/edk2-vars.fd
truncate -s 64M ~/qemu-vm/edk2-vars.fd

This creates a writable copy of the UEFI NVRAM (the edk2-vars.fd file). The truncate grows it to 64 MB for safety margin. Don't skip this — without the vars file, UEFI state won't persist across VM reboots, and your VM won't boot a second time.

Now create the launcher script. This is the heart of the whole setup:

cat > ~/boot-debian-mon.sh <<'EOF'
#!/data/data/com.termux/files/usr/bin/bash
set +e

VM_DIR="/data/data/com.termux/files/home/qemu-vm"
CODE="/data/data/com.termux/files/usr/share/qemu/edk2-aarch64-code.fd"
VARS="$VM_DIR/edk2-vars.fd"
IMG="$VM_DIR/debian-12-arm64.qcow2"
SEED="$VM_DIR/seed.iso"
MONSOCK="$VM_DIR/mon.sock"
SERIALSOCK="$VM_DIR/serial.sock"
LOG="$VM_DIR/debian-boot.log"

pkill -9 -f qemu-system-aarch64 2>/dev/null
sleep 2
rm -f $MONSOCK $SERIALSOCK

setsid qemu-system-aarch64 \
  -name docker-phone \
  -machine virt,gic-version=3 \
  -cpu max,aarch64=on,pmu=on \
  -smp 6 \
  -m 6144 \
  -accel tcg,thread=multi,tb-size=512 \
  -nodefaults \
  -chardev socket,id=mon0,path=$MONSOCK,server=on,wait=off \
  -mon chardev=mon0,mode=readline \
  -chardev socket,id=ser0,path=$SERIALSOCK,server=on,wait=off,logfile=$LOG \
  -serial chardev:ser0 \
  -display none \
  -drive if=pflash,format=raw,readonly=on,file=$CODE \
  -drive if=pflash,format=raw,file=$VARS \
  -drive file=$IMG,if=virtio,format=qcow2,cache=writeback \
  -drive file=$SEED,if=virtio,format=raw,readonly=on \
  -netdev user,id=net0,hostfwd=tcp::2222-:22,hostfwd=tcp::8080-:80,hostfwd=tcp::9000-:9000 \
  -device virtio-net-pci,netdev=net0 \
  -device virtio-rng-pci \
  -rtc base=utc \
  > $LOG 2>&1 &

disown
sleep 3
echo "QEMU PID: $(pgrep -f qemu-system-aarch64 | head -1)"
echo "Monitor socket: $MONSOCK"
echo "Serial socket: $SERIALSOCK"
echo "Log: $LOG"
EOF
chmod +x ~/boot-debian-mon.sh

What each line does

The machine definition:

-machine virt,gic-version=3 — QEMU's "virt" machine, which is designed for VMs (not emulating any specific real phone). GIC version 3 is the modern ARM interrupt controller.
-cpu max,aarch64=on,pmu=on — expose the maximum CPU feature set to the guest, including hardware crypto (ARMv8 crypto extensions). This makes TLS handshakes faster.
-smp 6 — give the VM 6 CPUs. Adjust based on your phone (8-core phones typically have a "big.LITTLE" layout; 6 leaves 2 for Android).
-m 6144 — give the VM 6 GB of RAM. Leave the rest for Android.

The emulator:

-accel tcg,thread=multi,tb-size=512 — use TCG (software emulation) with multi-threading and a 512 MB translation block cache. This is the best TCG config for sustained throughput.

Storage:

The first -drive if=pflash,readonly=on is the UEFI firmware code (read-only).
The second -drive if=pflash is the UEFI vars file (writable — this is why we made the copy earlier).
The -drive file=$IMG,if=virtio is your Debian disk.
The -drive file=$SEED,if=virtio,readonly=on is the cloud-init seed ISO.

Networking:

-netdev user,id=net0,hostfwd=tcp::2222-:22,... — user-mode networking with port forwarding. Anything connecting to port 2222 on the phone gets forwarded to port 22 inside the VM. We also forward 8080 and 9000 for web apps you might run later.

Process management (the tricky part):

setsid — detaches QEMU from Termux's session leader. Without this, when SSH disconnects, Android kills the whole process tree.
disown — removes QEMU from the shell's job table.
Together, these mean QEMU survives SSH disconnects. Do not use plain nohup — it's not enough on Termux.

Step 5: First boot (patience required)

Launch the VM:

bash ~/boot-debian-mon.sh

You should see:

QEMU PID: 12345
Monitor socket: /data/data/com.termux/files/home/qemu-vm/mon.sock
Serial socket: /data/data/com.termux/files/home/qemu-vm/serial.sock
Log: /data/data/com.termux/files/home/qemu-vm/debian-boot.log

Now wait. 20–30 minutes. No, that's not a typo. TCG software emulation is brutally slow.

You can watch the boot log from another SSH session:

# From your computer:
ssh phone-termux tail -f ~/qemu-vm/debian-boot.log

When you see something like:

[ OK ] Started OpenSSH server

…and the log stops growing, the VM is ready. Verify from your computer:

ssh -p 2222 sulthon@192.168.0.9 hostname
# → docker-phone

(Reminder: change sulthon to whatever username you put in user-data.)

If that works, add a second SSH config entry on your computer for the VM:

# append to ~/.ssh/config
Host phone-vm
  HostName 192.168.0.9
  Port 2222
  User sulthon
  IdentityFile ~/.ssh/id_ed25519
  ControlMaster auto
  ControlPath ~/.ssh/controlmasters/%r@%h:%p
  ControlPersist 10m

Now ssh phone-vm Just Works.

Step 6: Install Docker inside the VM

SSH into the VM and install everything:

ssh phone-vm

6.1 Install Docker

sudo apt-get update
sudo apt-get install -y docker.io

The docker.io package is Debian's official Docker package (version 20.10.24 as of this writing). It's slightly older than Docker CE, but it's in the main Debian repos and works perfectly. Expect this to take 25–35 minutes under TCG. Go get coffee.

6.2 Install Docker Compose v2

sudo mkdir -p /usr/libexec/docker/cli-plugins
sudo curl -fSL -o /usr/libexec/docker/cli-plugins/docker-compose \
  https://github.com/docker/compose/releases/download/v2.29.7/docker-compose-linux-aarch64
sudo chmod +x /usr/libexec/docker/cli-plugins/docker-compose

We download the binary directly because the docker-compose-v2 Debian package isn't in bookworm. Placing it in cli-plugins/ means docker compose (with a space, not a hyphen) works.

6.3 Let your user run Docker without sudo

sudo usermod -aG docker $USER

You'll need to log out and back in for this to take effect:

exit  # back to your computer
ssh phone-vm  # back in

6.4 Configure Docker for the slow VM

This step is critical. Without it, docker pull will fail with TLS handshake timeout because TCG is too slow for Docker's default timeouts.

sudo tee /etc/docker/daemon.json >/dev/null <<'EOF'
{
  "max-concurrent-downloads": 1,
  "max-download-attempts": 5,
  "dns": ["8.8.8.8", "1.1.1.1"],
  "ip6tables": false,
  "ipv6": false
}
EOF
sudo systemctl restart docker

What each setting does:

max-concurrent-downloads: 1 — only download one layer at a time. Parallel downloads overwhelm TCG and time out.
max-download-attempts: 5 — retry failed layers.
dns: [8.8.8.8, 1.1.1.1] — Docker's embedded DNS sometimes can't resolve registry hostnames under TCG; this forces public DNS.
ip6tables: false and ipv6: false — disable IPv6. TCG's IPv6 stack is even slower than IPv4, and many container images misbehave over IPv6 anyway.

6.5 Add ZRAM swap (recommended)

ZRAM is compressed swap in RAM. Under TCG, real disk I/O is brutal, so having compressed memory swap gives you a safety net for memory spikes.

sudo apt-get install -y zram-tools
echo -e "ALGO=zstd\nPERCENT=75\nPRIORITY=100" | sudo tee /etc/default/zramswap
sudo systemctl restart zramswap

This gives you ~4.3 GB of zstd-compressed swap (assuming 6 GB of VM RAM). zstd compresses roughly 3:1 on typical workload data, so it's like having ~13 GB of effective memory.

6.6 Verify

sudo docker run --rm hello-world

Expect:

Unable to find image 'hello-world:latest' locally
... pulling layers ...

Hello from Docker!
This message shows that your installation appears to be working correctly.

The pull takes ~75 seconds (5 KB image, but TCG). The run takes ~15 seconds after that. If you see "Hello from Docker!", you're done with the hard part.

Step 7: Make it survive phone reboots

If the phone reboots (battery died, OS update, accidental power button press), you want QEMU to come back automatically. Termux:Boot handles this.

7.1 Create the Termux:Boot scripts

Back in Termux (via ssh phone-termux):

mkdir -p ~/.termux/boot

Create the first script — auto-start QEMU:

cat > ~/.termux/boot/01-start-vm.sh <<'EOF'
#!/data/data/com.termux/files/usr/bin/bash
sleep 15
termux-wake-lock 2>/dev/null
pkill -9 -f qemu-system-aarch64 2>/dev/null
sleep 2
bash ~/boot-debian-mon.sh
EOF
chmod +x ~/.termux/boot/01-start-vm.sh

The sleep 15 gives Android time to finish booting before we start hammering the CPU. The pkill is a safety net in case QEMU somehow came back half-alive.

Create the second script — auto-start Termux sshd:

cat > ~/.termux/boot/02-start-sshd.sh <<'EOF'
#!/data/data/com.termux/files/usr/bin/bash
sleep 5
sshd
EOF
chmod +x ~/.termux/boot/02-start-sshd.sh

7.2 Verify the scripts are registered

If you've opened Termux:Boot once (Step 1), Termux automatically picks up scripts in ~/.termux/boot/ and runs them at boot. To confirm:

ls -la ~/.termux/boot/
# Should show:
# -rwx------ 1 u0_a892 u0_a892 ... 01-start-vm.sh
# -rwx------ 1 u0_a892 u0_a892 ... 02-start-sshd.sh

7.3 Test it (optional but recommended)

Reboot your phone the normal Android way. After it restarts:

Wait ~5 minutes for Android to fully boot.
Wait another ~20 minutes for QEMU to cold-boot Debian.
From your computer: ssh phone-vm hostname should return docker-phone.

If that works, your phone is a self-healing Docker host. You can unplug it, plug it back in, reboot it, whatever — it'll come back.

Step 8: Use it from your computer like it's local

Typing ssh phone-vm docker run ... for everything gets old. Let's make the phone feel like a local Docker host.

8.1 Create a Docker context

On your computer:

docker context create phone --docker "host=ssh://sulthon@192.168.0.9:2222"

(Change sulthon to your VM username, and 192.168.0.9 to your phone's IP from Step 2.5.)

Docker's SSH integration bypasses your ~/.ssh/config aliases, so you need to add the phone to ~/.ssh/known_hosts explicitly:

ssh-keyscan -p 2222 -t ed25519 192.168.0.9 >> ~/.ssh/known_hosts

Verify the plumbing works:

docker --context phone ps
# CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES
# (empty list is fine — you haven't run anything yet)

docker --context phone run --rm hello-world
# → Hello from Docker!

If docker --context phone ps returns an empty table, you're connected. If it times out, the phone is offline, the IP changed, or QEMU died — re-check ssh phone-vm hostname works first.

8.2 The DOCKER_HOST gotcha (Mac users especially)

If you have Colima, Docker Desktop, or OrbStack installed on your Mac, you'll see this warning:

Warning: DOCKER_HOST environment variable overrides the active context.

This is normal. The --context phone flag does override DOCKER_HOST for that one command — the warning is just noise. Two ways to silence it:

Option A (recommended): Always pass --context phone explicitly. The warning appears but the command works.

Option B: Temporarily unset DOCKER_HOST for the session:

unset DOCKER_HOST
docker context use phone     # now active
docker compose ps            # no --context needed

8.3 Test with a real compose stack

Create a file on your computer called docker-compose.yml:

services:
  whoami:
    image: traefik/whoami
    ports:
      - "8080:80"

Save it anywhere — your desktop, home directory, wherever. The file lives on your Mac; the container will run on the phone.

Now bring it up:

cd /directory/where/you/saved/it
docker --context phone compose up -d

Expect this to take 5–15 minutes the first time. TCG emulation makes image pulls brutally slow. You'll see Pulling fs sit there for minutes at a time. That's normal — don't Ctrl-C.

When it finishes:

docker --context phone compose ps
# NAME                IMAGE           STATUS         PORTS
# whoami-whoami-1     traefik/whoami  Up 30 seconds  0.0.0.0:8080->80/tcp

# Test it (port 8080 is forwarded from the phone to your Mac in the QEMU launcher):
curl http://192.168.0.9:8080
# → displays the whoami container's response

Bring it down when done:

docker --context phone compose down

8.4 Common ways compose fails (and the fix)

"Cannot connect to the Docker daemon" / SSH timeout / "command exited with status 255"
The most common cause — your computer and the phone aren't on the same network. Verify Layer-2/3 reachability first:

# 1. Ping the phone (Mac/Linux)
ping -c 3 192.168.0.9
# If 100% packet loss → network problem, not Docker

# 2. If ping works, test the SSH port
nc -zv 192.168.0.9 2222
# If "Connection refused" or timeout → QEMU died, SSH isn't listening
# If "succeeded" → network is fine, Docker context should work

Network causes (in order of likelihood): different Wi-Fi, AP isolation enabled on router, guest network blocking client-to-client traffic, VPN on Mac, phone asleep and dropped off Wi-Fi.

Fix network: put both devices on the same SSID, disable AP isolation in router settings, turn off Mac VPN, wake the phone screen.

If network is fine but SSH still times out: QEMU died inside the phone. Restart it via phone-vm-start --wait if you have the helper scripts, or reboot the phone entirely and wait 20–30 min for TCG boot. Verify with ssh phone-vm hostname — should return docker-phone.

"pull access denied" or "TLS handshake timeout"
Image pull timed out. Two causes: (1) you skipped the /etc/docker/daemon.json config from Step 6.4, or (2) the image is large and TCG is just slow. Re-check the daemon config. For large images (>500 MB), expect 20+ minute pulls.

"no configuration file provided: not found"
You're not in a directory with a docker-compose.yml. The compose file lives on your Mac, not the phone. cd into the directory containing your docker-compose.yml first.

Volume mount path doesn't exist
If your compose file has volumes: - ./data:/data, the ./data path resolves on the phone, not your Mac. The phone has no ./data directory. Use absolute paths inside the VM: volumes: - /home/sulthon/myapp/data:/data, and create the directory on the phone first via ssh phone-vm mkdir -p /home/sulthon/myapp/data.

Port conflict on 8080
The QEMU launcher in Step 4 already forwards port 8080 from phone → Mac. If a container inside the VM also tries to bind 8080, it conflicts with the QEMU-level forward. Use a different port (8081, 3000, etc.) in your compose file.

8.5 (Optional) Make the phone the default context

unset DOCKER_HOST          # required — otherwise DOCKER_HOST wins
docker context use phone
docker ps                  # now hits the phone

I don't recommend this. It's surprising when you forget and accidentally build an image on the phone over Wi-Fi. Keep `--context phone` explicit.

Troubleshooting: the 5 things most likely to break

1. "QEMU died after my SSH disconnected"

You forgot setsid and disown in the launcher script, or you launched it manually with nohup (which is not enough). Use the script from Step 4 as-is. Never launch QEMU directly with qemu-system-aarch64 ... — always go through the script.

2. "Docker pull fails with TLS handshake timeout"

You skipped the /etc/docker/daemon.json config in Step 6.4, or the config is malformed. Verify:

ssh phone-vm cat /etc/docker/daemon.json
ssh phone-vm sudo systemctl restart docker

Then retry. If it still fails, check that max-concurrent-downloads is set to 1 and not to a higher number.

3. "Termux sshd isn't running after reboot"

Either you forgot to open Termux:Boot once (Step 1), or the ~/.termux/boot/02-start-sshd.sh script isn't executable. Fix:

ssh phone-termux chmod +x ~/.termux/boot/02-start-sshd.sh

And open the Termux:Boot app icon on your phone, just to be safe.

4. "The VM boots to a UEFI shell instead of Debian"

This is a known issue with Debian cloud images on some QEMU versions. The fix is to write a startup.nsh script to the EFI System Partition. This is fiddly — you need to boot Alpine from ISO with your qcow2 as a data disk, mount the ESP, and write the file. I'll cover this in detail in a follow-up post. For now, if this happens, leave a comment on this post and I'll walk you through it.

5. "Everything worked yesterday, but today it's broken"

You hit Android's phantom process killer. Modern Android (12+) kills background processes that use too much CPU. The fixes:

Keep the phone plugged in. Battery-saver mode is brutal.
Keep termux-wake-lock active. Run ssh phone-termux termux-wake-lock to verify.
Disable Samsung Game Tuning / GOS if you're on a Samsung device. It throttles sustained CPU workloads. Settings → Gaming Services → Game Booster → Maximum Performance (or similar).
Check Settings → Battery → Termux → Unrestricted. This should be automatic via Termux:Boot, but if it's not, set it manually.

What to do next

You now have a working Docker host that costs $0/month and fits in your pocket. Some ideas:

Run a personal Traefik + whoami demo to verify compose works end-to-end. Port 8080 is already forwarded.
Self-host Postgres for local dev. Use a volume so data survives container restarts.
Run Watchtower to keep your containers auto-updated.
Add Tailscale to the VM so you can reach your Docker host from anywhere — not just your Wi-Fi.
Build images on the phone. docker build works fine (slowly) under TCG. Useful for iterating without hitting your laptop's battery.

The phone-as-server dream is real. It just takes QEMU to get there. Enjoy your free Docker host.

If you find bugs in this tutorial, please leave a comment — I'll keep it updated. Happy hacking.

I Built an AI Code Reviewer That Runs on 240 Repos — And a Cron System That Keeps It Alive

Sulthon Zainul Habib — Thu, 11 Jun 2026 16:38:53 +0000

I got tired of reviewing my own pull requests at 2 AM. So I built a GitHub Action that does it for me. Then I built a cron system to keep that action alive. Then I added 55 more AI agent jobs to that cron system because, honestly, I couldn't stop.

Here's what's actually running, what it costs, and what I'm building toward.

The Code Reviewer That Started It All

The core product: a GitHub Action called sulthonzh/code-reviewer that lives at github.com/sulthonzh/code-reviewer. Every time someone opens a PR on any of my repos, five jobs fire off in sequence:

Secret scan — checks the diff for leaked API keys, passwords, private keys
AI review — sends the diff to Z.AI's GLM model, gets back security/quality/style feedback
Quality gate — runs linting, type checks, test thresholds
Auto-merge — if the AI approved AND quality passed, merges automatically
Auto-release — on push to main, cuts a GitHub release with changelog

Here's the real workflow. This runs on 240+ repos right now:

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review]
  push:
    branches: [main]

concurrency:
  group: review-${{ github.ref }}
  cancel-in-progress: true

permissions:
  pull-requests: write
  contents: write
  checks: write
  statuses: write

env:
  ZAI_BASE_URL: "https://api.z.ai/api/coding/paas/v4/"

jobs:
  secret-scan:
    name: "🔒 Secret Scan"
    runs-on: ubuntu-latest
    outputs:
      secrets_found: ${{ steps.scan.outputs.found }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Scan diff for secrets
        id: scan
        uses: sulthonzh/code-reviewer@main
        with:
          command: secret-scan
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Block if secrets found
        if: steps.scan.outputs.found == 'true'
        run: |
          echo "::error::Found potential secret(s) in the diff. Remove before merging."
          exit 1

  ai-review:
    name: "🤖 AI Review"
    runs-on: ubuntu-latest
    needs: secret-scan
    outputs:
      approved: ${{ steps.review.outputs.approved }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Detect project context
        id: context
        uses: sulthonzh/code-reviewer@main
        with:
          command: detect-context
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Route model by diff size
        id: model
        run: |
          DIFF_LINES=$(git diff origin/main...HEAD 2>/dev/null | wc -l || echo 0)
          if [ "$DIFF_LINES" -gt 500 ]; then
            echo "model=glm-5.1" >> "$GITHUB_OUTPUT"
          else
            echo "model=glm-4.5" >> "$GITHUB_OUTPUT"
          fi
      - name: Run AI review
        id: review
        uses: sulthonzh/code-reviewer@main
        with:
          command: ai-review
          model: ${{ steps.model.outputs.model }}
          project-type: ${{ steps.context.outputs.project_type }}
          zai-api-key: ${{ secrets.ZAI_API_KEY }}
          zai-base-url: ${{ env.ZAI_BASE_URL }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

  quality-gate:
    name: "✅ Quality Gate"
    runs-on: ubuntu-latest
    needs: [secret-scan, ai-review]
    outputs:
      passed: ${{ steps.gate.outputs.passed }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Run quality checks
        id: gate
        uses: sulthonzh/code-reviewer@main
        with:
          command: quality-gate
          github-token: ${{ secrets.GITHUB_TOKEN }}

  auto-merge:
    name: "🔀 Auto-Merge"
    runs-on: ubuntu-latest
    needs: [ai-review, quality-gate]
    if: >-
      needs.ai-review.outputs.approved == 'true' &&
      needs.quality-gate.outputs.passed == 'true' &&
      github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v6
      - name: Approve and merge
        uses: sulthonzh/code-reviewer@main
        with:
          command: auto-merge
          github-token: ${{ secrets.GITHUB_TOKEN }}

  auto-release:
    name: "📦 Auto-Release"
    runs-on: ubuntu-latest
    if: >-
      github.event_name == 'push' &&
      github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Detect and release
        uses: sulthonzh/code-reviewer@main
        with:
          command: auto-release
          github-token: ${{ secrets.GITHUB_TOKEN }}

The model routing bit

Small PRs (under 500 lines diff) hit glm-4.5. Bigger ones get glm-5.1. This isn't arbitrary. The larger model costs more per token but handles cross-file reasoning better. Most PRs are under 500 lines, so the cheap model handles 90% of traffic.

The API endpoint is Z.AI (from 智谱AI, a Chinese AI company). Their GLM models are OpenAI-compatible, so the integration was just pointing the OpenAI SDK at a different base URL. No wrappers, no adapters.

What it actually costs

Per review:
  Z.AI API call:       ~$0.002
  GitHub Actions:      ~$0.003 (free tier mostly covers this)
  Total:               ~$0.006 per review

I'm spending roughly $3-5/month on API calls across all repos. That's less than a coffee.

The Secret Scanning Story

Here's where it got interesting. Before I built the secret-scan job, I ran a manual sweep across 240 public repos. Found 9 repos with real leaked credentials in git history:

AWS access keys
MySQL root passwords
RSA private keys
Hardcoded JWT secrets

Cleaning them wasn't just git rm. The secrets were in history. I used git filter-repo to rewrite the affected repos, rotated every compromised credential, and added the secret-scan job to the workflow to prevent recurrence.

That job alone has caught three attempted credential pushes in the last month. Worth the entire build.

The Babysitter: OpenClaw Cron Fleet

The code reviewer runs fine on its own. But I kept adding things. A marketing supervisor that publishes blog posts to Dev.to (10 articles so far). A deployment supervisor that ships to Vercel free tier. An IDX stock screener that runs 20+ intraday scans on the Indonesian exchange. A wealth builder that scaffolds SaaS products.

All of these are AI agent jobs running on cron schedules through a system I call OpenClaw.

Current state: 56 jobs, monitored by a guardian process that scans every few hours.

Guardian cycle 2026-06-11 04:48 WIB:
  - 56 jobs scanned
  - 0 with consecutiveErrors >= 2
  - 1 single-error transient (wealth-builder timeout)
  - No actions taken

The guardian doesn't just watch. It has rules:

1 consecutive error: ignore, probably transient
2 consecutive errors: monitor, create incident ticket
5+ consecutive errors: auto-heal (restart job, switch model, increase timeout)

This actually worked last week. The marketing supervisor started failing because the GLM model hit rate limits. The guardian detected 2+ consecutive errors, switched the model to glm-4.5-air (lighter, faster), bumped the timeout from 2700s to 3600s. Resolved without me touching anything.

The circuit breaker pattern

Each agent job wraps its API calls in a circuit breaker. Here's the pattern from my IDX screener:

class HealthRecord:
    """Track health of a single component."""

    def record_failure(self):
        self.consecutive_failures += 1
        self.consecutive_successes = 0
        if self.consecutive_failures >= 5:
            self.circuit_open = True
            self.circuit_opened_at = time.time()

    def record_success(self, duration_ms: float = 0):
        self.consecutive_successes += 1
        self.consecutive_failures = 0
        if self.consecutive_successes >= 3:
            self.circuit_open = False  # auto-close after 3 wins

    @property
    def is_healthy(self):
        if not self.circuit_open:
            return True
        # Half-open: try again after 5 min cooldown
        if time.time() - self.circuit_opened_at > 300:
            return True
        return False

5 failures in a row opens the circuit. 3 successes in a row closes it. 5-minute half-open cooldown lets it retry. This runs in production and has prevented cascading failures during API outages.

The Architecture (What Exists vs. What's Next)

Here's the honest map:

┌─────────────────────────────────────────────────────┐
│                   WHAT'S LIVE                         │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │ AI Code       │  │ OpenClaw     │  │ Guardian   │ │
│  │ Reviewer      │  │ Cron Fleet   │  │ Monitor    │ │
│  │ (240 repos)   │  │ (56 jobs)    │  │ (auto-     │ │
│  │               │  │              │  │  heal)     │ │
│  └──────────────┘  └──────────────┘  └───────────┘ │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ Marketing    │  │ Secret Scan  │                  │
│  │ Supervisor   │  │ (9 repos     │                  │
│  │ (10 posts)   │  │  cleaned)    │                  │
│  └──────────────┘  └──────────────┘                  │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│               WHAT I'M BUILDING TOWARD                │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │ Wallet       │  │ Cloning      │  │ Revenue    │ │
│  │ Module       │  │ Engine       │  │ Engine     │ │
│  │ (Stripe)     │  │ (multi-cloud)│  │ (SaaS)     │ │
│  └──────────────┘  └──────────────┘  └───────────┘ │
└─────────────────────────────────────────────────────┘

The bottom row doesn't exist yet. I'm sharing the architecture because it's where this is heading, but I want to be clear about the boundary.

What's next (honest roadmap)

Near term (building now):

Wallet module with Stripe integration for the code reviewer SaaS
Better incident response (currently the guardian can restart jobs and switch models; adding credential rotation automation)

Medium term (designing):

Multi-cloud cloning (snapshot state, deploy to new provider)
Revenue engine (paid tiers for the code reviewer, API marketplace listing)

Far term (thinking about):

Swarm coordination between cloned instances
Knowledge base that actually learns from review patterns over time (currently static prompts)

Why Z.AI and Not OpenAI

Three reasons:

Cost. GLM-4.5 costs roughly 10x less per token than GPT-4o for code review quality that's comparable for the patterns I care about (security, style, common bugs).
Latency. The API responds in under 2 seconds for most diffs. OpenAI was averaging 4-5 seconds.
OpenAI-compatible. Zero code changes to the OpenAI SDK. Just swap baseURL and apiKey. I could switch back to OpenAI (or add Claude, or Gemini) in about 10 minutes if Z.AI went down.

That last point matters. Vendor lock-in is the enemy of resilience.

Try It

Drop this into .github/workflows/ai-review.yml on any repo:

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: sulthonzh/code-reviewer@main
        with:
          command: ai-review
          zai-api-key: ${{ secrets.ZAI_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

You'll need a Z.AI API key from open.z.ai. The free tier covers a few hundred reviews per month.

The code is open source at github.com/sulthonzh/code-reviewer.

I Stopped Switching Git Branches — And Started Using Worktrees Instead

Sulthon Zainul Habib — Fri, 29 May 2026 11:16:44 +0000

I used to be a git stash person. You know the dance — you're halfway through a feature, someone pings you about a bug on main, and suddenly you're stashing, switching, fixing, switching back, popping, and praying the stash applies cleanly.

Then I discovered git worktrees. And then I discovered why nobody uses them — the UX is awful.

The Problem With Branch Switching

Here's a typical afternoon for me:

Working on feature/payment-flow in VS Code
Production bug comes in, needs a hotfix on main
Stash changes (12 files modified)
git checkout main
Apply hotfix, test, push
git checkout feature/payment-flow
git stash pop — conflict. Of course.
Spend 20 minutes resolving stash conflicts that have nothing to do with my actual work

Multiply this by 3-4 context switches a day and I'm losing an hour just to git gymnastics.

Git Worktrees: The Concept

Git worktrees let you have multiple checkouts of the same repo simultaneously. Each worktree is a directory with its own working tree and branch, but they all share the same .git database.

# Instead of switching branches, you just cd to a different directory
cd ~/projects/myapp              # main branch
cd ~/projects/worktrees/bugfix   # bugfix branch, fully checked out

No stashing. No switching. Your IDE stays open. Your node_modules are intact. Your brain stays in context.

The problem? The commands are verbose and there's no automation:

git worktree add ../worktrees/feature-x feature-x
cd ../worktrees/feature-x
npm install              # gotta reinstall deps
cp ../../myapp/.env .    # gotta copy env files manually
# oh and the directory structure is ugly

Every single time, same repetitive steps. And cleaning up? git worktree remove ../worktrees/feature-x — if you even remember where you put it.

So I Built worktree-manager

I wanted worktrees to be as easy as switching branches. So I built worktree-manager — a zero-config CLI that handles the tedious parts.

npm install -g worktree-manager

One command to create a worktree and set it up:

wtm add feature/payment-flow

That's it. Under the hood, it:

Creates the worktree at ../worktrees/feature/payment-flow
Detects your project type (Node.js, Python, Go, Rust)
Copies dependency files (package.json, lock files)
Copies environment files (.env, .env.local, .env.example)
Runs setup commands (npm install, pip install, etc.)

The path generation is smart — it strips prefixes like feature/ or bugfix/ and nests cleanly. You end up with a structure like:

projects/
├── myapp/                      # main
└── worktrees/
    ├── payment-flow/           # feature/payment-flow
    ├── hotfix-login-bug/       # hotfix/login-bug
    └── refactor-api/           # refactor/api

The Commands That Actually Matter

Listing what you have

wtm list

Shows all your worktrees with branch names and paths. The --verbose flag adds commit hashes and last modified times. Honestly I use this more than I should because I forget what I have open.

Cleaning up

This is the one that sold me. git worktree doesn't have a great cleanup story. Worktrees accumulate, directories go stale, and you end up with zombie checkouts.

wtm clean

It scans for stale worktrees (ones where the branch was deleted but the directory still exists) and removes them. One command instead of manually hunting directories.

Removing a specific worktree

wtm remove feature/payment-flow
# or with the branch too:
wtm remove --with-branch feature/old-experiment

Jumping between worktrees

wtm cd feature/payment-flow

This one's simple but I use it constantly. Instead of remembering the full path, just reference the branch name.

How the Project Detection Works

This was the part I spent the most time on, because it's what separates "yet another wrapper" from something that actually saves time.

The detector checks for marker files in order:

// Node.js: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
// Python: requirements.txt, setup.py, pyproject.toml, poetry.lock
// Go: go.mod, go.sum
// Rust: Cargo.toml, Cargo.lock

For each detected project type, it knows which env files to copy and which setup commands to run. Node.js gets npm ci (or npm install if no lock file). Python gets pip install -r requirements.txt. You get the idea.

If you don't want the auto-setup (maybe you're doing something custom), there's a flag:

wtm add --skip-setup feature/experiment

A Real Workflow Example

Here's how my afternoon looks now:

# Working on main, bug report comes in
wtm add hotfix/login-timeout
# → worktree created, deps installed, .env copied, ready to code

cd ../worktrees/hotfix/login-timeout
# Fix the bug, test, commit, push

cd ~/projects/myapp
# Back to main, still exactly where I left off

# Later, clean up
wtm remove --with-branch hotfix/login-timeout

No stashing. No context loss. The node_modules in my main checkout never got touched. My VS Code windows for both branches stay open simultaneously if I want.

Why Not Just Use Multiple Clones?

Fair question. I tried that first. The problems:

Disk space: Each clone duplicates .git (can be 100MB+ for large repos)
Divergence: Clones drift apart. You forget to fetch in one, push in another
Branch confusion: Which clone has the latest main? Did I push to the right remote?
No shared state: Git hooks, config, refs are all separate

Worktrees share the git database. One remote, one set of branches, one .git/config. But multiple working directories.

The One Catch

Worktrees aren't perfect. A few things to be aware of:

You can't have the same branch checked out in two worktrees — this is a git limitation, not a tool limitation
Some tools get confused — older IDEs might not understand worktrees well (modern VS Code handles them fine)
Path-based tooling — if you have scripts that hardcode paths, they'll break in worktrees (use git rev-parse --show-toplevel)

Wrapping Up

If you context-switch between branches more than twice a day, worktrees will save you real time. And if the raw git commands feel too manual, worktree-manager handles the boring parts.

npm install -g worktree-manager
wtm add your-branch-name

It's open source, MIT licensed, and works with Node.js 18+. Zero config, detects your project type, and gets out of your way.

The biggest shift for me was mental — instead of thinking "switch branches", I started thinking "open a new workspace". And that small change made a surprisingly big difference in how smoothly my day flows.

I Got Tired of Wiring Grafana + Loki + Tempo — So I Built a One-Command Observability Stack

Sulthon Zainul Habib — Fri, 29 May 2026 08:49:12 +0000

I've lost count of how many weekends I've spent wiring up observability stacks for side projects. Grafana for dashboards. Loki for logs. Tempo for traces. Prometheus for metrics. Jaeger if you're feeling adventurous. Each one needs its own config, its own datasource wiring, its own port.

By the time everything talks to each other, you've burned a Saturday and you still haven't shipped your actual app.

So I built TelyX — a lightweight observability suite that gives you logs, metrics, and traces with a single docker-compose up. No chasing config docs. No datasource chaining. Just run it and start instrumenting.

What's in the box

TelyX stacks five containers:

OpenSearch — stores and indexes your logs
OpenSearch Dashboards — visualizes those logs (think Kibana but open source)
Prometheus — scrapes and stores your metrics
OpenTelemetry Collector — receives traces and forwards them
Go backend + React frontend — ties it all together

Here's the docker-compose.yml:

version: "3.8"
services:
  opensearch:
    image: opensearchproject/opensearch:2.18.0
    environment:
      - discovery.type=single-node
      - plugins.security.disabled=true
    ports:
      - "9200:9200"

  opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:2.18.0
    ports:
      - "5601:5601"
    environment:
      - OPENSEARCH_HOSTS=http://opensearch:9200

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"

  otel-collector:
    image: otel/opentelemetry-collector:0.115.1
    ports:
      - "4317:4317"  # gRPC
      - "55681:55681" # HTTP

  backend:
    build: ../backend
    ports:
      - "8080:8080"

  frontend:
    build: ../frontend
    ports:
      - "3000:3000"

One command. Six services. All three pillars covered.

The Go backend — where the magic happens

The backend is a simple Go service that demonstrates the full observability pipeline. It exposes a /logs endpoint that:

Receives log data as JSON
Forwards it to OpenSearch for indexing
Records request metrics in Prometheus (count + duration histogram)
Creates an OpenTelemetry span for distributed tracing

Here's what the instrumentation looks like:

var (
    requestCount = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total number of HTTP requests",
        },
        []string{"path"},
    )
    requestDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "http_request_duration_seconds",
            Help:    "Histogram of response time",
            Buckets: prometheus.DefBuckets,
        },
        []string{"path"},
    )
)

func logHandler(w http.ResponseWriter, r *http.Request) {
    start := time.Now()
    defer func() {
        duration := time.Since(start).Seconds()
        requestDuration.WithLabelValues("/logs").Observe(duration)
    }()

    _, span := otel.Tracer("telyx-backend").Start(r.Context(), "logHandler")
    defer span.End()

    var logData map[string]interface{}
    json.NewDecoder(r.Body).Decode(&logData)

    // Forward to OpenSearch
    body, _ := json.Marshal(logData)
    http.Post("http://opensearch:9200/logs/_doc", "application/json", bytes.NewReader(body))

    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

See how every request gets three things for free? The Prometheus counter and histogram track volume and latency. The OTel span gives you distributed tracing. And the OpenSearch call ensures your logs are searchable.

Why not just use Grafana?

Look, I love Grafana. I use it at work. But for side projects and small teams, the Grafana+Loki+Tempo stack is heavy. You need:

Grafana itself
Loki (with its own storage config)
Tempo or Jaeger (with span storage)
Prometheus (metrics)
Each datasource configured in Grafana's UI
Service discovery or static targets

That's a lot of moving parts. TelyX trades some Grafana flexibility for simplicity. OpenSearch Dashboards handles log visualization natively. Prometheus gives you raw metric queries. And the OTel collector standardizes your trace pipeline.

If you're running production infra at scale, stick with Grafana. If you're building a side project and want to see "what's breaking" without a PhD in Grafana config — TelyX gets you there faster.

Running it yourself

Clone the repo and fire it up:

git clone https://github.com/sulthonzh/telyx.git
cd telyx/docker
docker-compose up -d

Wait about 30 seconds for OpenSearch to initialize (it's chatty on startup, that's normal). Then:

Frontend: http://localhost:3000
OpenSearch Dashboards: http://localhost:5601
Prometheus: http://localhost:9090
Backend API: http://localhost:8080

Send a test log:

curl -X POST http://localhost:8080/logs \
  -H "Content-Type: application/json" \
  -d '{"level":"info","message":"TelyX is running","service":"test"}'

Check it in OpenSearch Dashboards — go to Discover, create an index pattern for logs*, and you'll see your entry. In Prometheus, query http_requests_total and you'll see the metric. The trace lands in the OTel collector.

Three pillars. One request. Zero config headaches.

The sampling gotcha

One thing I learned the hard way — the backend uses 10% trace sampling:

trace.WithSampler(trace.ParentBased(trace.TraceIDRatioBased(0.1)))

This is intentional for production workloads where you don't want every single request traced. But during development, you might want to bump that to 1.0 so every request shows up. Cost me 20 minutes of "where are my traces?!" before I realized.

Also, the initTracer function has a duplicate trace.WithBatcher(exporter) line — that's a bug, not a feature. It won't break anything but it's redundant. PR welcome 😉

What I'd like to add next

TelyX is functional but minimal. A few things I want to build:

Alerting rules — Prometheus alertmanager integration so you get notified when things break
Pre-built dashboards — OpenSearch and Prometheus dashboards that work out of the box
Multi-service tracing — right now the trace pipeline works but you need OTel SDK in your own services to propagate context
Helm chart — for deploying to Kubernetes instead of just Docker Compose

If any of that sounds interesting, the repo is open. Contributions welcome.

When to use this vs. managed services

Real talk: if you're running a production system with SLAs, use Datadog or New Relic. Managed observability is worth the money when your pager goes off at 3 AM and you need answers fast.

But for:

Side projects where you want visibility without the price tag
Learning how observability actually works (the three pillars, not just "install agent")
Small teams that can't justify $100+/month on monitoring
Prototyping before committing to a managed stack

TelyX fills that gap. It's not trying to be Datadog. It's trying to be the thing you reach for when console.log isn't enough but full Grafana is too much.

Give it a spin and let me know what you think. Star the repo if it saves you a weekend — that's literally what it was built for.

Built TelyX as part of an open-source lab. Check out the repo if you want to contribute or just poke around the code.

I Use lazydocker for Everything — Except When I Don't

Sulthon Zainul Habib — Fri, 29 May 2026 07:36:16 +0000

I love lazydocker. Honestly, Jesse Duffield built something special — it's the first thing I install on a new machine. But here's the thing: 90% of the time I open it, I just want to check if my containers are healthy. I don't need to browse image layers, scroll through compose configs, or dig into volume mounts. I just want the pulse check.

And sometimes lazydocker feels like opening a control room when you just need a dashboard.

So I built dockervis. It's a terminal dashboard that does one thing: show you what your Docker containers are doing, right now, and let you act on it with a single keypress.

The Problem I Was Solving

My typical workflow looks like this:

Start 4-5 containers with docker compose
Something feels off — API is slow, or a cron job might've crashed
Open terminal, type docker ps, squint at the truncated output
Copy a container ID, run docker stats --no-stream
Realize it was the wrong container
Repeat

docker stats is fine but it's a firehose. docker ps doesn't show resource usage. And jumping between them gets old fast when you're debugging at 2 AM.

lazydocker solves this, but it also shows me every image, every volume, every compose file — when I just want to know if my app container is eating all the RAM again.

What dockervis Does

npm install -g dockervis
dockervis

That's it. You get a live dashboard:

┌─────────────────────────────────────────────────────────────┐
│ dockervis - Docker Container Dashboard                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ ● app (running)           CPU: 1.2%                        │
│ ● db (running)            Memory: 256 MB / 512 MB (50.0%)  │
│ ○ web (exited)            Network RX: 1.2 GB               │
│ ● redis (running)         Network TX: 512 MB               │
│                                                             │
└─────────────────────────────────────────────────────────────┘
q: Quit | r: Refresh | s: Stop | R: Restart | d: Delete

Every container, its state, CPU, memory, and network — updated live. No mouse needed. No panels to navigate. Just the info.

The Keyboard Shortcuts That Actually Matter

Here's the part I use most. When something's stuck:

Press j to move to the container
Press R to restart it
Done

Or when a container exited and I want it gone:

Move to it with k/j
Press d to delete it

The full set:

Key	What it does
`j` / `↓`	Move down
`k` / `↑`	Move up
`s`	Stop container
`R`	Restart container
`d`	Delete (exited only)
`r`	Force refresh
`q`	Quit

vim-style navigation because, well, muscle memory.

Filtering When You Have Too Many Containers

On my work machine I have like 20 containers. Most of them are from old projects I forgot to clean up. I don't need to see all of them.

# Only show running ones
dockervis --filter running

# Focus on specific services
dockervis --include app,db,redis

# Hide the noise
dockervis --exclude test,ci

The --exclude flag is my favorite. I have a bunch of test containers that I never touch — filtering them out makes the dashboard actually useful.

Exporting Metrics (Because Sometimes You Need Proof)

Sometimes you need to show someone "hey, this container has been eating 80% CPU for three days." Or you want to log metrics over time.

# JSON export
dockervis --export metrics.json

# CSV if you need to throw it in a spreadsheet
dockervis --export metrics.csv --export-format csv

I use this in CI sometimes — run it once, dump to JSON, parse with jq in a health check script. Not glamorous but it works.

Why TypeScript (And Not Go Like Everyone Else)

Most terminal Docker tools are written in Go — lazydocker, ctop, docui. Nothing wrong with Go. But I write TypeScript all day. When I want to fix something or add a feature, I want to do it in the language I'm fastest in.

dockervis uses:

dockerode for the Docker API — battle-tested, well-documented
blessed for the terminal UI — same library lazydocker uses under the hood (via tview/bubbletea equivalents)

The result is a tool that TypeScript/Node developers can actually contribute to without learning a new language. And the install is just npm install -g — no Go toolchain needed.

When I Still Reach for lazydocker

I'm not going to pretend dockervis replaces lazydocker for everything. If I need to:

Browse Docker Compose configs
Inspect image layers
Manage volumes and networks
Read container logs in detail

...I still use lazydocker. It's the better Swiss Army knife.

But for the 5-second "is everything okay?" check? Or the "restart that one container real quick" moment? dockervis is faster. Less noise, less cognitive load.

Quick Setup

# Install
npm install -g dockervis

# Make sure you have Docker socket access
sudo usermod -aG docker $USER
# (log out and back in)

# Run it
dockervis

If you want to tweak the refresh rate:

dockervis --interval 5000  # 5 seconds instead of default 2

And if Docker is running on a remote host:

DOCKER_HOST=tcp://192.168.1.100:2375 dockervis

The Code

It's open source, MIT licensed: github.com/sulthonzh/dockervis

Issues and PRs welcome. Especially if you find bugs — I mainly tested this on my own machine (macOS + Docker Desktop), so Linux and Windows reports would be helpful.

Building developer tools is my thing. Check out my other projects at github.com/sulthonzh

I Scanned 200 Public GitHub Repos for Leaked .env Files — Then Built a CLI to Stop It

Sulthon Zainul Habib — Fri, 29 May 2026 04:49:37 +0000

I was helping a friend debug a deploy last month. Cloned the repo, checked the .env — and there it was. A full AWS access key, sitting in plain text. The repo was public for 8 months.

That's when I started looking around. Public GitHub repos, open .env files, real credentials. It's... more common than you'd think. People push .env by accident, forget to update .gitignore, or just don't realize those files end up in git history forever.

So I built envguard — a zero-dependency CLI that scans your .env files for leaked secrets and validates your config before it hits production.

The problem isn't new, but it keeps happening

Every tutorial tells you "add .env to .gitignore." Every framework has a .env.example template. And yet, I've seen:

AWS keys (AKIA...) in public npm packages
GitHub personal access tokens (ghp_...) committed in monorepos
Database URLs with passwords in Stack Overflow questions (screenshots, but still)
Private keys embedded in Docker build contexts

The worst part? Most of these leaks happen because there's no automated check. Your CI pipeline runs tests, lints code, checks coverage — but nobody's checking if your .env just leaked a production database password.

What envguard does

It's two things: secret scanning and env validation. Let me walk through both.

Secret scanning

npx envguard secrets .env

This scans your .env file for known credential patterns:

AWS Access Key IDs (AKIA...)
AWS Secret Access Keys
GitHub Tokens (ghp_, ghs_)
Generic API Keys (20+ chars, high-entropy strings)
Generic Tokens (32+ chars)
Private Keys (-----BEGIN ... PRIVATE KEY-----)
JWTs (eyJ...)

If it finds anything, it exits with code 1 and shows you exactly which keys are problematic — but it redacts the actual values. Because the last thing you need is your secret scanner leaking secrets in your CI logs.

$ envguard secrets .env

⚠ Secret detected in .env:
  Line 3: AWS_ACCESS_KEY_ID
    Pattern: AWS Access Key ID (AKIA...)
  Line 4: AWS_SECRET_ACCESS_KEY
    Pattern: AWS Secret Access Key (40 chars, base64)
  Line 7: GITHUB_TOKEN
    Pattern: GitHub Token (ghp_...)

Found 3 secrets. Values have been redacted.
Exit code: 1

Env validation

The other side: making sure your .env actually has everything it needs. We've all been there — deploy fails because someone forgot to add REDIS_URL to the production environment. Or worse, it succeeds but the app silently falls back to defaults.

envguard check .env .env.example

This compares your .env against .env.example and tells you:

Missing keys — variables expected but not set
Extra keys — variables set but not documented
Empty values — keys that exist but have no value

$ envguard check .env .env.example

✓ DATABASE_URL
✗ REDIS_URL          ← missing
+ STRIPE_KEY          ← extra (not in .env.example)
! PORT               ← empty value

3 issues found.
Exit code: 1

Type validation with annotations

This is the part I'm most excited about. You can annotate your .env.example with types, and envguard will validate them:

# .env.example
DATABASE_URL=           # @required @type url
PORT=3000               # @type number
DEBUG=false             # @type boolean
ADMIN_EMAIL=            # @type email
FEATURE_FLAGS=          # @type json

Then run:

envguard validate .env .env.example

It checks that DATABASE_URL is actually a valid URL, PORT is a number, DEBUG is a boolean, etc. Supported types: string, number, boolean, url, email, json.

This catches the sneaky bugs. Like when someone sets PORT=3000abc and your app crashes with NaN in weird places.

Putting it in CI

Here's the real value — this runs in your pipeline before anything ships.

# .github/workflows/deploy.yml
steps:
  - uses: actions/checkout@v4

  - name: Check env vars are complete
    run: npx envguard check .env .env.example

  - name: Validate env types
    run: npx envguard validate .env .env.example

  - name: Scan for leaked secrets
    run: npx envguard secrets .env

  - name: Deploy
    run: ./deploy.sh

If any of those checks fail, the deploy doesn't happen. No more shipping with missing config. No more leaking credentials.

For teams, I'd add this to PR checks too:

# .github/workflows/pr.yml
steps:
  - uses: actions/checkout@v4

  - name: Ensure no secrets in env files
    run: npx envguard secrets

Even if you don't use .env.example (you should though), the secret scanner alone is worth adding. One npx command, zero config.

Why not just use git-secrets or trufflehog?

Good question. Those tools are great, but they solve a different problem:

git-secrets scans your git history for patterns. It's preventive but doesn't check your current working directory.
trufflehog scans repos and orgs for leaked credentials. It's an audit tool.
detect-secrets by Yelp is similar — great for scanning repos.

envguard is a pre-commit/pre-deploy tool. It checks the .env file you're about to ship right now. It also validates that your config is complete and correctly typed — something none of those tools do.

Use them together. trufflehog for auditing your org, envguard for gating your deploys.

The zero-dependency thing

I went out of my way to make this have zero runtime dependencies (only commander for CLI parsing, which is basically part of Node at this point). Why?

Because security tools should be auditable. If you're going to trust a CLI to scan your secrets, you should be able to read the entire codebase in an afternoon. Every dependency is a black box. When your secret scanner itself has 47 transitive dependencies... that feels wrong.

The whole thing is ~500 lines of actual logic. You can read it, understand it, and verify it's not doing anything shady.

Quick start

# Scan for secrets
npx envguard secrets

# Check env completeness
npx envguard check

# Full validation with types
npx envguard validate

# Generate .env.example from existing .env
npx envguard init

There's also envguard diff for a side-by-side comparison of two env files, and --json output for every command if you want to pipe it into something else.

The tool works with both CJS and ESM projects. Install globally with npm install -g envguard or just use npx.

What I learned building this

The regex patterns for detecting secrets are tricky. AWS access keys have a specific format (AKIA followed by 16 alphanumeric chars), which is easy. But "generic API key" is harder — you're basically looking for long, high-entropy strings that look like credentials. There will be false positives. That's fine — better to flag too much than miss a real leak.

The --json flag was a late addition but it turned out to be the most useful feature for CI. You can parse the output, filter it, post it to Slack, whatever.

If you're interested, the code is at github.com/sulthonzh/envguard. 51 tests, MIT license. Contributions welcome — especially new secret patterns if you've seen ones I missed.

Stay safe out there. Check your .env files.

I Deploy to Docker Swarm from GitHub Actions — Here's the Setup That Actually Works

Sulthon Zainul Habib — Thu, 28 May 2026 20:45:21 +0000

If you've ever tried to set up continuous deployment to a remote Docker host, you know the pain. GitHub Actions is great for CI — build, test, done. But deploying to a remote server? That's where things get messy.

Most tutorials hand you a 200-line shell script with ssh hacks, scp gymnastics, and prayer. I got tired of that, so I packaged it into a reusable GitHub Action that handles Docker Compose and Docker Swarm deployments over SSH.

Here's how it works and how to set it up in under 10 minutes.

The Problem

You have a VPS (or a bare-metal server) running Docker. You want GitHub Actions to:

Build your images (or pull them from a registry)
SSH into your server
Deploy using docker-compose up or docker stack deploy
Clean up old files

Without leaking SSH keys everywhere or writing bespoke deployment scripts per project.

The Action: `docker-remote-deployment-action`

github.com/sulthonzh/docker-remote-deployment-action

It's a GitHub Action available on the Marketplace that does exactly this. It supports two deployment modes:

docker-compose — runs docker-compose on the remote host
docker-swarm — runs docker stack deploy for Swarm services

Both via SSH, both from your existing docker-compose.yml.

The Minimal Setup

1. Add your SSH keys to GitHub Secrets

In your repo → Settings → Secrets and variables → Actions, add:

SSH_PRIVATE_KEY — your private key for the server
SSH_PUBLIC_KEY — the corresponding public key

2. Create the workflow file

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy to server
        uses: sulthonzh/docker-remote-deployment-action@v1
        with:
          remote_docker_host: deploy@your-server.com
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
          ssh_public_key: ${{ secrets.SSH_PUBLIC_KEY }}
          deployment_mode: docker-compose
          stack_file_name: docker-compose.yml
          args: up -d

Push to main → your service deploys. That's it.

Docker Swarm Mode

If you're running a Swarm cluster, switch the mode and add the stack name:

- name: Deploy to Swarm
  uses: sulthonzh/docker-remote-deployment-action@v1
  with:
    remote_docker_host: deploy@your-server.com
    ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
    ssh_public_key: ${{ secrets.SSH_PUBLIC_KEY }}
    deployment_mode: docker-swarm
    copy_stack_file: true
    deploy_path: /opt/deployments/myapp
    stack_file_name: docker-compose.yaml
    keep_files: 5
    args: myapp

This will:

Copy your docker-compose.yaml to /opt/deployments/myapp/ on the server
Run docker stack deploy -c docker-compose.yaml myapp
Keep the last 5 deployment files (auto-cleanup old ones)

Feature Breakdown

`copy_stack_file: true` — Deploy from the server

When enabled, the Action copies your compose file to a configurable path on the remote host before deploying. This is useful when:

Your compose file references local build contexts
You want deployment history on the server
You need to inspect the compose file on the host later

Combined with keep_files: N, it auto-prunes old deployment directories. No manual cleanup.

`pull_images_first: true` — Pull before deploy

If your compose file references images from a private registry:

pull_images_first: true
docker_registry_username: ${{ secrets.REGISTRY_USER }}
docker_registry_password: ${{ secrets.REGISTRY_PASS }}

The Action logs into your registry and pulls images before deploying. Works with any Docker-compatible registry.

`docker_prune: true` — Automatic cleanup

Adds a docker system prune -f after deployment. Useful on small VPS instances where disk space is precious.

`pre_deployment_command_args` — Run commands before deploy

Need to run migrations or health checks before deploying?

pre_deployment_command_args: "docker exec myapp_web bundle exec rake db:migrate"

Runs any command on the remote host before the deployment step.

A Real-World Example: Full Pipeline

Here's a complete workflow that builds, pushes, and deploys:

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: myuser/myapp:${{ github.sha }}

      - name: Update image tag in compose file
        run: |
          sed -i "s|image: myuser/myapp:.*|image: myuser/myapp:${{ github.sha }}|" docker-compose.yml

      - name: Deploy
        uses: sulthonzh/docker-remote-deployment-action@v1
        with:
          remote_docker_host: deploy@myserver.com
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
          ssh_public_key: ${{ secrets.SSH_PUBLIC_KEY }}
          deployment_mode: docker-compose
          copy_stack_file: true
          deploy_path: /opt/myapp
          stack_file_name: docker-compose.yml
          keep_files: 3
          pull_images_first: true
          docker_registry_username: ${{ secrets.DOCKERHUB_USERNAME }}
          docker_registry_password: ${{ secrets.DOCKERHUB_TOKEN }}
          args: up -d --remove-orphans

This gives you a full CI/CD pipeline: commit → build → push → deploy. No Jenkins, no GitLab Runner, no self-hosted agent. Just GitHub Actions SSHing into your server.

Security Notes

A few things to keep in mind:

Use a dedicated deploy user on your server, not root. Create a user that only has Docker permissions.
Restrict SSH keys — the deploy key should only work for Docker-related commands.
Use GitHub Secrets — never hardcode keys in your workflow files.
Rotate keys if they ever appear in logs (the Action masks secrets, but be careful with set -x in pre-deployment commands).

When This Shines

This setup is ideal for:

Solo devs / small teams deploying to a single VPS
Side projects that don't need Kubernetes
Staging environments that auto-deploy on push
Hobby infrastructure where you want CI/CD without the complexity of ArgoCD or Flux

If you're running 50 microservices on EKS, this isn't for you. If you're deploying a few containers to a $5/month DigitalOcean droplet, this is exactly what you need.

What's Next

The Action is stable and production-ready at v1.0.0. It's adapted from earlier work by wshihadeh and TapTap21, with improvements for modern GitHub Actions.

Star it, try it, open issues if something doesn't work. That's how open source grows.

Built this while deploying side projects at quadbyte. More dev tools coming.

I Accidentally force-pushed to main at 11 PM — So I Built an Interactive Git Undo Tool

Sulthon Zainul Habib — Thu, 28 May 2026 12:13:25 +0000

We've all been there. It's late. You're tired. You run git push --force and realize — half a second too late — you're on main, not your feature branch.

Your heart drops. Your teammates' commits are gone. You open Stack Overflow in a panic.

That exact scenario happened to me (okay, it was a branch, not main — but the fear was real). After the third time digging through git reflog output at midnight, I built gitpanic — an interactive CLI that auto-detects git disasters and walks you through recovery.

The Problem: git reflog is Powerful but Hostile

git reflog is the right tool for the job. But let's be honest:

$ git reflog
a1b2c3d HEAD@{0}: checkout: moving from feature/login to main
e4f5g6h HEAD@{1}: commit: add login validation
i7j8k9l HEAD@{2}: commit: fix auth middleware
m0n1o2p HEAD@{3}: checkout: moving from main to feature/login

Cool. Now what? Which SHA do I use? What command fixes a deleted branch vs. a bad merge? Is git reset --hard safe here or am I about to make things worse?

Every developer knows this feeling. Stack Overflow's most upvoted git questions aren't about advanced workflows — they're all "how do I undo X":

"How to undo last commit" — 16k+ upvotes
"How to undo git push" — 5k+ upvotes
"How to recover deleted branch" — 3k+ upvotes

The knowledge exists. The UX is the problem.

Enter gitpanic

gitpanic is a zero-config CLI that does three things:

Auto-detects what went wrong by analyzing your git state
Explains the problem in plain English with confidence levels
Guides you through recovery with risk-rated options and confirmation prompts

npx gitpanic

That's it. No arguments, no config files, no documentation to read while sweating.

How It Detects Disasters

gitpanic runs multiple "detectors" against your current repository state:

1. Reflog Analysis

It scans recent reflog entries looking for red flags:

Recent force pushes (within the last hour)
Branch deletions
Sudden HEAD movements that suggest accidental operations

2. Working Tree State

Uncommitted changes that might be about to get lost
Detached HEAD state (happens more than you'd think)
Merge conflicts left unresolved

3. Timing Heuristics

Commits made less than 2 minutes ago → probably accidental
Rapid branch switches → possibly confused about where you are

Each detector returns a finding with a confidence score. If confidence is high enough, it surfaces the issue.

Real-World Example: Recovering a Deleted Branch

Here's what happens when you accidentally delete a branch:

$ gitpanic
🔍 Analyzing your git state...

⚠️  Found 1 potential issue:

1. 🔴 Deleted Branch
   Branch "feature/login" was deleted 45 seconds ago.
   Confidence: 90%

Select an issue to fix [1-1]: 1

🔧 Recovery options for: Deleted Branch

1. ✅ Restore branch "feature/login"
   Recreate the branch from the deleted commit
   Risk: safe
   Steps:
   - git branch feature/login abc1234
   - git checkout feature/login

Select a recovery option [1-1]: 1
⚠️  Confirm: "Restore branch \"feature/login\""? This can be undone. [y/N]: y

🚀 Executing recovery...

✅ Recovery complete!

Notice the risk rating — safe. gitpanic never marks destructive operations as safe. You always know what you're getting into.

Recovery Options Are Tiered by Risk

Every disaster comes with multiple recovery strategies:

Risk Level	What It Means	Examples
✅ Safe	Can be easily undone	Stash, soft reset, branch restore
⚡ Medium	May need manual cleanup	Cherry-pick, rebase
⚠️ High	Destructive, no undo	Hard reset, force push

This matters because when you're panicking, you don't always make the best decisions. gitpanic shows you the safest option first and clearly marks dangerous ones.

The Dry Run Safety Net

Not sure what will happen? Use dry run mode:

gitpanic --dry-run

This shows you exactly what commands would run without executing anything. Perfect for learning or when you want to handle recovery manually but need guidance on the right commands.

Under the Hood: Building Disaster Detectors

Here's a simplified version of how the "accidental commit" detector works:

async function detectAccidentalCommit(repo: Repository): Promise<Finding | null> {
  const lastCommit = await repo.getHeadCommit();
  const commitAge = Date.now() - lastCommit.date().getTime();

  // If the last commit was made less than 2 minutes ago
  if (commitAge < 120_000) {
    return {
      type: 'accidental_commit',
      severity: 'low',
      confidence: 0.8,
      message: `You just committed "${lastCommit.message()}" ${secondsAgo}s ago.`,
      recoveries: [
        {
          name: 'Undo commit, keep changes staged',
          risk: 'safe',
          steps: ['git reset --soft HEAD~1']
        }
      ]
    };
  }

  return null;
}

The key insight: timing is the strongest signal. A commit made 10 seconds ago is very different from one made 10 hours ago. By combining timing with reflog patterns, you can surface the right problem at the right time.

What It Can Detect (So Far)

Disaster	Detection Method	Confidence
Detached HEAD	`git status`	100%
Deleted Branch	Reflog scan	90%
Force Push	Reflog analysis	85%
Botched Merge	MERGE_HEAD file	95%
Accidental Commit	Timing heuristics	80%
Uncommitted Changes	`git status`	100%
Wrong Branch Commit	Branch comparison	70%

When NOT to Use gitpanic

Let's be honest — if you're a git wizard who lives in the reflog, this tool isn't for you. It's for:

Developers who've been coding for 2 years and still Google "how to undo git commit"
Junior devs who are afraid of git reset
Anyone working late at night when judgment is impaired
Teams that want a safer workflow for git operations

Get Started

# Install globally
npm install -g gitpanic

# Or use without installing
npx gitpanic

# Preview without making changes
gitpanic --dry-run

GitHub: sulthonzh/gitpanic

License: MIT

The goal isn't to replace git reflog — it's to make recovery accessible when you're in full panic mode. Because the worst time to learn git internals is when your production branch is hanging by a thread.

If you've ever panicked after a bad git operation, give gitpanic a try. And if you have ideas for new disaster detectors, PRs are welcome — there's a clean plugin architecture for adding new ones.

We Lost 4 Hours to a Missing .env Variable — So I Built a Schema-First Fix

Sulthon Zainul Habib — Wed, 27 May 2026 23:45:08 +0000

Every developer has a war story about environment variables. Ours went like this: production deployment at 2 AM, the app starts throwing undefined is not a valid database URL, and the team spends 4 hours hunting down a missing DATABASE_HOST that was present in every environment except the one that mattered.

The fix? We wrote a tool called dotenv-schema that flips the problem upside down. Instead of validating what you have, you define what you need first.

The Problem with .env Files

Here's the thing about .env files — they're documentation, configuration, and secrets all rolled into one unstructured text file. No types. No required/optional flags. No validation until runtime (if you're lucky).

Most teams handle it like this:

# .env
DATABASE_URL=postgres://localhost:5432/mydb
NODE_ENV=production
PORT=3000
API_KEY=

Spot the problem? API_KEY is empty. In production. At runtime, something explodes.

Existing tools like dotenv, envalid, or zod validate after the fact. You write your validation code, you remember to call it, and hopefully you covered every variable. It's reactive.

Schema-First: Define Before You Validate

The idea behind dotenv-schema is simple: define the schema first, then generate everything from it.

npx dotenv-schema init --env=.env --output=schema.json

This reads your existing .env and generates a schema with inferred types:

{
  "DATABASE_URL": {
    "type": "string",
    "required": true,
    "format": "uri",
    "description": "Database connection string"
  },
  "NODE_ENV": {
    "type": "enum",
    "values": ["development", "production", "test"],
    "required": true,
    "description": "Application environment"
  },
  "PORT": {
    "type": "number",
    "required": false,
    "default": 3000,
    "min": 1024,
    "max": 65535,
    "description": "Server port number"
  },
  "API_KEY": {
    "type": "string",
    "required": true,
    "description": "External API authentication key"
  }
}

Now you have a single source of truth for what your app needs. From this schema, you can generate:

.env.example — for onboarding new developers
TypeScript types — so process.env is typed
Validation code — runtime checks before your app starts
Documentation — a markdown table for your README

The Real Technique: Generating a Validation Gate

Here's the part that actually saved us. Run:

dotenv-schema generate --validator --types --env-example

You get a generated env.validator.ts that looks like this:

import { EnvValidator } from "dotenv-schema/validator";

const schema = {
  DATABASE_URL: { type: "string", required: true, format: "uri" },
  NODE_ENV: { type: "enum", values: ["development", "production", "test"], required: true },
  PORT: { type: "number", required: false, default: 3000 },
  API_KEY: { type: "string", required: true }
};

const validator = new EnvValidator(schema);

export function validateEnv(env: Record<string, string>) {
  const result = validator.validate(env);
  if (!result.valid) {
    console.error("❌ Environment validation failed:");
    result.errors.forEach(err => console.error(`  - ${err}`));
    process.exit(1);
  }
  return result.data;
}

Then in your app entry point:

import { validateEnv } from "./env.validator";
import * as dotenv from "dotenv";

dotenv.config();
const env = validateEnv(process.env);
// ^ Fully typed, fully validated. App never starts with bad config.

If API_KEY is missing or empty, the app refuses to start with a clear error. No more 2 AM detective work.

CI/CD Integration: Catch It Before Deploy

The schema file is JSON — commit it to your repo. Now CI can validate too:

# .github/workflows/ci.yml
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 20
  - run: npm install -g dotenv-schema
  - run: dotenv-schema validate --env=.env.example --schema=schema.json

If someone adds a new required variable to the schema but forgets to update .env.example, CI fails. The schema becomes a contract between developers and the deployment pipeline.

What About zod/envalid?

Good question. Here's when to use what:

zod: Great for API validation, complex runtime schemas. Overkill for env vars if you just need type checking.
envalid: Solid runtime validation, but no schema-first approach. You write validation inline in your code.
dotenv-schema: Schema is a separate artifact. You generate .env.example, types, docs, and validators from one definition. It's about the workflow, not just validation.

If you have 3 environment variables, any of these work fine. If you have 30+ across microservices, having a committed schema file that generates everything is a different level of maintainability.

The Type System

dotenv-schema supports these types out of the box:

string — with optional format (uri, email), pattern (regex), min/max length
number — with optional min/max range
boolean — true or false (handles string "true"/"false" from .env)
enum — one of predefined values, great for NODE_ENV
json — validates that the value parses as valid JSON

Each variable can be required or optional with a default value and a human-readable description.

Practical Tips

1. Start from your existing .env:

npx dotenv-schema init --env=.env --interactive

The interactive mode prompts you for types and descriptions instead of guessing.

2. Add variables over time:

dotenv-schema add --schema=schema.json

Prompts for name, type, required, default, description. No manual JSON editing.

3. Generate docs for your README:

dotenv-schema generate --docs

Outputs a clean markdown table you can paste into your project documentation.

4. Check schema health:

dotenv-schema check --schema=schema.json

Validates the schema itself — catches circular refs, invalid types, missing descriptions.

Installation

npm install -g dotenv-schema

Or use without installing:

npx dotenv-schema init --env=.env

Works with Node.js >= 18. MIT licensed.

GitHub: sulthonzh/dotenv-schema

The takeaway isn't about this specific tool — it's the schema-first mindset. Define what you need before you need it. Generate the boilerplate. Let the schema be the contract. Your future self (especially at 2 AM) will thank you.

Built by sulthonzh — because losing 4 hours to a missing env var is 4 hours too many.

I Don't Know Zig — But I Built a Production Log Tool With GitHub Copilot

Sulthon Zainul Habib — Mon, 25 May 2026 02:49:25 +0000

This is a submission for the GitHub Finish-Up-A-Thon Challenge

⭐ GitHub Repository

👉 github.com/sulthonzh/logchef-zig — Star it if you find it useful!

What I Built

logchef — a 592KB binary that parses, filters, and pretty-prints log files in JSON, logfmt, or plain text. Think jq meets tail meets grep, purpose-built for logs.

I'm a TypeScript/Node.js developer. I'd never written a line of Zig before this project. I built the entire thing using GitHub Copilot.

Demo

# Filter errors from any log format
logchef app.log -l error

# Search + follow in real-time
logchef app.log -c "timeout" -F

# Field filtering
logchef app.log -f status=500

# JSON output for piping
logchef app.log -l error -o json | jq '.message'

# Pipe from kubectl
kubectl logs my-pod | logchef -c panic

🔗 GitHub: github.com/sulthonzh/logchef-zig
⭐ Give it a star! It helps other developers discover the project.

The Comeback Story

BEFORE (May 6, 2026)

I started logchef during a weekend sprint. I had an idea: replace bloated Node.js log viewers with a tiny Zig binary. I didn't know Zig, so I opened VS Code, enabled Copilot, and started learning.

The first version was rough:

1,218 lines of code
Basic JSON parsing and level filtering worked
Text search worked
Color output worked
21 tests passing

But the README listed features that didn't exist:

❌ Follow mode (tail -f)
❌ Logfmt format support
❌ No benchmarks
❌ No cross-platform builds
❌ No release automation

Life happened. The project sat for 2 weeks.

AFTER (May 25, 2026)

I picked it back up for the GitHub Finish-Up-A-Thon. Using GitHub Copilot CLI (copilot -p), I created 6 issues and implemented them one by one:

✅ Follow mode — polls file every 500ms, handles rotation
✅ Logfmt support — auto-detects and parses key=value pairs
✅ JSON output — NDJSON format for pipeline integration
✅ Benchmarks — compared vs jq, grep, awk
✅ Cross-platform CI — Linux + macOS, x86 + ARM
✅ Polished README — badges, comparison table, benchmarks

Final stats:

1,991 lines of Zig code (+64%)
23 tests
592KB binary
4-platform CI
Zero dependencies

My Experience with GitHub Copilot

Learning Zig Through Copilot

Zig has concepts I'd never seen in TypeScript:

Explicit allocators — every allocation needs an allocator passed in
Error unions — !Type syntax for functions that can fail
Comptime — code that runs at compile time
No hidden control flow — no exceptions, no hidden allocations

I didn't learn these from docs. I learned them by writing prompts like:

copilot -p "How do I read a file line by line in Zig? Show me with explicit allocators."

And Copilot would generate code that taught me the pattern:

var gpa = std.heap.GeneralPurposeAllocator(.{}){};
const allocator = gpa.allocator();
const file = try std.fs.cwd().openFile(path, .{});
const content = try file.readToEndAlloc(allocator, max_size);
defer allocator.free(content);

Copilot CLI as My Zig Tutor

The most valuable tool was copilot -p — non-interactive mode that reads your codebase and generates matching code:

# Implement follow mode
copilot -p "Add follow mode that polls a file for new lines every 500ms" \
  --allow-all -C . -s

# Add logfmt parsing
copilot -p "Add logfmt key=value parsing to the existing parser" \
  --allow-all -C . -s

# Fix build errors
copilot -p "The build fails with: [error]. Fix it." \
  --allow-all -C . -s

Every prompt taught me something new about Zig. By the end, I understood allocators, error handling, and even cross-compilation — all through Copilot-guided implementation.

What Copilot Got Right

Pattern matching — it read my existing code and matched the style perfectly
Zig idioms — it knew to use defer for cleanup, try for error propagation
Test writing — it generated tests that followed my existing test patterns
Cross-platform — it knew the right Zig target triples for all 4 platforms

What I Still Needed to Do

Architecture decisions — Copilot writes code, but I decided what to build
Code review — I read every line before committing
Integration — I connected the pieces Copilot built
Problem framing — the quality of Copilot's output depends on how you describe the problem

Results

Metric	Before	After
Lines of code	1,218	1,991
Tests	21	23
Binary size	592KB	592KB (unchanged!)
Formats supported	JSON, plain text	JSON, logfmt, plain text
Follow mode	❌	✅
JSON output	❌	✅
Cross-platform CI	❌	✅ (4 platforms)
Benchmarks	❌	✅

Key Takeaway

You don't need to know a language to build something useful in it. GitHub Copilot won't replace understanding — but it dramatically lowers the barrier to entry. I went from "what is Zig?" to "I shipped a cross-platform CLI tool in Zig" in 3 weeks, part-time.

The trick isn't blindly accepting Copilot's output. It's:

Having a clear idea of what you want to build
Reading and understanding every line Copilot generates
Using Copilot to learn, not just to code

Thanks to GitHub and DEV for the challenge! 🙏

Built with GitHub Copilot (free tier). No paid subscriptions used.

I Replaced 70MB Node.js Log Viewer with a 172KB Zig Binary

Sulthon Zainul Habib — Sun, 24 May 2026 19:21:56 +0000

Log files are the debugging reality of production systems. You stare at them daily, curse the noise, and grep until your eyes bleed.

The problem? Most log viewers are heavy, slow, or require complex setups. I wanted something that just works.

The Problem

I tried the usual suspects:

tail -f: Raw, unfiltered stream. No filtering, no highlighting. Useless for anything beyond watching errors fly by.
grep: Powerful but terminal-destroying. grep -R "ERROR" ./logs | grep "database" works, but it's not interactive. You can't drill down, and the output is a wall of text.
Docker logs: docker logs -f container is okay for one container, but when you have 15 microservices, it's a mess.
Existing log viewers: Most are GUI apps (heavy), or Node.js CLI tools (slow, 70MB+ dependencies), or require configuration files.

I needed something that:

Is fast — no lag when scrolling through 1GB log files
Has syntax highlighting — ERROR in red, DEBUG in gray, stack traces visible
Lets me filter interactively — type / to search, drill down without re-running commands
Is tiny — no 70MB node_modules bloat

The Solution: logchef-zig

I wrote logchef-zig in Zig. It's a single 172KB binary that does exactly what I need:

What It Does

# View any log file with auto-highlighting
logchef app.log

# Follow mode (like tail -f, but with filtering)
logchef -f app.log

# Filter by log level before opening
logchef --level error app.log

# Interactive search (press / inside the viewer)
logchef app.log

Why Zig?

I chose Zig for three reasons:

Zero dependencies: No node_modules, no Python runtime, nothing. Just one binary.
Performance: Zig compiles to native machine code. I'm talking instant scrolling on 1GB+ files.
Cross-compilation: I can build for Linux, macOS, and Windows from my Mac. One CI run, three binaries.

How It Works

1. Fast Log Parsing

Logchef reads logs line-by-line and detects common log formats automatically:

2026-05-25T02:19:12.123Z [INFO] User logged in
2026-05-25T02:19:15.456Z [ERROR] Database connection failed

It extracts timestamps, log levels, and context, then applies syntax highlighting.

2. Interactive TUI

The interface is terminal-based (like htop or lazygit):

Arrow keys: Scroll through the file
/: Search for patterns (supports regex)
l: Filter by log level (DEBUG, INFO, WARN, ERROR)
q: Quit

No mouse required. Pure keyboard efficiency.

3. Zero Configuration

Logchef doesn't need a config file. It detects log patterns heuristically. If your logs look like this:

[INFO] Something happened
ERROR: Something broke

It just works. If they don't, you can pass a custom regex.

Benchmarks

I tested logchef against a 1GB log file with 10 million lines:

Tool	Startup Time	Memory Usage	Binary Size
logchef-zig	0.05s	2.5MB	172KB
Node.js equivalent	1.2s	85MB	70MB
bat (syntax highlighter)	0.8s	12MB	4.2MB
cat (no highlighting)	0.01s	0.5MB	N/A

Scrolling is instant. No lag. No beach balls.

Real-World Use Cases

Debugging Production Issues

You get paged at 2 AM. A service is failing.

# SSH into the server
ssh production-server

# Start following the logs
logchef -f /var/log/app/app.log

# Press `/` and type "ERROR" to filter only errors
# Press `l` to switch to error-only view
# Use arrow keys to scroll through the error context

You find the root cause in 30 seconds instead of 10 minutes.

Local Development

You're running a dev server and want to see errors only:

# Run your server in background
npm run dev &

# Follow logs, error-only
logchef -f --level error logs/combined.log

CI/CD Debugging

Your CI pipeline failed. You download the log artifact:

# CI artifact downloaded to build.log
logchef build.log

# Search for the first error
/ ERROR

# Jump to that line, scroll to see context

Getting Started

Installation

macOS / Linux (Homebrew):

brew install sulthonzh/tap/logchef

Manual download:

# Download from GitHub Releases
wget https://github.com/sulthonzh/logchef-zig/releases/latest/download/logchef-macos-arm64
chmod +x logchef-macos-arm64
mv logchef-macos-arm64 /usr/local/bin/logchef

From source:

# Requires Zig 0.13+
git clone https://github.com/sulthonzh/logchef-zig.git
cd logchef-zig
zig build -Doptimize=ReleaseSafe
zig build install

Basic Usage

# View a log file
logchef app.log

# Follow mode (live updates)
logchef -f app.log

# Filter by log level
logchef --level error app.log
logchef --level debug app.log

# Search inside the viewer (press /)
logchef app.log
# Press /, type pattern, enter
# Use n/N for next/previous match

What's Next

I'm planning:

Custom log format parsing (via CLI flags)
Log aggregation (multiple files at once)
Time-range filtering (logchef --from "2h ago" --to "now" app.log)

But even in its current form, logchef-zig has replaced grep and tail for me.

I Turned npm outdated into a CI Gate — Here's How

Sulthon Zainul Habib — Sun, 24 May 2026 17:20:15 +0000

You run npm outdated and see a list of stale packages. But your CI doesn't care. It passes anyway. Dependencies drift until something explodes in production. There's no built-in way to fail the build when versions drift too far.## The Problemnpm outdated lists outdated dependencies, but:- No exit codes — CI cannot gate builds on the result- No threshold configuration — you can't say "fail if >2 minors behind"- No distinction between prod and dev dependencies in many workflows- Manual updates become a fire drill instead of a controlled processA typical scenario: Your team wants to stay current with security patches, but you can't update everything. You need a rule: "No production dependency more than 2 minor versions behind latest." npm outdated can't enforce that.## The SolutionI built npm-outdated-check to turn npm outdated into a first-class CI citizen with:- Semantic version thresholding (major/minor/patch drift limits)- Meaningful exit codes (0 = pass, 1 = violation, 2 = config error, 3 = network error)- Configurable via CLI flags or a .npm-outdated-check.json config file- Production/dev dependency filtering- Multiple output formats (text, table, JSON)## How It WorksThe tool reads your package.json, queries the npm registry for each dependency, calculates the semantic version difference, and flags anything that exceeds your thresholds.Key implementation details:1. Registry fetching: Hit the npm registry endpoint for each package and extract the dist-tags.latest version2. Semver diff: Use semver to parse coerce(current) and parse(latest), then compute major/minor/patch differences3. Violation logic: A package violates if any diff exceeds its configured maxMajor/maxMinor/maxPatch4. Exit codes: CI reads the exit code and fails the build when violations existSample threshold calculation:

typescriptconst majorDiff = latest.major - current.major;const minorDiff = latest.minor - current.minor;const patchDiff = latest.patch - current.patch;const isViolation = majorDiff > config.maxMajor || minorDiff > config.minorDiff || patchDiff > config.maxPatch;

Getting StartedInstall globally or as a dev dependency:

bashnpm install -D npm-outdated-check

Run it in CI with sensible defaults (major=0, minor=2, patch=5):

bashnpx npm-outdated-check

Add it to GitHub Actions:

yamlname: Dependency Checkon: [push, pull_request]jobs: outdated-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '18' - run: npm install - run: npx npm-outdated-check --max-minor 3

If a dependency is 4 minor versions behind, CI fails and you get notified.## Why This Matters- Controlled updates: Set thresholds to avoid surprise breaking changes- Security posture: Enforce staying within N patch versions of latest- Team consistency: Config rules checked automatically in CI- Zero config: Works out of the box with smart defaults## What's NextRoadmap items include:- Configurable notification channels (Slack, email)- Automated PR generation for outdated packages- Support for Yarn and pnpm lockfiles- Monorepo workspace awareness## Links- GitHub: https://github.com/sulthonzh/npm-outdated-check- Try it: npm install -D npm-outdated-check

DEV Community: Sulthon Zainul Habib

Run Real Docker on Android — No Root, No Tricks, Just QEMU

Run Real Docker on Android — No Root, No Tricks, Just QEMU

What you'll need

The architecture (mental model)

Step 1: Install Termux (the right way)

Step 2: Set up SSH so you can work from your computer

2.1 Grant storage access (one-time)

2.2 Set a Termux password

2.3 Add your computer's SSH public key

2.4 Start the SSH server

2.5 Find your phone's IP

2.6 Set up SSH config on your computer

Step 3: Download Debian and build the cloud-init seed

3.1 Install QEMU and friends

3.2 Acquire a wake lock (CRITICAL — do not skip)

3.3 Download the Debian cloud image

3.4 Resize the disk

3.5 Create the cloud-init seed

Step 4: The QEMU launcher script

What each line does

Step 5: First boot (patience required)

Step 6: Install Docker inside the VM

6.1 Install Docker

6.2 Install Docker Compose v2

6.3 Let your user run Docker without sudo

6.4 Configure Docker for the slow VM

6.5 Add ZRAM swap (recommended)

6.6 Verify

Step 7: Make it survive phone reboots

7.1 Create the Termux:Boot scripts

7.2 Verify the scripts are registered

7.3 Test it (optional but recommended)

Step 8: Use it from your computer like it's local

8.1 Create a Docker context

8.2 The DOCKER_HOST gotcha (Mac users especially)

8.3 Test with a real compose stack

8.4 Common ways compose fails (and the fix)

8.5 (Optional) Make the phone the default context

I don't recommend this. It's surprising when you forget and accidentally build an image on the phone over Wi-Fi. Keep --context phone explicit.

Troubleshooting: the 5 things most likely to break

1. "QEMU died after my SSH disconnected"

2. "Docker pull fails with TLS handshake timeout"

3. "Termux sshd isn't running after reboot"

4. "The VM boots to a UEFI shell instead of Debian"

5. "Everything worked yesterday, but today it's broken"

What to do next

I Built an AI Code Reviewer That Runs on 240 Repos — And a Cron System That Keeps It Alive

The Code Reviewer That Started It All

The model routing bit

What it actually costs

The Secret Scanning Story

The Babysitter: OpenClaw Cron Fleet

The circuit breaker pattern

The Architecture (What Exists vs. What's Next)

What's next (honest roadmap)

Why Z.AI and Not OpenAI

Try It

I Stopped Switching Git Branches — And Started Using Worktrees Instead

The Problem With Branch Switching

Git Worktrees: The Concept

So I Built worktree-manager

The Commands That Actually Matter

Listing what you have

Cleaning up

Removing a specific worktree

Jumping between worktrees

How the Project Detection Works

A Real Workflow Example

Why Not Just Use Multiple Clones?

The One Catch

Wrapping Up

I Got Tired of Wiring Grafana + Loki + Tempo — So I Built a One-Command Observability Stack

What's in the box

The Go backend — where the magic happens

Why not just use Grafana?

Running it yourself

The sampling gotcha

What I'd like to add next

When to use this vs. managed services

I don't recommend this. It's surprising when you forget and accidentally build an image on the phone over Wi-Fi. Keep `--context phone` explicit.

The Action: `docker-remote-deployment-action`

`copy_stack_file: true` — Deploy from the server

`pull_images_first: true` — Pull before deploy

`docker_prune: true` — Automatic cleanup

`pre_deployment_command_args` — Run commands before deploy