Forem: Amir Reza Dalir

No Docker Here: Welcome to Singularity 🔬

Amir Reza Dalir — Wed, 25 Feb 2026 18:55:22 +0000

I just joined a new project — one that runs on a big HPC cluster. I opened the project README.md and saw something like this:

singularity exec docker://python:3.11 python train_model.py --data /shared/datasets/train

I had no idea what singularity was. 😅 So I did what felt natural — typed the Docker command instead:

docker run python:3.11 python train_model.py --data /shared/datasets/train

And the terminal replied with:

bash: docker: command not found

I messaged my project manager. His reply was short:

"We don't use Docker here. We use Singularity."

I stared at the message, thinking: "I have been using Docker for years. I know docker build, docker run, docker push like the back of my hand. And now none of that works here?"

That's how it all started.

🤔 "Why Not Docker?"

I loved Docker. Years of packaging apps in containers, deploying to production, running ML training pipelines. It was part of how I worked every day.

So I asked my project manager to install Docker on the cluster. His reply came quickly:

"We can't. There are legal reasons we can't use Docker here. Company policy. But also — Singularity is a better fit for what we do."

He didn't go into all the legal details, but explained the technical side in a Google Meet session. Docker needs a background daemon running all the time — a service that sits there waiting for your commands. On a shared HPC cluster where hundreds of researchers submit jobs, that adds complexity and overhead. Singularity doesn't need any daemon — you just run it directly. No background process. And you are the same user inside the container as you are outside. No switching to root, no permission confusion.

That last part sounded too good to be true. But it was true.

What?	Docker 🐳	Singularity 🔬
Main idea	Isolation (microservices)	Integration (HPC)
Background daemon?	Yes (always running)	No (daemonless)
Who are you inside?	root by default	Same user as host
Image format	Multi-layer, managed by daemon	Single `.sif` file
File access	Must mount volumes	Auto-mounts `$HOME`
Network	Isolated by default	Host network

💡 Docker wants to isolate your app from the system. Singularity wants to integrate your app with the system.

That made sense. I started learning Singularity and writing down every Docker command I knew next to its Singularity equivalent. This article is that cheat sheet.

📦 Image Management

First thing I needed was a Python image. In Docker, I would type docker pull python:3.11. In Singularity, the command is almost the same — with one small twist:

singularity pull docker://python:3.11

See that docker:// prefix? All my Docker Hub images still work. Every image I had ever used — GPU-enabled, data science, notebook servers — still available.

But instead of layers hidden in Docker's storage, I got a single file:

ls -lh python_3.11.sif
# -rwxr-xr-x 1 dalirnet dalirnet 385M Feb 25 09:15 python_3.11.sif

That .sif file is the image. A real file in my directory. I can cp it, scp it to another node, or rsync it anywhere. Try that with Docker — you need a registry, accounts, push, pull... With Singularity, you just copy a file.

Want to delete it? rm python_3.11.sif. No docker system prune, no dangling images.

Task	Docker 🐳	Singularity 🔬
Pull image	`docker pull ubuntu:22.04`	`singularity pull docker://ubuntu:22.04`
Build image	`docker build -t myimage .`	`singularity build myimage.sif myimage.def`
List images	`docker images`	`ls *.sif` (they're just files!)
Inspect image	`docker inspect myimage`	`singularity inspect myimage.sif`

▶️ Running Containers

In Docker, I would do docker run python:3.11 python script.py. In Singularity, the keyword is exec instead of run (run exists too — more on that in a second):

singularity exec python_3.11.sif python --version

Task	Docker 🐳	Singularity 🔬
Run a command	`docker run myimage cmd`	`singularity exec myimage.sif cmd`
Interactive shell	`docker run -it myimage bash`	`singularity shell myimage.sif`
Default command	`docker run myimage`	`singularity run myimage.sif`
Background	`docker run -d myimage`	`singularity instance start myimage.sif name`

📂 File System & Volumes

This is where Singularity first surprised me. I typed singularity shell python_3.11.sif, then ls — and saw all my files. My notebooks. My training scripts. My config files. Everything from my home folder, right there.

In Docker, you see an empty filesystem unless you mount your folder with -v. In Singularity, your home directory, current working directory, /tmp, and system paths like /proc and /sys are automatically available ✅.

So my old Docker habit:

docker run -v $(pwd):/workspace -w /workspace python:3.11 python analysis.py

Becomes just:

singularity exec docker://python:3.11 python analysis.py

No -v. No -w. Your current directory is already there.

When you need folders outside your home directory, use --bind:

singularity exec \
    --bind /shared/datasets:/data \
    --bind /scratch/$USER:/scratch \
    myimage.sif python train.py --data /data/train --output /scratch/checkpoints

You can also make binds read-only: --bind /shared/datasets:/data:ro.

Task	Docker 🐳	Singularity 🔬
Bind mount	`-v /host:/container`	`--bind /host:/container`
Current dir	`-v $(pwd):/app`	Already there
Read-only	`-v /host:/container:ro`	`--bind /host:/container:ro`
Multiple	`-v /a:/a -v /b:/b`	`--bind /a:/a,/b:/b`
Working dir	`-w /app`	`--pwd /app`

⚙️ Environment Variables

This one caught me off guard. In Docker, the container starts with a clean environment. If you need an API key inside, you pass it explicitly:

docker run -e API_KEY=abc123 myimage python train.py

Singularity does the opposite — it inherits your entire host environment by default ✅. Your $PATH, your custom variables — all available inside the container.

At first I thought this was great. Then I hit a bug where my container's Python was fighting with my host's Python paths because environment variables were leaking in. That's when I learned about --cleanenv:

# Clean environment — recommended for reproducible experiments
singularity exec --cleanenv myimage.sif python train.py

# Clean env + only the variables you need
singularity exec --cleanenv --env API_KEY=abc123 myimage.sif python train.py

# Or use an env file
singularity exec --cleanenv --env-file .env myimage.sif python train.py

My advice: always use --cleanenv for training runs. The inherited environment is handy for quick interactive work, but for anything reproducible, you want a clean slate.

Task	Docker 🐳	Singularity 🔬
Set variable	`-e VAR=value`	`--env VAR=value`
Inherit host env	No	Default
Env file	`--env-file .env`	`--env-file .env`
Clean env	Default	`--cleanenv`

🌐 Networking

In Docker, every container gets its own isolated network. Want to run a notebook server? You need port mapping:

docker run -p 8888:8888 mynotebook-image

In Singularity, there is no network isolation. The container uses the host network directly. Start a service on port 8888 inside the container, and it is on port 8888 on your machine. No mapping needed ✅:

singularity exec myimage.sif python -m notebook --port 8888

Running notebook servers, dashboards, monitoring tools — no more figuring out port mappings. Just start the service and go to localhost:port.

The downside? Two users on the same node starting something on port 8888 will conflict. But our cluster setup handles that by assigning different ports.

	Docker 🐳	Singularity 🔬
Default	Isolated bridge	Host network
Port mapping	`-p 8888:8888`	Not needed
Custom network	`docker network create`	Not available

🔄 Running Services (Instances)

Sometimes you need something running in the background — a notebook server, a database, a monitoring dashboard. In Docker, you use -d to detach. Singularity has instances:

Task	Docker 🐳	Singularity 🔬
Start	`docker run -d --name nb myimage`	`singularity instance start myimage.sif nb`
List	`docker ps`	`singularity instance list`
Stop	`docker stop nb`	`singularity instance stop nb`
Exec	`docker exec nb ls`	`singularity exec instance://nb ls`
Logs	`docker logs nb`	Check instance-specific logs

One important difference: in Docker, the daemon keeps your containers alive even if you log out. In Singularity, instances are tied to your session. If you disconnect from the cluster, they stop. For long-running services, you need a job scheduler — which is usually how HPC clusters work anyway.

📄 Definition Files

Every Docker user knows the Dockerfile. Singularity has its own version called a definition file (.def). Different structure, same idea — a recipe for building your image.

A Dockerfile:

FROM python:3.11-slim
RUN pip install numpy pandas scikit-learn matplotlib
COPY analysis.py /app/
WORKDIR /app
CMD ["python", "analysis.py"]

The same thing as a Singularity definition file:

Bootstrap: docker
From: python:3.11-slim

%post
    pip install numpy pandas scikit-learn matplotlib

%files
    analysis.py /app/

%environment
    export LC_ALL=C

%runscript
    cd /app
    exec python analysis.py

Dockerfile	Singularity	Purpose
`FROM`	`Bootstrap: docker` + `From:`	Base image
`RUN`	`%post`	Build commands
`COPY`	`%files`	Copy files in
`ENV`	`%environment`	Environment vars
`CMD`	`%runscript`	Default command
`ENTRYPOINT`	`%startscript`	Instance command
`LABEL`	`%labels`	Metadata
`WORKDIR`	Set in `%runscript`	Working dir

Most of the time, you don't need a .def file at all. If you already have a Docker image, convert it directly:

singularity build myenv.sif docker://myregistry/gpu-image:latest

I only started writing .def files when I needed a custom environment that didn't exist on Docker Hub. For everything else, docker:// was enough.

🧪 Sandbox Mode

When I need to experiment with new packages before committing to a build, I create a writable sandbox — a draft environment I can mess around in, then freeze into a clean image:

singularity build --sandbox myenv/ myenv.def   # create writable folder
singularity shell --writable myenv/             # shell in and install stuff
# pip install some-new-package
# python -c "import some_new_package"           # test it
sudo singularity build myenv.sif myenv/         # freeze when happy

In Docker, you would do docker run -it myimage bash then docker commit, but the sandbox approach feels more intentional.

🎮 GPU Access

This is where Singularity really shines.

In Docker, you need --gpus all:

docker run --gpus all gpu-image:latest python train.py

In Singularity, you add --nv:

singularity exec --nv gpu-image.sif python train.py

That's it. No nvidia-docker, no container runtime config, no Docker daemon GPU passthrough setup. Just --nv and your NVIDIA drivers are available. For AMD GPUs, it's --rocm.

Combined with a job scheduler, a typical training job looks like this:

singularity exec --nv \
    --bind /shared/datasets:/data \
    --bind /scratch/$USER:/scratch \
    gpu-image.sif \
    python train.py \
        --data /data/train \
        --output /scratch/checkpoints \
        --epochs 100 \
        --batch-size 512 \
        --gpus 4

Submit the job and check the results later.

GPU	Docker 🐳	Singularity 🔬
NVIDIA	`--gpus all`	`--nv`
Specific GPU	`--gpus '"device=0"'`	`CUDA_VISIBLE_DEVICES=0`
AMD	`--device /dev/kfd --device /dev/dri`	`--rocm`

📤 Registry & Sharing

In Docker, sharing an image means pushing to a registry. Both sides need accounts and permissions.

In Singularity, you can push to the Singularity Library:

singularity remote login
singularity push myimage.sif library://myname/default/myimage:v1.0

But what I actually do: just copy the file.

cp myimage.sif /shared/containers/team-env.sif

Anyone on the cluster can run singularity exec /shared/containers/team-env.sif python train.py and get the exact same environment. Same packages, same versions, same GPU libraries. No registry, no login. Just a file on a shared filesystem.

Task	Docker 🐳	Singularity 🔬
Login	`docker login`	`singularity remote login`
Push	`docker push user/image:tag`	`singularity push image.sif library://user/image:tag`
Share	Push to registry	Copy the `.sif` file

🎼 Multi-Container Orchestration

Singularity has no built-in docker-compose alternative ⚠️. If you come from a world of docker-compose up with web servers, databases, and caches all wired together, this will feel like a step back.

But on HPC, you usually don't need it. Most workloads are single-container jobs. Your training script runs inside one environment, reads data from shared storage, and writes checkpoints to scratch space.

When you do need multiple services, you have a few options:

📜 Option 1: A simple shell script. Start each service as a Singularity instance, connect them through localhost (since they share the host network):

#!/bin/bash
singularity instance start postgres.sif db
sleep 5
singularity instance start --env DATABASE_URL=postgresql://localhost/mydb tracker.sif tracker
singularity instance list

🔧 Option 2: singularity-compose — a community tool that reads YAML files similar to docker-compose.yml. It works for simple setups, but it is not actively maintained.

Feature	Docker Compose	Singularity Compose
Network isolation	✅ Full	❌ Host only
Service discovery	✅ DNS	⚠️ Limited
Health checks	✅ Built-in	❌ Manual
depends_on	✅ Full	⚠️ Limited
Secrets	✅ Built-in	❌ Env vars
Production ready	✅ Yes	⚠️ Not actively maintained

🔍 Troubleshooting

Here are the problems I hit and how I solved them:

🐍 Host Python leaking in — my $PYTHONPATH and other environment variables were being inherited by the container, causing import errors. Fix: always use --cleanenv for training runs.

✏️ "Read-only file system" errors — Singularity images are read-only by default. If your script tries to write to /opt or /usr, it will fail. Fix: write to $HOME, use --bind, or use sandbox mode.

🔌 Port conflicts — two users starting a service on the same port will conflict since Singularity shares the host network. Fix: always pick a random port, or let your job scheduler assign one.

💾 Disk space — .sif files can be large (multi-GB for GPU images) and there is no layer sharing. Fix: keep shared images in /shared/containers/ instead of each person having their own copy.

Problem	Docker fix 🐳	Singularity fix 🔬
Permission denied	`--user $(id -u):$(id -g)`	Shouldn't happen (same user)
Can't write to a path	Mount a volume	Use `$HOME`, `--bind`, or sandbox
Port in use	Change port mapping	Pick a different port
Out of space	`docker system prune`	`rm *.sif` or use shared images
Wrong Python version	Check base image	`--cleanenv` to stop host env leaking in
Package not found	Install in Dockerfile	Install in `%post` or use sandbox

💡 What I Learned

Where Singularity wins

No daemon — just run it
Single-file images — cp for instant reproducibility
Same user inside and outside — no permission headaches
Simple GPU access — just --nv
Works on shared HPC clusters without special privileges

Watch out for

Building images needs root (--fakeroot or --remote as workaround)
No network isolation
No built-in compose/orchestration
No layer caching — full rebuild every time
Host environment can leak in — always use --cleanenv

🎬 The End

That command not found on my first day scared me. I thought none of my Docker experience would transfer.

But it did 😊. Every Docker image still works — just add docker:// in front. Every concept — images, containers, mounts, environment variables — still applies. Same mental model, different tool.

Singularity taught me something unexpected: isolation is not always the goal. Docker keeps containers separate from the host. But on a shared cluster, you actually want the container to feel like part of the system. You want your files there. You want the GPU drivers to just work. You want to submit a job and not worry about daemon sockets and port mappings.

My workflow now: Docker on my MacBook for local testing. Singularity on the cluster for real training. Same images, same Dockerfiles, different last mile.

They are not competitors. They answer different questions:

🐳 Docker: "How do I isolate this app?"
🔬 Singularity: "How do I bring this app into the researcher's environment?"

Sometimes the second question is the right one.

If you found this useful, follow me here on dev.to and check out my GitHub.

You Just Want Containers — Why Is Installing Docker & Podman Still This Hard?

Amir Reza Dalir — Mon, 23 Feb 2026 11:14:47 +0000

It's 11 PM. Your deadline is tomorrow. The model is ready, the compose file is written, and all you need is docker compose up. But you're staring at a fresh Ubuntu VM and Docker isn't installed.

No problem, right? Just install it.

sudo apt-get install docker.io

Except the version in the repo is two years old. The docs say to add Docker's official repository. So you start adding GPG keys, configuring apt sources, updating package lists... fifteen minutes later, Docker is running. You pull your image, start the stack, and finally get to work.

That was the easy version. 😅

What if you could just type docker + podman and have it work — anywhere?

When the easy version doesn't exist

🔬 The researcher. You're on a university HPC cluster with a containerized pipeline — a deep learning training job, a genomics workflow, a physics simulation. You need Docker or Podman. But you don't have sudo. You can't install packages. The sysadmin takes days to respond to tickets. Your deadline doesn't care.

🧠 The ML engineer. You're spinning up GPU instances on a cloud provider. The VM comes with a minimal OS — no apt, no yum, no package manager at all. Just a kernel and a shell. You need Docker, but the official install script assumes you have a full distro underneath.

🔒 The restricted environment. You're working in a secure facility. The machines are air-gapped — no internet. You can transfer files in via USB, but every tool you need has to be bundled and self-contained.

🔀 The mixed-runtime team. Your team standardized on Podman for security reasons, but half your tooling still expects Docker. You need both, and switching between them shouldn't require reconfiguring everything.

These aren't edge cases. For researchers, data scientists, and engineers working outside the typical cloud-native setup — this is everyday reality.

The official path is paved, but narrow

Docker does provide a convenience script:

curl -fsSL https://get.docker.com | sh

It's well-maintained and it works. But it needs sudo. It needs a package manager. It needs internet access. It only supports specific distributions. And it only installs Docker — no Podman, no rootless mode out of the box.

For Podman, the story is worse. There's no get.podman.com. Your options are distro packages (often outdated, sometimes missing entirely) or building from source. That means cloning seven separate repositories — Podman itself, plus crun, conmon, netavark, aardvark-dns, slirp4netns, and fuse-overlayfs — and compiling Go, Rust, and C code. On a machine where you can't even sudo apt install gcc, that's a dead end. 🛑

And Compose? That's another installation step on top of everything else.

The tools exist. The documentation exists. But the path from "I need containers" to "I have containers" is full of assumptions about your environment that don't always hold.

Removing the assumptions

dockpod (docker + podman, quick setup) was built around a simple idea: installing a container runtime should work the same way everywhere.

curl -fsSL diphyx.github.io/dockpod/setup.sh | bash
dockpod install

That's the entire setup. An interactive menu asks which runtime you want — Docker, Podman, or both. Compose is included automatically with either choice. No sudo required. No package manager. No GPG keys. No repository configuration.

It works on any Linux system with kernel 4.18+ and systemd — which covers essentially every modern distro and cloud image. ✅

Under the hood

When you run dockpod install, it checks your system, detects your architecture, and pulls prebuilt static binaries — the same ones compiled from the official upstream sources. It places them in the right directories, writes configuration files, sets up systemd services, and verifies the installation by actually running a container.

🛡️ If you have root, binaries go to /usr/local/bin/ and services run system-wide. If you don't, everything goes into ~/.local/bin/ and runs as user-scoped systemd services. Docker uses its rootless mode, Podman works rootless natively. Either way, you end up with a fully working runtime without ever typing sudo.

🔌 Compose is included out of the box — installed as both a standalone docker-compose binary and a Docker CLI plugin (docker compose). When Podman is installed, dockpod creates a podman-compose symlink automatically, so your existing compose files work with either runtime:

docker compose up -d       # with Docker
podman-compose up -d       # with Podman — same file, no changes

🔀 Need both Docker and Podman? Install both, then switch between them instantly. Your compose files, your scripts, your muscle memory — everything stays the same. Only the engine underneath changes.

dockpod switch podman
dockpod switch docker

No internet? No problem

This is the part that matters most for restricted environments.

dockpod publishes architecture-specific tarballs with every release. Each one is self-contained — Docker, Podman, Compose, and all their dependencies bundled together. Nothing is downloaded during installation.

Grab the tarball on a connected machine, transfer it however you can — USB, scp, a shared drive — and install on the target without a single network call:

tar -xzf dockpod-v2.0.0-amd64.tar.gz && cd dockpod-v2.0.0-amd64
./dockpod.sh install --offline

For labs, secure facilities, and isolated clusters, this is often the only practical way to get containers running without a lengthy approval process.

Give it a try

If you've ever spent more time installing a container runtime than actually using it — that's exactly what dockpod is for.

If it saves you time, share it with your team, your lab, or that colleague who's still struggling to get containers running.

GitHub · MIT licensed · Built by DiPhyx

Your Cheap Home Router Has a Hidden CLI — Here's How I Found It

Amir Reza Dalir — Fri, 13 Feb 2026 08:43:24 +0000

🏚️ Chapter 1: The Budget

Let me set the scene.

Most of us don't get to choose our router. Your ISP comes to your house, puts a white plastic box on the wall, gives you a paper with the WiFi password, and leaves. That's it. That's your whole network now.

My box was a Huawei HG8240. A GPON terminal. This kind of device exists in millions of homes across Asia, the Middle East, South America — anywhere ISPs buy hardware in bulk and give it away for almost nothing. It's cheap. And it looks cheap too.

The Web UI: A Beautiful Prison

Every router comes with a web UI. You open a browser, type an IP address, and you get an admin panel. Fine.

But here's what nobody tells you: the web UI doesn't show you everything your router can do. You get WiFi settings, a MAC filter table, maybe port forwarding if you're lucky. The rest — advanced routing, VLAN management, QoS controls, real firewall rules, diagnostics — is either hidden behind an "advanced" tab that barely works, or just not there at all.

And some of these web UIs... okay, I don't want to insult anyone's work, but — frames inside frames. Pages that fully reload on every click. Buttons that do nothing when you press them. Session timeouts that kick you out while you're still typing a MAC address.

You learn to be fast and hope nothing crashes. It's not network administration — it's speedrunning.

The Real Problem: Humans Required

But the bad design is not even the worst part. The real problem is more basic than that:

A web UI needs a human.

Every action needs your hands and your eyes. You can't write a script for it. You can't automate it. You can't connect it to anything else.

Want to add 10 devices to the whitelist? That's 10 rounds of click, type, save, wait, repeat. Want a script that blocks all devices at midnight and turns them back on in the morning? Not possible. Want to connect your router to your smart home or a monitoring tool? The web UI says: "No. Sit down. Click the button. Wait for the page to reload. That's your life now."

For a technical user, this is a dead end. A wall. A cage made of <iframe> tags.

The "Easy" Solution

Now, there's always the obvious answer: go to a store, drop your money, and buy a MikroTik RouterBoard. Problem solved. CLI out of the box. Full control. Done. 💸

And if money is no problem, why stop there? Get a Cisco managed switch. Get a rack. Get a server room. Put on a suit. Become a network engineer. Problem really solved.

But back in reality — where the ISP already gave us a router for free and we'd rather spend that money on coffee ☕ — let's work with what we have.

What If There Was Another Way?

A CLI changes everything. Every command the router supports — available directly. You can write scripts. You can automate tasks. You can connect it to other tools. You could set up your whole network in seconds instead of clicking through fifteen slow pages.

That's not a nice-to-have — that's the difference between controlling your router and being stuck with it.

And I was definitely stuck. Every time a new device needed WiFi access — open browser, type 192.168.1.1, log in, go through three menus, type a MAC address, click save, hope it works. Every. Single. Time.

Meanwhile, MikroTik and Cisco users had one-line CLI commands. Clean. Scriptable. Well documented.

And me? Clicking through a web panel like it was 2008. Because I had the budget router. The one nobody makes CLI tools for. The one nobody writes docs for. The one that's supposed to sit in the corner and never be questioned.

But I'm a developer. I question things.

🔍 Chapter 2: The Suspicion

It started with a port scan.

I don't remember exactly why I ran it — maybe I was bored, maybe curious, maybe it was one of those late nights where developers do things they probably shouldn't with nmap.

$ nmap 192.168.1.1

And there it was in the output. Something unexpected.

Port 22. Closed.

Not filtered (that means a firewall is hiding it). Not absent (that means the service doesn't exist). Closed — that means something is right there, but it's not accepting connections.

Like a door that's locked, but you can see there's a room behind it.

SSH. On my cheap home router.

My heart beat a little faster. I tried to connect:

$ ssh root@192.168.1.1
ssh: connect to host 192.168.1.1 port 22: Connection refused

Connection refused. Of course. 😑

But now I knew there was a door. I just needed to find the key.

📚 Chapter 3: The Documentation Nightmare

This is where the story gets painful.

I started looking for official Huawei documentation for the HG8240 series. What I found was... almost nothing useful.

Language	Usefulness
Chinese	Detailed — if you can read it
Portuguese	Brazil-specific firmware only
English	Machine-translated, barely usable
Russian	Random blog posts, hit or miss
Indonesian	"It works!" (no explanation)

There was no "Developer Guide." No "CLI Reference." No simple README with examples. Just small pieces here and there — a forum post from someone in Indonesia who said they enabled SSH but didn't explain how, a Russian blog with screenshots of XML files that looked useful but led nowhere, and PDFs. So many PDFs.

Seriously — PDFs. In 2026. Not a web page, not a wiki, not even a text file. PDFs. And not small ones — each one over 10MB, full of screenshots of admin panels I've never seen, for firmware versions I don't have, about features I wasn't looking for. I downloaded about a dozen of them. Opened each one hoping to find a CLI reference. Got 200 pages about how to set up PPPoE through the web panel instead. Thanks, Huawei.

I spent hours. Real hours. Not the "I searched for five minutes" kind. The kind where you have too many browser tabs open, half of them in Google Translate, comparing a Chinese PDF with a Portuguese forum thread because they both describe the same XML setting but with different names.

The Hard Truth

Here's what I want to say clearly: this is normal for consumer routers.

Huawei, ZTE, TP-Link — they all do this. They don't write documentation for people like us. Their real customer is the ISP, not the person at home. The ISP gets proper guides and setup tools. We get a web panel and nothing else.

But just because they don't tell you about something doesn't mean it's not there. It just means nobody thought you'd go looking.

The engineers who build these devices still leave traces behind. Config files have patterns. Firmware has help commands. Ports show up in scans. The information is out there — hard to find, badly written, in the wrong language — but it exists.

You just have to want it badly enough.

🔓 Chapter 4: The Configuration File

The answer came from the last place I expected: the web panel itself.

Yes, the irony was not lost on me.

I logged into the admin panel — not with the regular user, but with telecomadmin / admintelecom, the ISP-level account that most people never use. I went to:

Advanced → Maintenance Diagnostic → Configuration File Management

And there it was. A small button to download the router's full configuration as a file.

I had ignored it many times before. But I was desperate enough to try anything. I downloaded it. Made a backup copy first (always do this). Opened it in my IDE and... XML. Thousands of lines of XML.

Now — I got really lucky here. Some Huawei routers encrypt the config file when you export it. You download it, open it, and instead of readable XML you see random characters. Useless.

If that had happened to me, honestly? I probably would have closed my laptop and moved on with my life. Mystery over. The web panel wins.

But my config came out as plain, readable XML. That small bit of luck is the only reason this article exists.

A note for anyone following along — if your config file is encrypted, don't give up. People have already figured this out. There are Gists on GitHub with scripts that can decode and re-encode config files for different Huawei models. The process is: download the encrypted config → decode it with the script → make your changes → encode it back → upload it. Search for "huawei config decrypt HG8245" or "huawei gpon config encode decode" on GitHub Gists — people have been sharing these tools for years.

Anyway, back to my config. I started scrolling. And somewhere around line 400, in that wall of angle brackets, I found this:

<X_HW_CLISSHControl Enable="0" port="22" Mode="0" AluSSHAbility="0"/>

I stared at it. Read it again. Read it a third time.

But let me tell you about the journey to find that line. Scrolling through this XML felt like Huawei was trying to break me personally. Thousands of lines of nested tags, no comments, no clear sections, no formatting. It looked like it was created by a machine that had never heard of indentation. I'm pretty sure this config format is older than most programming languages I use.

Anyway — back to the discovery:

SSH was not missing. It was not unsupported. It was just... turned off. In some firmware versions the line is there with Enable="0". In others it doesn't exist at all — you have to add it yourself. Either way, the feature is built into the firmware. It just needs to be turned on.

I kept reading. Found another flag:

<AclServices ... SSHLanEnable="0" ... />

Two zeros. Two flags. That's all that stood between a "dumb" web-only router and one with a full command-line interface.

The Surgery

The fix was almost too simple:

Step 1 — Add or change the X_HW_CLISSHControl line to Enable="1". Make sure to place it before X_HW_CLITelnetAccess in the XML:

<X_HW_CLISSHControl Enable="1" port="22" Mode="0" AluSSHAbility="0"/>

Step 2 — Find SSHLanEnable and change the zero to one:

<AclServices ... SSHLanEnable="1" ... />

Step 3 — Upload the changed config through the same admin page. The router rebooted on its own.

Then I waited. Watched the lights blink. Watched them go steady. Opened my terminal. And typed:

$ ssh -o HostKeyAlgorithms=+ssh-rsa -o PubkeyAcceptedKeyTypes=+ssh-rsa root@192.168.1.1
root@192.168.1.1's password: ********

The -o HostKeyAlgorithms=+ssh-rsa flags are needed because these routers use an older SSH algorithm that new SSH clients block by default. Also, only the root user can connect — the password is printed on the back of the device.

And then...

WAP>

A prompt. A real command prompt. On my budget router. 🎉

I typed help. A long list of commands appeared — WiFi, routing, VLAN management, diagnostics. This router had a whole operating system hiding behind that web panel the entire time.

WAP> display wifi filter                                # List filtered devices
WAP> add wifi filter index 1 mac AA:BB:CC:DD:EE:FF     # Whitelist a device on SSID-1
WAP> del wifi filter index 1 mac AA:BB:CC:DD:EE:FF     # Remove from whitelist

The locked door was open. And the room behind it was huge.

🚀 Chapter 5: Now What?

The CLI was open. And suddenly, everything that was impossible through the web UI became easy.

I could write a bash script to add ten devices in two seconds. I could set up a cron job to block everything at midnight. I could send the output of display wifi filter to grep and build a monitoring tool. The CLI turned my "dumb" router into something I could actually write code against.

And that's what I did — I wrapped these SSH commands into a small macOS app called WMac using Expect scripts to handle the old SSH connection. But that's just one example. The point isn't the app — the point is that once you have CLI access, you can build anything on top of it.

The locked door led to a whole building.

🌍 Chapter 6: The Bigger Mystery

Here's where I stop talking about my story and start talking about yours.

I did all of this on one router — the Huawei HG8240 — because that's what I have at home. I don't have a ZTE. I don't have a TP-Link. I can't test them, so I won't pretend to know what's inside them.

But here's what I believe: most cheap home routers are hiding something like this.

These devices are not built from zero. They share the same chips, the same firmware base, the same design. The same factories in Shenzhen that make Huawei's GPON terminals also make ZTE's, and many other brands you've never heard of. If Huawei's firmware has SSH built in but turned off, there's a good chance the router on your shelf does too.

The problem is always the same — nobody tells you. The docs are bad, in the wrong language, written for someone else, about a different firmware version, on forums in countries you've never been to, in threads from 2019.

But the information is out there. That's the biggest thing I learned from this whole experience. Bad documentation doesn't mean no documentation. The answers are just harder to find. But they can be found.

🎬 Your Turn

That's my story. One cheap router. One hidden CLI. A lot of bad docs and late nights.

But the real point of this article is not about my router — it's about yours. Here's a simple guide to start:

Step	What to Do	What to Look For
1	`nmap 192.168.1.1`	Closed ports (not filtered — closed)
2	Download config from admin panel	XML/JSON with disabled settings
3	Search for `Enable="0"`	SSH, Telnet, SNMP — anything turned off
4	Read the bad docs	Google Translate is your friend
5	Get a shell, type `help`	See what commands are available

The worst thing that can happen is you learn something about your router. The best thing? You find a whole hidden interface that was always there, waiting for someone curious enough to look.

I solved this mystery for one router. There are thousands of models out there that nobody has looked into yet. If you've explored your cheap home router and found hidden features — SSH on a ZTE, telnet on a TP-Link, a CLI on some ISP box nobody knows about — tell me in the comments.

The more you share, the fewer people have to suffer through web panels.

Sometimes the cheapest hardware has the best-hidden secrets. You just have to read the bad docs.

The tool I built from this is open source: github.com/dalirnet/wmac — give it a ⭐ if this was useful.

Follow me on GitHub @dalirnet for more weekend hacks like this.

Your Resume Deserves Better Than a Black Hole

Amir Reza Dalir — Thu, 12 Feb 2026 16:15:01 +0000

Every day, thousands of resumes disappear into inboxes, portals, and applicant tracking systems — never to be heard from again. No read receipt. No engagement data. No signal at all.

We believe your resume deserves better than that. And we built CVinci to prove it.

But first, let us tell you about a developer we know.

🕳️ Into the Black Hole

He's a web developer with a computer science degree, real-world projects, and three years of experience at a company in Austin. He was looking for his next remote role — flexible on the company, as long as it was US-based.

He spent a weekend rewriting his resume, exported a clean PDF, and started applying. By the end of the month, he had sent it to 25 companies.

Then — silence.

What he expected	What actually happened
Acknowledgment that someone received his file	Nothing
Feedback on whether his CV was a fit	Nothing
Knowing if anyone even opened the PDF	Nothing

25 applications. Zero visibility. Every one felt like shouting into a void.

We've heard this story from hundreds of people. It's the norm — and it shouldn't be.

📁 The Mess Behind the Scenes

He was tailoring his resume for different roles. Within two weeks, his laptop looked like this:

Resume_v3_final.pdf
Resume_frontend_updated.pdf
Resume_startup_FINAL_v2.pdf
Resume_startup_FINAL_v2_revised.pdf

And his supporting materials were scattered everywhere:

Document	Location
CV versions	Local folder
Cover letters	Email drafts
Portfolio	Separate website
Certifications	Downloads folder

Every time a recruiter asked for the "full package," he spent twenty minutes hunting for files and hoping he grabbed the right versions. We know this pain — it's one of the first problems we set out to solve.

📊 The Data Gap No One Talks About

One evening, his friend in marketing mentioned that their team tracks open rates, click-through rates, and engagement time on every email they send.

Our developer thought about his 25 job applications.

He had less insight into his career-defining document than his friend had into a promotional newsletter.

We thought about this too:

Metric	Marketing email	Traditional resume
Was it opened?	Yes	No idea
How long did they read?	Yes	No idea
Did they click anything?	Yes	No idea
Where is the reader located?	Yes	No idea
Which version performs best?	Yes	No idea

Your resume is the most important document in your job search. Why does it have less analytics than a marketing email?

That question is exactly what pushed us to build CVinci.

💡 Out of the Black Hole

He found CVinci and decided to give it a try. The process took about two minutes:

Uploaded his existing PDF
Our AI extracted his work history, education, skills, languages, and certifications — automatically
Picked a template and customized colors and fonts
Attached his cover letter and portfolio as downloadable files
Got his link — a clean, personalized URL

One link. Everything a recruiter needs. No more black hole.

👀 Finally — Visibility

Two days later, he opened his CVinci dashboard.

For the first time, he could actually see what happened after he hit send:

Viewer	Location	Time spent	Engagement	Action
Recruiter A	Chicago, IL	1 min 42 sec	Deep Dive 🔥	Downloaded portfolio
Hiring Manager B	Denver, CO	3 visits in 48 hrs	Deep Dive 🔥	Viewed all sections
Company C	Seattle, WA	4 seconds	Quick Glance 👀	Left immediately

What the data told him:

🔥 Chicago — strong signal. Recruiter spent real time and downloaded files. Worth a follow-up.
🔁 Denver — came back three times. Serious interest he would have never known about with a static PDF.
👋 Seattle — four seconds and gone. Not the right fit. Move on.

His resume was no longer in a black hole. It was a live, trackable page with real data behind it.

🔄 From Guesswork to Strategy

With real numbers, he started experimenting. He created a second CV version for startup roles — different template, revised summary, separate link.

After one week, the data was clear:

Version	Avg. view time	Scroll to bottom	Downloads
General	38 sec	41%	12%
Startup-focused	1 min 14 sec	67%	29%

He doubled down on the startup version.

We designed CVinci so anyone can A/B test their job search — something that was never possible when your resume lived in a black hole.

📬 The Right Follow-Up at the Right Time

The feature that surprised him most — our live notifications. The moment someone opened his page, he knew. When someone downloaded his portfolio, he saw it instantly.

One afternoon:

🔔 A recruiter from his top-choice company opened his CV
👀 She spent two full minutes reading
📥 She downloaded both his cover letter and portfolio
✉️ He sent a follow-up email within the hour
📞 He got an interview the next day

When your resume is in a black hole, you can't time your follow-ups. When it's on CVinci, you can.

🎯 Black Hole vs. CVinci

The black hole	CVinci
Send a PDF and hope for the best	Share a trackable link and see what happens
Zero visibility after sending	Real-time view notifications
No idea which version works	A/B testing with engagement data
Scattered files across folders	Everything bundled in one link
Follow-ups based on guesswork	Follow-ups based on actual engagement

Eight weeks later, he accepted an offer from the Chicago recruiter — the one who downloaded his portfolio on day two.

We built CVinci for developers like him. And we think you might be one of them.

⚡ What We Built

Core features:

AI Content Extraction — upload a PDF, Word doc, or image. Our AI structures your content automatically
Personalized URL — every CV gets a clean link like cvinci.me/your-name
Multiple Templates — switch styles without re-entering data
File Attachments — bundle up to 3 supporting documents per CV
Access Control — toggle between public and private with one click

Analytics you get for every view:

Data point	Example
Engagement level	Quick Glance / Considered / Deep Dive
Time spent	1 min 42 sec
Location	Chicago, IL — plotted on map
Platform	Chrome on macOS
Referrer	LinkedIn / Email / Direct
Downloads	Portfolio.pdf downloaded
Timestamp	Feb 12, 2026 at 3:14 PM

What makes us different:

Most resume tools help you build a CV.
We help you build, share, track, and optimize it.

🚀 Get Started

Step	What happens
1	Sign in with Google, GitHub, or LinkedIn
2	Upload your existing resume
3	Review the AI-extracted content
4	Pick a template and customize
5	Share your personalized link
6	Track views from your dashboard

Free. No credit card. No setup wizard. Takes about two minutes.

Your resume deserves better than a black hole.

Try CVinci →

When Your Country Blocks the Internet, You Build Your Own Path

Amir Reza Dalir — Thu, 12 Feb 2026 10:20:05 +0000

I'm a developer unfortunately living in a country where the government blocks access to most of the internet — Twitter, YouTube, GitHub (sometimes), messaging apps, news sites... all filtered. Millions of people deal with this every single day.

The obvious solution? A VPN server somewhere abroad. Spin up an instance on AWS or Hetzner, install a VPN, connect from home. Simple, right?

Except it doesn't work. ❌

Local ISPs actively detect and block VPN protocols. Even if you get a connection working, the foreign IP gets blacklisted within days. You set it up, it works for a week, then it's dead. Start over.

🔍 The Real Problem

You can't connect directly to a foreign server running a proxy. The connection gets detected and killed — not always, but almost mostly. But here's the thing — not all networks are filtered equally. Each ISP behaves differently, and filtering varies from city to city. One ISP might block everything, while another provider in a different city lets certain traffic through.

This means your middle server doesn't have to be in a datacenter. It can be:

🏠 A home server on a different ISP
🏙️ A friend's machine in another city with a static IP
💰 A cheap VPS at a local hosting provider

As long as it can reach both your device and the foreign server, it works as an EDGE.

The filtering mostly targets end-user residential connections to foreign IPs. Internal traffic — between ISPs, cities, datacenters — is far less restricted.

So the solution is a chain:

📱 Your phone/laptop ➜ 🔗 Middle server (EDGE) ➜ 🌍 Exit server (GATEWAY) ➜ 🌐 Free internet

Your device connects to the middle server (fast, low latency, not blocked). That server forwards everything to your exit server abroad. The exit server fetches the content and sends it back through the chain.

This is exactly what I've been working on.

⚡ Xray Chain Proxy

This tool is built on top of Xray-core — one of the most powerful and battle-tested proxy platforms out there. Xray supports advanced protocols, encryption, and routing that make it extremely hard to detect and block. But configuring it manually is painful — JSON config files, multiple protocols, user management, all by hand, and repeating the whole process every time a server gets blocked.

So I wrote a single bash script that wraps all of Xray's power into simple commands.

Two servers, two commands:

# On your foreign server (e.g., AWS in Frankfurt)
./xcp.sh setup gateway

# On your local server (inside your country)
./xcp.sh setup edge

That's the entire setup. ✅

The gateway setup configures your exit node — the server with free internet. It gives you the IP, ports, and a password.

Then you enter those details on the edge server (the local one). The encrypted chain between the two is established automatically.

🏗️ How the Architecture Works

┌────────┐      ┌────────┐      ┌─────────┐      ┌──────────┐
│ Client │ ──── │  EDGE  │ ──── │ GATEWAY │ ──── │ Internet │
│ (You)  │      │(Local) │      │  (AWS)  │      │          │
└────────┘      └────────┘      └─────────┘      └──────────┘

Server	Location	Role
EDGE	Local datacenter / home server	🚪 Entry point — your devices connect here
GATEWAY	Foreign server (AWS, Hetzner, etc.)	🌍 Exit point — fetches content from the internet

Why this works:

🟢 EDGE is local — your ISP sees a connection to a local IP, nothing suspicious
🔒 GATEWAY is hidden — censors never see it directly, only the EDGE talks to it
🔐 Traffic is AES-256-GCM encrypted between EDGE and GATEWAY
🔄 If EDGE gets blocked — spin up a new server, run one command, done in 2 minutes
🛡️ GATEWAY stays safe — it never changes, no one knows about it except your EDGE

📡 3 Protocols at Once

Each server runs three protocols simultaneously:

Protocol	Port	Best For
Shadowsocks	`443`	📱 Mobile apps (v2rayNG, Shadowrocket), looks like HTTPS
HTTP	`80`	🌐 Browser proxy, curl
SOCKS5	`1080`	💻 System-wide proxy on desktop

All share the same username and password. Connect with whatever works best for your device.

👥 Adding Users

I share my proxy with family and friends. Adding a new user takes seconds:

./xcp.sh user add

It generates the credentials, a QR code (scan with your phone), and a Shadowsocks URI you can share directly.

📊 Monitoring

When you share with others, you want to know what's happening.

Check if everything is running

./xcp.sh status

See who's using how much bandwidth

./xcp.sh stats

Test the full chain

./xcp.sh test

This verifies the chain is working and shows the exit IP (should be your GATEWAY's IP) plus speed measurements.

🧭 Smart Routing

Not everything needs to go through the foreign server. Local websites work fine directly — routing them through AWS just adds latency for no reason.

./xcp.sh rule add

Real examples I use:

🏠 Local sites direct (no proxy needed): geosite:ir as direct
🚫 Block ads: geosite:category-ads-all as blocked
🌐 Social media through proxy: twitter.com, instagram.com, youtube.com as proxy

This way, local sites stay fast and only filtered content goes through the chain.

📖 Documentation

Full documentation is available in English and Persian:

🇬🇧 English Docs
🇮🇷 Persian Docs

Covers all commands, configuration options, routing rules, and more.

🔄 When the EDGE Gets Blocked

It happens. The local server's IP gets flagged and your connection drops. Here's my workflow:

Spin up a new VPS at a local datacenter (takes 1 minute)
Download the script: curl -sL ... -o xcp.sh && chmod +x xcp.sh
Run: ./xcp.sh setup edge
Enter the same GATEWAY details
Done. New EDGE, same chain, 2 minutes total ⏱️

The GATEWAY never changes. Only the EDGE rotates. Your users just update the server IP and they're back online.

📦 Requirements

Debian/Ubuntu with root access
512 MB RAM, 1 CPU (cheapest VPS works)
Dependencies (curl, jq, unzip) are auto-checked
Works on x86_64, ARM64, and ARM32

🚀 Get Started

curl -sL https://raw.githubusercontent.com/dalirnet/xray-chain-proxy/main/script.sh -o xcp.sh
chmod +x xcp.sh
./xcp.sh setup gateway  # on foreign server
./xcp.sh setup edge     # on local server
./xcp.sh user add       # create your account

GitHub: github.com/dalirnet/xray-chain-proxy
Docs: dalirnet.github.io/xray-chain-proxy

This tool exists because I needed it. If you're in a similar situation — Iran, China, Russia, or anywhere else with internet restrictions — I hope it helps. ⭐ A star on GitHub helps others find it.

I Built a Native macOS Authenticator App Because I Was Tired of Reaching for My Phone

Amir Reza Dalir — Wed, 11 Feb 2026 07:37:15 +0000

You're working on your Mac, logging into a service, and then — "Enter your verification code." You stop. You reach for your phone. You unlock it. You open the authenticator app. You squint at tiny digits. You type them in before the timer runs out. If you're lucky, you make it. If not, you wait for the next code and do it again.

I got tired of this, so I built Mactokio (Mac + Token + I/O) — a free, open-source authenticator that lives right on your Mac.

What is Mactokio?

Mactokio is a lightweight authenticator app built natively for macOS. It generates the same verification codes as Google Authenticator or Microsoft Authenticator — but directly on your desktop. No phone needed.

Free. Open source. Offline. Your secrets never leave your Mac.
No cloud. No account. No subscription.

Why Not Just Use What's Already Out There?

Most authenticator solutions fall into two camps:

	Phone-only apps	Cloud-synced apps	Mactokio
Examples	Google Authenticator, Microsoft Authenticator	Authy, 1Password	—
Works on Mac?	No	Yes	Yes
Secrets stored	On your phone	On their servers	On your Mac only
Requires account?	No	Yes	No
Cost	Free	Free / Paid	Free
Open source?	No	No	Yes

Mactokio is the third option: your codes, on your Mac, encrypted on your disk, and nowhere else.

The Killer Feature: Safe Account Import via Webcam

Let's talk about the elephant in the room. How do you actually move your authenticator accounts from your phone to your Mac?

Here's what the typical workflow looks like:

Open Google Authenticator on your phone
Go to Transfer accounts → Export
A QR code appears — this QR contains every single one of your secret keys in readable form
You take a screenshot
Now you need to get that screenshot to your Mac
So you send it via... Email? Telegram? WhatsApp? AirDrop?

Think about what just happened. That screenshot — containing the master keys to all your accounts — is now:

Sitting in your email sent folder (stored on Google/Microsoft servers)

Saved in your Telegram/WhatsApp chat history (on their cloud servers)

In your phone's photo gallery (possibly auto-synced to iCloud or Google Photos)

Cached in whatever transfer app you used

Potentially visible to anyone who gains access to any of those services

You just took the most sensitive data you own and scattered copies of it across the internet. The very act of transferring your secrets has created a bigger security risk than not having two-factor authentication at all.

Mactokio's Approach: Just Point Your Camera

Mactokio eliminates this entire problem. Instead of transferring a file, you simply hold your phone up to your Mac's webcam.

Step	What you do
1	Open Google Authenticator → Transfer accounts → Export
2	Open Mactokio → click + → From Camera
3	Hold your phone's screen up to your Mac's webcam
4	Done. All your accounts are imported.

No screenshot. No file transfer. No email. No messaging app. No cloud.

The QR code goes directly from your phone's screen, through the air, into your Mac's camera, gets encrypted, and is stored safely on your disk. The secret never exists as a file, never touches a network, and never leaves the space between your two devices.

Your secrets travel through physical space, not through the internet.

The Camera is Smart About It

The scanner doesn't just grab the first QR it sees. It carefully watches the QR code across multiple frames before accepting it — this prevents mistakes from partial scans or blurry images. You'll see clear visual feedback the whole time:

What you see	What it means
Highlight border	Scanner found a QR code, verifying...
Green border	Valid authenticator code — imported!
Red border	QR found but not a valid authenticator code

A momentary hand wobble won't reset the scan — there's a built-in grace period. Just hold your phone reasonably steady and the app does the rest.

All Your Accounts in One Scan

Google Authenticator's export puts all your accounts into a single QR code. Mactokio fully supports this — one scan imports every account at once. Each secret is individually encrypted. One scan, all your accounts, zero exposure.

Other ways to import (From File / From Clipboard)

The camera is the safest and recommended way, but Mactokio also supports:

From File — select a QR code image or a text file
From Clipboard — paste a QR screenshot or a link

With every method, the same principle applies: the secret is encrypted the instant it's read, and is never stored unprotected on your disk.

But if you can use the camera, use the camera. It's the only method where your secret never exists as a digital file outside your two devices.

How Mactokio Protects Your Secrets

1. Your Mac Guards the Door — Touch ID & Device Password

Before you can see anything, Mactokio asks for Touch ID or your Mac's password — the same authentication you use to log into your Mac. This isn't some new password that Mactokio asks you to create. It's your Mac's own built-in security, managed by Apple.

Touch ID (fingerprint) if your Mac supports it
Your Mac password as a fallback
Required every single time you open the app — no "stay logged in", no "remember me"
If someone sits down at your unlocked Mac, they still can't see your codes without your fingerprint or password

You already trust this to protect your entire Mac. Mactokio simply puts the same lock on your verification codes.

2. Your Secrets Are Locked to Your Hardware

Your secrets are protected by a second layer: AES-256 encryption — the same standard used by governments and banks to protect classified data.

The encryption key comes from your Mac's unique hardware identity. It's not a password you choose or type. It's something only your specific Mac can produce.

Your encrypted secrets are useless on any other computer — even if someone copies the files
There's no master password to remember, forget, or have stolen
Even if your Mac is stolen and someone extracts the hard drive, the secrets are unreadable without the original hardware

Two layers working together: your fingerprint (or password) controls who can open the app, and your Mac's hardware controls who can read the data.

3. Completely Offline

Mactokio makes zero internet connections. None.

What some apps do	What Mactokio does
Phone home on launch	Nothing
Check for updates online	Nothing
Send usage analytics	Nothing
Sync to cloud	Nothing

Your secrets exist in exactly one place: encrypted on your Mac.

4. Auto-Lock

If you reveal a code and walk away, it hides itself automatically after about 90 seconds. Your codes aren't left sitting on screen for anyone to see.

What You Get

Feature
Verification codes on your Mac	No more reaching for your phone
Works with any service	Google, GitHub, AWS, Discord — anything that uses authenticator codes
Search and filter	Quickly find the account you need
One-click copy	Click a code → it's on your clipboard → paste it
Visual countdown	See exactly how much time before the code changes
Clean, minimal interface	Small window that stays out of your way
Free and open source	No subscriptions, no ads, no hidden costs

Getting Started

Step 1: Install

Download Mactokio.zip from the latest release on GitHub
Unzip and move Mactokio.app to your Applications folder
Right-click the app → click Open (required the first time only, because the app isn't from the App Store)
Authenticate with Touch ID or your Mac password

That's it. No account creation, no setup wizard, no configuration.

Step 2: Import Your Accounts

The recommended way — From Camera:

On your phone, open your authenticator app and go to the export or transfer option
In Mactokio, click the + button → From Camera
Hold your phone's QR code up to your Mac's webcam
Mactokio detects the code and imports your accounts automatically

Your accounts appear in the list, encrypted and ready to use.

Tip: You can also add accounts one at a time — whenever a website shows you a QR code to set up two-factor authentication, just scan it with Mactokio's camera instead of (or in addition to) your phone.

Step 3: Use Your Codes

Click an account to reveal its current code
Click the code to copy it to your clipboard
Paste it wherever you need it

Codes auto-hide after about 90 seconds for security.

It's Free and Open Source

Mactokio is completely free under the MIT license. The entire source code is publicly available on GitHub — anyone can inspect exactly how the app handles your secrets, build it from source, or contribute improvements.

Star Mactokio on GitHub

If Mactokio saves you from reaching for your phone, a star on GitHub helps others discover the project.

Mactokio requires macOS 13 or later. No accounts. No cloud. No tracking. Just your codes, on your Mac.

Eliminate 80% of Nuxt store boilerplate with a single createStore call

Amir Reza Dalir — Tue, 10 Feb 2026 20:00:29 +0000

Every Nuxt app has the same problem.

For every API resource — users, posts, products, orders — the same code gets written:

Define a TypeScript interface
Create reactive state (ref, reactive)
Create a loading ref
Create an error ref
Write a fetch function with try/catch/finally
Repeat for create, update, delete
Repeat for the next resource

Harlemify is an open-source Nuxt module by Diphyx that eliminates this repetition. It's built on top of Harlem, a powerful and extensible state management library for Vue 3 — so the reactive store layer is solid and battle-tested.

Define your data shape once, get everything else for free

Harlemify generates typed stores from Zod schemas. Here's what a full CRUD store looks like:

import { createStore, shape, ModelOneMode, ModelManyMode } from "@diphyx/harlemify/runtime";

const userShape = shape((factory) => {
    return {
        id: factory.number().meta({
            identifier: true,
        }),
        name: factory.string(),
        email: factory.email(),
    };
});

export const userStore = createStore({
    name: "users",
    model({ one, many }) {
        return {
            current: one(userShape),
            list: many(userShape),
        };
    },
    view({ from }) {
        return {
            user: from("current"),
            users: from("list"),
        };
    },
    action({ api }) {
        return {
            list: api.get(
                {
                    url: "/users",
                },
                { model: "list", mode: ModelManyMode.SET },
            ),
            get: api.get(
                {
                    url: "/users/:id",
                },
                { model: "current", mode: ModelOneMode.SET },
            ),
            create: api.post(
                {
                    url: "/users",
                },
                { model: "list", mode: ModelManyMode.ADD },
            ),
            delete: api.delete(
                {
                    url: "/users/:id",
                },
                { model: "list", mode: ModelManyMode.REMOVE },
            ),
        };
    },
});

No separate type definitions. No manual loading/error refs. No try/catch boilerplate.

What comes out of this single definition

Typed models — current holds a single user, list holds a collection. Both are fully typed from the Zod shape.

Reactive views — user and users are computed refs that update whenever the underlying model changes. Powered by Harlem's reactive store engine under the hood.

API actions with auto-commit — Each action knows which model to update and how (SET replaces, ADD appends, REMOVE deletes by identifier).

Automatic status tracking — Every action exposes loading, error, and status without writing a single ref.

Using it in components

<script setup>
const { execute, loading, error } = useStoreAction(userStore, "list");
const { data: users } = useStoreView(userStore, "users");

await execute();
</script>

<template>
    <p v-if="error">{{ error.message }}</p>
    <ul v-else-if="!loading">
        <li v-for="user in users" :key="user.id">{{ user.name }}</li>
    </ul>
</template>

Three composables cover everything:

useStoreAction — execute actions, track loading/error/status
useStoreView — access reactive computed state
useStoreModel — mutate state directly (set, patch, add, remove, reset)

Beyond basic state management

Concurrency control

Every action can be configured with a concurrency strategy:

BLOCK — throw if the action is already running
SKIP — return the existing promise
CANCEL — abort the previous call, start a new one
ALLOW — run both in parallel

No more debouncing hacks or manual AbortController wiring.

Record collections

For grouped data (e.g., users by team), use record mode:

model({ many }) {
    return {
        byTeam: many(userShape, { kind: ModelManyKind.RECORD }),
    };
},

This gives you { teamA: [...users], teamB: [...users] } with typed CRUD operations per key.

Handler actions

Not every action is an API call. Custom logic gets first-class support:

action({ handler }) {
    return {
        sortByName: handler(async ({ model }) => {
            const sorted = [...model.list].sort((a, b) => a.name.localeCompare(b.name));
            model.list = sorted;
        }),
    };
},

Handlers have full access to models and views, with the same status tracking as API actions.

SSR with automatic hydration

Harlemify uses Harlem's SSR plugin (@harlem/plugin-ssr) under the hood. Server-rendered state is automatically hydrated on the client — no manual transfer or serialization needed.

How it compares

	Manual / Pinia	Harlemify
Schema	Separate TypeScript interfaces	Zod shape — types + validation
API calls	Manual fetch + state updates	Declarative with auto-commit
Loading/error	Manual refs per action	Automatic per action
Concurrency	Not built-in	Block, Skip, Cancel, Allow
Collections	Manual array management	Built-in modes (SET, ADD, PATCH, REMOVE)
SSR	Plugin required	Built-in via Harlem SSR
Lines per resource	~50-60	~15-20

Harlemify is not a Pinia replacement. Pinia is great for general-purpose client state. Harlemify is built on top of Harlem and optimized for API-driven data — the CRUD resources that make up 80% of most apps.

Try it

npm install @diphyx/harlemify

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ["@diphyx/harlemify"],
});

Feedback and contributions are welcome — star the repo if it's useful, or open an issue for anything that's missing.