Recently, I have been using my Mac a lot and noticed a issue: Apple Music's inbuilt MiniPlayer does not display over apps, it only displays on Desktop.

This is frustrating a lot of times because I don't want to swipe the screen/click the menu bar "What's Playing" button to see the song name/artist and progressbar of the music.

Brainstorming

I first thought why not use my earlier Ubersicht cd player widget for displaying over other full screen apps, but found that it had the same issue as the Apple Music MiniPlayer, it ONLY displays on desktop.

So BACK to square zero...

After 5 mins:💡 Ah-ha!

Why not vibe code an app in swift, that way it is more customizable!

Solving the Issue

After I had the framework, it was easy down the road, I gave an agent my prompt, and with my small tweaks & new functions (Theme Color/Liquid Glass/MacOS 11 through 26 support... and more), it made a miniplayer in ~40min

Then it was done! A full-fledged miniplayer that shows even when your desktop is in fullscreen mode. 😉😉

You can download it here.

Some Screenshots

So... Yeah I admit it. My home network is WEIRD, partly because I'm literally 16 years old, partly because I'm broke. But also it's weird in a good way (kinda), the network is sort of like an intricate web that connects all my important devices together, and that delicacy is held together by LAN cables that are either under the carpet or on the floor , which, if you think about it, is a terrible choice for a sysadmin.

Diagrams... Fun!

But anyways, lets get to the actual structure of my LAN network by showing you this mermaid diagram:

	%%{init: {"flowchart": {"useMaxWidth": true}}}%%
	flowchart TD

    ONT["ONT (Optical Network Terminal)<br/>Bridge Mode"]
    BE3["Main Router"]

    ONT --> BE3

    %% Second Floor
    SW2F["Dumb LAN Switch<br/>2nd Floor<br/>1000 Mbps"]

    NAS["NAS"]
    SERVER["Main Server"]
    Q2["Router #2<br/>(Acts as Wi-Fi Extender)"]
    SW2F100["Dumb Switch<br/>100 Mbps"]

    BMC["Main Server BMC"]
    PRINTER["Printer"]

    BE3 -->|1 Gbps| SW2F

    SW2F --> NAS
    SW2F --> SERVER
    SW2F --> Q2

    Q2 -->|100 Mbps| SW2F100
    SW2F100 --> BMC
    SW2F100 --> PRINTER

    %% First Floor
    SW1F["Dumb LAN Switch<br/>1st Floor<br/>1000 Mbps"]

    WINPC["PC"]
    BOSE["Central Speaker"]
    HA["Home Assistant Server"]
    SW1F100["Dumb LAN Switch<br/>100 Mbps"]

    DOORCAM["IP Camera"]
    LRCAM["IP Camera"]

    BE3 -->|1 Gbps| SW1F

    SW1F --> WINPC
    SW1F --> BOSE
    SW1F --> HA
    SW1F -->|100 Mbps| SW1F100

    SW1F100 --> DOORCAM
    SW1F100 --> LRCAM

    %% Styling
    classDef wan fill:#6c5ce7,stroke:#a29bfe,color:#fff,stroke-width:2px
    classDef router fill:#0984e3,stroke:#74b9ff,color:#fff,stroke-width:2px
    classDef switch fill:#e17055,stroke:#fab1a0,color:#fff,stroke-width:2px
    classDef server fill:#00b894,stroke:#55efc4,color:#fff,stroke-width:2px
    classDef endpoint fill:#636e72,stroke:#b2bec3,color:#fff
    classDef camera fill:#d63031,stroke:#ff7675,color:#fff

    class ONT wan
    class BE3,Q2 router
    class SW2F,SW2F100,SW1F,SW1F100 switch
    class NAS,SERVER,BMC,HA server
    class WINPC,BOSE,PRINTER endpoint
    class DOORCAM,LRCAM camera

And I can pretty much say that this setup works great! (though there is a bit of a spaghetti cable situation that needs action)

Thoughts on switches

I initially thought those dumb and cheap VLAN switches would SERIOUSLY decapacitate my network's speed, but it turns out they remained basically the same 1gbps throughput up AND down, which is surprising considering these switches (5 port, 4 port usable), are around 70 CNY (10.37 USD) a piece.

So I began wondering how this works, then I found it: cheap VLAN switches don’t lose much speed because packet forwarding is handled by dedicated switching hardware, not a slow general-purpose CPU. VLAN tagging adds only a tiny amount of extra data, and modern switch chips can process it at full line rate. The real bottleneck is usually the Ethernet port itself, so thats why I lost no speed!

Now THAT'S what I call a bang for the buck.

Self-hosted services I am running...

Main Server Services:

NGINX - Load balancer and webserver in front of my website backend

Grafana - Server/Website traffic Monitoring

Immich - Photo gallery

Jellyfin - Media indexer & Player

Scriberr - Audio/Video transcription (Speech-To-Text)

CarbonPanel - Custom built real-time server monitoring panel

MCSManager - Manager for my minecraft server

Thinkpad E450 Services (Yes its a repurposed old laptop lol, still works great.)

Home Assistant - Home Controls & Monitoring

Right that's about it for this blog, thanks again for reading to the very end and see ya next time!

Fair warning, this one gets deep. But every single problem in here cost me real time, so I'm writing all of them down.

Also, upfront: I used AI heavily for this. Reading logs, narrowing down causes, remembering API names I'd never heard of. I'll talk about where that actually helped and where it very much did not near the end.

The one thing I didn't like

My home network gets a public IPv6 address, and it rotates. So for my phone to reach home, that address has to be somewhere my phone can look it up. The normal answer is dynamic DNS: point a hostname at your home IP, update it whenever it changes, done.

Except that means my home address is sitting in public DNS. Anyone who knows the hostname knows exactly where I live, network-wise, and can start knocking. I really didn't want that.

So I did something slightly cursed. My VPN control server's hostname resolves to a private LAN address. 192.168.x.x. That's the only thing in public DNS. At home, it just works. Away from home, it obviously doesn't, the connection dies instantly.

The plan: when the connection dies, the app quietly asks a tiny endpoint of mine for the current public IPv6, and dials that instead. The endpoint sits behind a CDN, needs a secret header, and needs a client certificate. So the real address only ever gets handed to something that can prove it's me.

Which is a lovely plan except no VPN client on earth does that. So, fork.

Part 1: making the official Android app do something it wasn't built for

I forked the open-source Tailscale Android client and called mine Headlink.

Problem 1: I couldn't actually edit the code I needed to edit

The networking core isn't in the app's repo. It's a dependency, pinned by version, no local override, no vendored copy. So "just add an if statement in the dialer" was not available to me.

I ended up finding one function where the app hands its own dialer to the core, and swapping in a wrapped one. My entire hook into the networking stack is basically a single statement, and everything else is new files that don't touch upstream at all.

That sounds like a limitation but it turned out to be the best thing about the whole project. When I rebase onto a newer upstream, there's almost nothing to conflict.

Problem 2: not accidentally destroying my own TLS

This was the part I was genuinely nervous about. If I'm substituting a different IP address, what stops the certificate check from breaking? Or worse, what stops me from "fixing" it by turning verification off, which is the classic way people end up with a VPN that isn't private at all?

The thing that saved me is where the substitution happens. DNS resolution and TLS setup happen above the dial function. My hook gets called at the very bottom, and all it does is return a socket. It never sees the hostname's role as an identity, it can't set the server name, it can't touch the certificate check. The hostname stays the hostname for SNI, for cert verification, and for the HTTP Host header. Only the physical destination changes.

I wrote a test whose entire job is to fail if that ever stops being true. If someone (me, in six months, tired) tries to make the hook "smarter", that test breaks.

Problem 3: the app was sending logs to someone else's servers

Upstream ships with telemetry pointed at the vendor's log service, on by default. For an app whose entire reason to exist is hiding my home address, that's not okay.

I turned it off twice, on purpose:

1. The config flag that disables it.
2. A custom HTTP transport that fails every request without even opening a socket.

Two independent mechanisms, because the first one is a setting, and settings can get flipped. I also deleted the switch in the UI, because a toggle that can't change anything is worse than no toggle.

One detail I got wrong first and had to fix: my transport originally returned a fake "200 OK" to keep things quiet. Turns out the logging library deletes its buffered lines once a POST succeeds. So faking success would have been silently throwing away my own on-device logs, which are the only logs I have. It has to return an actual error.

Problem 4: a DNS fallback that defeated the whole point

Upstream defaults to falling back to Google's public resolvers when the system DNS is being weird. Reasonable default for most people! Terrible default for an app built specifically to keep my home network's addressing private. Flipped to off.

Problem 5: where do I put the secret

The endpoint needs a shared secret and a client certificate. Those cannot live in plain app preferences, that's just a file any rooted process can read.

So: everything gets encrypted with an AES-256-GCM key that lives in the Android hardware keystore, and only ever exists as ciphertext on disk. On top of that:

• The toString() of every config object prints <redacted>. Which sounds paranoid until you realize a crash log prints objects.
• Redirects on the lookup request are refused, not followed. Otherwise someone could redirect my request somewhere else and my secret goes with it.
• The discovered IPv6 address is never logged. It's the one value the entire project exists to protect. Logging it would be genuinely funny in a bad way.

Problem 6: the failure that doesn't look like a failure

My lookup endpoint requires a client certificate, checked at the CDN edge. So I tested it with curl and got... nothing. Connection just closed. Exit code 52 or 56, sometimes a weird HTTP framing error. Never a status code, never a "403 forbidden," nothing that says "auth problem."

Here's why, and it's such a good detail: in TLS 1.3, the handshake completes before the server evaluates your client certificate. So from your side, the connection succeeded. Then it just dies. It looks exactly like a broken server, and nothing like being rejected.

I spent way too long assuming my endpoint was down.

Problem 7: macOS curl is not the curl you think it is

Once I knew I needed a client cert, I passed one. It didn't work. --cacert did nothing either.

macOS ships curl built against Apple's TLS backend, which doesn't accept a PEM cert/key pair and ignores --cacert entirely. You have to hand it a PKCS#12 bundle. Once I did that, it worked first try, and I felt a bit robbed of the hour I'd just spent.

Problem 8: the wrong port cost me an afternoon

My control server is on a non-standard port. Port 443 on that same hostname is a completely different service (an NVR), with its own unrelated self-signed certificate.

So I probed 443, got a garbage certificate, and concluded my VPN server was misconfigured. It was fine. I was knocking on a different door in the same building.

Problem 9: Gradle refused to build, for a reason it wasn't going to tell me

My machine had a very new JDK. Gradle rejected it. Answer was just "install JDK 17 and point JAVA_HOME at it," but the error message did not lead there in any obvious way.

Problem 10: the app had NO network at all, and it looked like a server problem

This is the single most misleading thing that happened in this whole project.

The app just couldn't reach anything. Not "slow," not "some requests fail." Zero network. I checked my server, my certs, my DNS, my code.

The actual cause: Android's battery optimisation. The app needs to be set to Unrestricted, and without it the system reports a blocked reason on every socket the app opens. It presents identically to your server being down.

If you're building anything network-heavy on Android, check this first, not last.

Problem 11: a copy of my app I couldn't see

Release builds started failing to install with a signature mismatch, even after uninstalling the app. I uninstalled it again. Same error. There was no app on the phone. The error insisted there was.

Turns out adb install installs for every user profile on the device, but adb uninstall only removes it from the main one. My phone has a Private Space, which is a separate user, and every dev install had been quietly seeding a copy in there. Android keeps one signature per package for the whole device, so that invisible debug-signed copy was blocking every release-signed build.

You have to unlock the Private Space and uninstall for that user specifically. There is no way you're guessing that from the error message.

Problem 12: the logs kept disappearing

Android's default log buffer is tiny, and the camera stack on my phone spams it constantly. My VPN logs were being evicted within seconds of appearing.

Bumping the buffer to 16MB fixed it. Should've done it on day one.

Problem 13: I couldn't reproduce my own bug

I was launching the app from the command line to test connections, and nothing was happening. No dial attempts, no errors, no anything.

Because launching the app isn't connecting. The backend just sits in an idle state waiting for you to actually press the button. I had to physically tap it every time. Obvious in hindsight, extremely annoying at the time.

Part 2: the plot twist

So Headlink worked. I was happy. And then I ran into a wall that had nothing to do with my code.

Android only lets one app hold the VPN slot at a time. I needed my tailnet and another networking client running at once, and that's just not a thing you can do. One or the other.

The only real fix was to stop having two apps. So I took the discovery feature I'd built into Headlink and ported it into the other client, so one app does both jobs.

Problem 14: same idea, completely different plumbing

The second app has its own dialer abstraction, own address types, own config format. The logic transferred fine; everything around it had to be rewritten. Which is normal, but it's also where the next bug got in.

Problem 15: THE BUG. And it was invisible at home.

Ported everything, built it, tested at home. Worked great. Went out, switched to mobile data, and it couldn't find my server at all.

The logs said the connection timed out against the LAN address. Fine, that's expected, that's exactly the case my hook exists for. But the line where the hook says "a dial failed, let me go look up the real address"? Not there. Not an error. Just absent.

That absence was the entire clue. The hook was never being asked.

The cause: I had written the hook to skip anything that came in as a hostname instead of an IP, because normally the app resolves DNS first and hands the dialer an IP. But one specific request in the connection process, the very first key fetch, goes through a plain HTTP client, and those hand the dialer the raw hostname. So the one request that had to work was the exact one I was skipping.

And at home it never mattered, because at home the LAN address actually works.

Fix was to handle the hostname case: resolve it, then run the results through the hook like normal. Plus a regression test that literally has the phone's real log line in a comment, so future me knows this was a real thing that happened and not a hypothetical.

Problem 16: my build lied to me

After fixing that, I rebuilt. It took two seconds and said BUILD SUCCESSFUL.

Two seconds. For a change to native Go code.

The build was reusing a stale prebuilt native library and only recompiling the app around it. I had shipped the OLD code to my phone, with a green checkmark and everything. If I'd trusted it, I'd have spent the next hour debugging a fix that was never on the device.

I added a check to the build script: if any Go source is newer than the compiled library, rebuild the library first, no arguing.

I also stopped trusting build output entirely. Now I pull the APK back off the phone and search inside the compiled binary for the name of the function I just added. If it's not in there, it's not on the phone. That habit has caught things twice now.

Problem 17: my patch files were basically empty

I keep my changes as patch files so I can reapply them to newer upstream versions. I generated them, they looked fine, reasonable size.

They contained none of the feature.

git diff ignores files git has never seen. All of my new files, which is most of the work, were silently skipped. The patch was just the handful of edits to existing files. You have to tell git the new files exist first (git add -A -N), and then the patch went from ~120 lines to ~800.

Terrifying, because that's the kind of thing you only discover months later when you try to restore from it.

Problem 18: the moment I thought the whole project was wasted

I tried importing a config share link into the app and got "not a supported scheme."

My stomach dropped. I genuinely thought I'd spent weeks building on something that didn't support the thing I needed, and had to start over.

It wasn't that. That share-link format comes from a different project and this app has simply never read it. The underlying support was there the whole time, and my own logs from an earlier test literally showed it working. I just had to convert the link into the app's own config format instead of pasting it in. Wrote a small script to do the conversion and moved on.

Lesson I keep relearning: "the app rejected my input" and "the app can't do this" are very different sentences and panic does not distinguish them.

Problem 19: startup depended on something that needed startup

The app downloads some routing rule sets when it starts. Those downloads go through the tunnel. The tunnel isn't up yet. So on a bad network, startup would just fail, not degrade, fail.

Fixed by shipping the rule sets inside the APK and pointing the app at those as the initial copy, plus enabling its cache file so it remembers between runs. Now it starts from local data instantly and refreshes later if it can. Tested by deliberately breaking the connection: starts in 0.08 seconds.

Problem 20: three config mistakes the config checker doesn't catch

• Two options I was using got deprecated in a recent version and replaced by a different structure.
• One of my sections pointed its traffic at an empty placeholder, which the app rejects at runtime with "makes no sense" (accurate).
• Both of those pass check and only fail on run. So "config is valid" means less than you'd hope.

Problem 21: editing JSON on a phone is miserable

All my settings lived in a config file that I had to edit on my phone in a text box. Every tweak. It was awful.

So I built an actual settings screen. Control server, secret, certificate, all of it, stored encrypted in the keystore like before, with the ability to import a certificate bundle straight from the phone's file picker. It merges into the config on the way past, so the config file itself stays free of credentials.

It also validates: it refuses a control server given as a bare IP (there'd be no hostname left to protect), refuses a non-HTTPS lookup URL, refuses an empty secret, refuses half a certificate pair. All the mistakes I'd already made once.

Part 3: the battery mystery

Everything worked. Then I noticed my phone was looking up my server's hostname every two seconds, forever. That is not a thing a healthy app does, and it was going to eat my battery.

First instinct: something's wrong with DNS caching. Wrong. Almost all of those "lookups" were cache hits, one real query per DNS TTL. The lookups were a symptom, and I nearly spent a day fixing the wrong thing.

Here's the actual chain, and it's a good one:

1. My relay server's certificate is self-signed, so away from home the app can't verify it.
2. Failure → retry with backoff.
3. Every retry re-runs a network conditions check.
4. That check's result flapped between two values.
5. A changed result counts as "my network changed."
6. So the app posted a network update to the control server. TLS handshake plus an HTTPS POST.
7. Six to eight times a minute. Forever.

Over 8 minutes I counted 199 lookups, 88 network checks, 38 update posts, 81 certificate errors and 88 backoffs.

The proper fix is a real publicly-trusted certificate on that relay, which I'll do. The immediate fix: the protocol supports pinning a specific certificate by its hash. That's a pin, not a bypass. Hostname verification still runs, expiry still runs, the only thing replaced is chain-to-CA verification.

I want to be really clear about that, because sitting a few lines away in the same source file is an option that genuinely does turn verification off, and it would also have "fixed" this. I didn't use it, and I wrote down why so I don't get tempted later.

After the pin, same measurement over an idle window: 0, 0, 0, 0, 0. And the relay connected on the first try.

The bonus: a workaround that had never once worked

While in there I found that my server config had an "ignore certificate errors" option set. Except the key was spelled insecurefortest and the real one is InsecureForTests. Missing an s.

The config parser silently ignores keys it doesn't recognise. No warning, no error, nothing. So that line had been sitting there doing absolutely nothing for weeks, while I assumed it was handling the problem.

And I'm leaving it broken, because fixing the typo would actually disable certificate verification, which is the thing I've spent this entire project refusing to do. Deleted it instead.

So how much of this was AI

A lot. Honestly.

Where it was great:

• Reading walls of logs. Thousands of lines of connection logs, and the answer being which line is missing. That's the kind of thing I'd stare past twenty times.
• Knowing the shape of unfamiliar code. Names of functions in a networking library I'd never touched, where the seams are, what's safe to hook.
• Talking me down. During the "supported scheme" panic, having something go "wait, your own log from yesterday shows it working" was worth a lot.

Where I had to stay awake:

• Confident wrong answers happen. The fake-200 telemetry thing would have quietly deleted my logs. The stale-build thing said BUILD SUCCESSFUL. Both looked correct.
• Verification beats agreement. Pulling the APK off the phone and grepping the binary is undramatic and never lies. Reading a success message is faster and lied to me directly.
• Security shortcuts need a hard "no" written down somewhere. There is always a one-line change that makes the error go away by disabling a check. I kept a rules file in the project saying never disable certificate verification, never log the discovered address, never store credentials in plain preferences. Having those written down meant every time we got near one, the answer was already decided instead of being re-argued at 1am when I just wanted it to work.

That last one is my actual takeaway. Not "AI good" or "AI bad." The tool is extremely fast at getting you to something that runs, and "runs" and "correct" are not the same word, especially when the whole point of your project is a privacy property that failing silently is the worst possible outcome for.

The short version, if you skipped

• Check Android battery settings before you debug your server
• adb uninstall doesn't remove other user profiles' copies
• The absence of a log line is data
• git diff doesn't see untracked files
• A fast build is a suspicious build
• macOS curl needs a P12, not a PEM pair
• Config validators validate less than you think
• A pin is not a bypass, but the bypass is always right there next to it

Anyway. My phone finds my house from anywhere now, and my home address isn't in public DNS. Took a while.

P.S.

The repo is here if anybody is interested :)

The actual use cases were pretty normal homelab stuff: remote camera streaming, controlling Home Assistant, SSH into the server without exposing port 22, and editing/debugging code remotely without building a separate public endpoint for every service.

Tailscale is the obvious answer, but for this setup I wanted to self-host the control plane. That is where Headscale comes in: it implements the Tailscale coordination/control server, while the normal Tailscale clients still handle WireGuard, endpoint discovery, NAT traversal, and peer connectivity.

One distinction matters a lot here:

• Headscale/Tailscale coordination is the control plane.
• WireGuard peer traffic is the data plane.
• DERP is a fallback relay when a direct peer path cannot be established.

The control server distributes keys, peer information, policy, and DERP maps. It normally does not sit in the middle of the traffic between two peers.

I also used AI tools heavily while building this: reading logs, comparing configs, checking assumptions, and helping turn the deployment notes into this writeup. The interesting part was not getting a perfect setup on the first try; it was seeing how all of the pieces behave once you stop testing from a single machine on a single LAN.

Getting stable node identity

The first version worked on my Mac, but after restarts I started seeing duplicate nodes appear in Headscale with new tailnet IPs and slightly different names.

For a private deployment I did not want routine node expiry, so I made that explicit:

node:
  expiry: 0

After cleaning up the duplicate entries, the machine identity stayed stable.

One useful caveat: if a client registers as a genuinely new node after every reboot, do not only stare at the Headscale expiry setting. The client also needs to preserve its own local Tailscale state. A server-side expiry policy and lost client state can produce similar-looking symptoms from the admin side.

TLS with a private CA

I already had my own CA for internal services, so the natural next step was to sign a certificate for Headscale and trust that CA on the clients.

OpenSSL liked the chain. macOS did not.

The important detail turned out to be the leaf certificate itself. I had originally issued it with a 10-year validity period, which is far longer than Apple's TLS requirements allow for server certificates issued on modern systems.

This is easy to confuse with Apple's newer 398-day public-certificate limit. That newer rule applies to certificates chaining to roots in Apple's built-in trust store; it does not apply in the same way to a root CA that a user or administrator installed manually.

For my private-CA setup, the relevant Apple requirement was the older 825-day maximum for TLS server certificates, along with the usual modern requirements such as SAN, serverAuth EKU, SHA-2 signatures, and adequate key sizes.

Reissuing the leaf certificate with a much shorter lifetime solved the problem.

So if a private PKI looks valid in OpenSSL but an Apple client still rejects it, I would check more than the chain:

• certificate lifetime
• Subject Alternative Name
• Extended Key Usage
• signature algorithm
• key size

The error message is not always going to point at the exact one.

IPv6-only server meets IPv4-only network

My home server has a public IPv6 address but no public IPv4 address.

That is fine until the client happens to be on an IPv4-only network.

At that point there may simply be no shared IP family for a direct UDP path between the two endpoints. Tailscale can normally punch through NAT and establish direct WireGuard paths, but it cannot make an IPv4-only network directly route to an IPv6-only endpoint without some translation mechanism in the middle.

This is where DERP matters.

I added a nearby self-hosted relay so that the fallback path stayed geographically close to the server:

derp:
  server:
    enabled: true
    region_id: 999
  paths:
    - /etc/headscale/derp.yaml

Headscale distributes the DERP map to the clients; the Tailscale clients measure the available regions and choose an appropriate relay when they need one.

The important part is that direct is still preferred. The relay exists for the cases where the network path genuinely cannot be direct.

Keeping the control hostname pointed at a changing IPv6 address

My ISP does not give the server a permanently static public IPv6 address, so I already had a small helper that kept an internal hostname mapped to the server's current address.

On macOS I used /etc/hosts:

2409:xxxx:xxxx:xxxx::1 headscale.lan

The script periodically queries a small authenticated endpoint, gets the current IPv6 address, and rewrites the entry only when it changes.

A simplified version looks like this:

#!/usr/bin/env bash
set -euo pipefail

ENDPOINT="YOUR_SYNC_ENDPOINT_HERE"
SECRET="YOUR_SECRET_HERE"
CA_CERT="YOUR_CERT_PATH/ca.crt"
CLIENT_CERT="YOUR_CERT_PATH/client.crt"
CLIENT_KEY="YOUR_CERT_PATH/client.key"
HOSTNAME_ENTRY="headscale.lan"

CURRENT_IPV6=$(grep -E "[[:space:]]${HOSTNAME_ENTRY}([[:space:]]|$)" /etc/hosts \
  | awk '{print $1}' | head -1 || true)

RESPONSE=$(curl --silent --fail --max-time 15 \
  --cacert "$CA_CERT" \
  --cert "$CLIENT_CERT" \
  --key "$CLIENT_KEY" \
  -H "X-Sync-Secret: $SECRET" \
  "$ENDPOINT")

NEW_IPV6=$(printf '%s' "$RESPONSE" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['ipv6'])")

if [[ -z "$NEW_IPV6" || "$NEW_IPV6" == "$CURRENT_IPV6" ]]; then
  exit 0
fi

sudo /bin/sh -c "
  awk -v host='$HOSTNAME_ENTRY' '\$2 != host { print }' /etc/hosts > /tmp/hosts.tmp
  printf '%s %s\n' '$NEW_IPV6' '$HOSTNAME_ENTRY' >> /tmp/hosts.tmp
  cat /tmp/hosts.tmp > /etc/hosts
  rm -f /tmp/hosts.tmp
"

I run it periodically through launchd.

A subtle but important point: this changes how the Mac reaches the Headscale control server. It does not force Tailscale peer traffic to use that same address. Peer-to-peer WireGuard paths are negotiated separately.

That distinction becomes important later.

Windows and Android exposed the DNS bootstrap problem

The Mac worked because it already had the hostname in /etc/hosts.

Windows and Android did not.

Both clients sat on "connecting" because the control-server hostname only existed locally on the Mac. Before a new client can join the tailnet, it still needs some normal way to resolve and reach the Headscale server.

Tailscale has bootstrap-DNS behavior that can help when ordinary DNS is broken, but that only helps for names that actually exist in resolvable DNS. It cannot discover a private hostname that was never published anywhere and only exists in another machine's hosts file.

The clean solution was to give Headscale a real subdomain and issue a certificate for that name using DNS-01.

Once the control hostname was something every device could resolve, Windows and Android connected normally.

That does not mean a Headscale hostname must always be public. A private hostname works perfectly well if every client already has DNS or hosts-file resolution for it. Mine simply did not.

Control-plane DNS and data-plane performance are separate problems

Around the same time as the hostname migration, I noticed some connections that had previously been direct showing up as relayed, with much worse throughput.

This is exactly the kind of thing that is easy to misdiagnose because two changes happen at the same time.

The Headscale hostname determines how a client reaches the control plane. It does not determine the address used for normal peer-to-peer WireGuard traffic.

The data path is negotiated separately:

1. peers learn about each other through the control server;
2. the clients discover candidate endpoints;
3. Tailscale tries to establish a direct UDP path;
4. if that fails, traffic can fall back to DERP.

So if a connection suddenly becomes relayed, changing the DNS record for the Headscale hostname is not, by itself, a real explanation.

The useful tools are things like:

tailscale status
tailscale ping <peer>
tailscale netcheck
tailscale debug derp-map

Then look at the actual path: UDP reachability, NAT behavior, firewall rules, discovered peer endpoints, and the DERP region being selected.

I still use local hosts/split-DNS overrides where they are useful for making the control server reachable at the right address. I just treat that separately from whether the peer connection itself is direct.

My Windows desktop is a nice example: it sits on the same LAN as the server, so the peers can normally establish a local direct path regardless of what hostname I use to reach Headscale.

Android is the least flexible client in this setup

macOS is easy to customize because I can rewrite /etc/hosts.

A normal unrooted Android phone is not.

That means any design that depends on a per-device hosts override becomes awkward on Android very quickly. DNS override apps exist, but most are built around filtering or VPN-based DNS interception rather than acting as a transparent replacement for /etc/hosts.

The more robust design is therefore to make the Headscale control endpoint reachable in a way the phone can actually use remotely: public endpoint, reverse proxy, split-horizon DNS where appropriate, or some other path that does not depend on root access.

Existing Tailscale connections can survive temporary loss of the coordination server for a while because the clients cache peer state, but that is not a substitute for a reachable control plane. New peer information, policy changes, key operations, and re-registration still depend on it.

Windows kept the old control server in local state

The final annoying issue was Windows remembering the old login server after I had moved everything to the new hostname.

Changing command-line flags was not enough because the client had already persisted its state locally.

The clean first choice is still the normal route: logout, reset/reconfigure, and enroll the machine again.

In my case I eventually treated it as a fresh client: stopped the service, made sure the client processes were gone, removed the relevant local Tailscale state, and re-enrolled it against the new Headscale URL.

That is a destructive reset, not something I would recommend as the first troubleshooting step. It throws away local Tailscale state and effectively makes the machine a new client again.

Where the setup ended up

The final architecture is much easier to reason about once the control plane and data plane are kept separate.

Control plane

Headscale lives behind one real hostname with a valid TLS certificate.

Every device that needs to join, re-register, receive peer updates, or pick up policy changes needs a way to reach that hostname.

Depending on the device and network, that can be:

• normal public DNS + a reachable endpoint
• split-horizon DNS
• a reverse proxy/VPS
• an explicit local override

Data plane

The actual traffic between peers is handled by Tailscale/WireGuard.

The clients try to establish a direct UDP path first. If the two networks cannot talk directly, for example an IPv4-only client reaching an IPv6-only server with no translation path, DERP provides the fallback.

That separation cleared up most of the confusing behavior:

• TLS and hostname problems are control-plane problems.
• Direct-vs-relayed performance is a data-plane problem.
• The self-hosted DERP exists for the second one, not the first.

The setup ended up being less about one clever config file and more about making each layer explicit: identity, TLS, DNS, control-plane reachability, peer discovery, and relay fallback.

Once those layers were separated, the system became a lot less mysterious.

I've been thinking about writing a blog for a long time but never really committed to it haha, but this will be a new place for me to occasionally write some interesting stuff.

What to expect from my blogs

Probably a mix of:

• Build logs / project updates (ShutterWingPhotos, llmgps, basically whatever I am working on)
• Self-hosting stuff: things that took me WAYYYY too long to figure out
• IoT and HomeAssistant experiments
• Occasional hot takes on AI tools

Nothing too formal. If something trips me up and took me a while to figure out, I'll write it down so future me (and maybe you) don't have to go through it again.

Anyways... first post is done. More content coming sometime soon :)

Note

Originally posted on my old blog on New Year's Day 2025. It was the last thing I put on it before moving here.

It is January 1st, 2025 12:50 PM here in China (GMT +8 Beijing Standard Time).

and so… it is time to say…

Happy New Year Everybody!

I sincerely hope everybody has a great NEW & AWESOME YEAR ahead!

Note

Originally posted on my old blog in November 2024. The montage was a 4K HEVC file that most browsers refused to play. It is re-encoded here so it actually works.

Hi Again!

There has been a lot of things that happened in my life for the past few months, and explaning them one by one is kinda tough, so I'm just going to round up what happened, first, 8th grade ended (and i definitely did not end up finishing my RaspberyPi handheld project lmao XD), then came summer vacation, I went to Suzhou for a business competition in which we had to "make" a game and market it, we got one medal but did not win a huge prize, I think our team ended up in 10th place but it doesn't really matter cause' people say that "The process is what matters." hey? Anyways, after the competition we stayed in Suzhou, exploring almost all of the gardens and museums there is, and I used my Camera (A Canon EOS R6) to take pictures around the famous tourist attractions, near the end of the summer vacation, we took a train back, which took a detour in Tianjin, so we also decided to stay there for a bit, and it was really fun :) Thats about it for the summer vacation updates and after that, the new semester starts.

Some Carefully Selected Pictures I took in a montage video:

(btw the title is in Mandarin because I'm Chinese if u didnt know already, the title means "If you took a camera to Suzhou & Tianjin, you will get…")

Note

Originally posted on my old blog in April 2024. This is a build log plus a separate "Tutorial Part 1" that never got a part 2, merged into one post here.

Hey!

As I have mentioned in the last blog, I was preparing to make a small Raspberry Pi PDA (or Handheld PC) using my spare RPI 4B, and after about 20 days or so, I am 90% done building it, so the objective was to build a compact device to code on and to take everywhere, so I listed some basic functions:

1. Charge-free for at least 2 hours under full load (2 Amps)
2. Fits in my hands
3. Adequately cooled
4. No external Keyboard or mouse unless necessary
5. External USB 3.0 Ports
6. External FULL-SIZED HDMI port
7. System set up for tinkering and learning (I Promise :3)
8. Plays Sound

Components list

With all those function requirements, I went to work and made a components list.

1. Raspberry Pi 4B (x1)
2. 32 GB SD Card (x1)
3. 3.7v 3000mah Lithium Polymer Battery (Totals 6000mah) (x2)
4. Charge/Boost Converter 2 in 1 Module (x1)
5. Type-C Female Port (x2)
6. Micro HDMI Male to HDMI Female Connector (x1)
7. 18 AWG Wires (x4)
8. Rectangular On-Off Switch (x1)
9. 3.5 AUX Male to Positive/Negative Wire (x1)
10. 8Ω 2W Wired Water-proof Speakers (x1)
11. Rii Mini X1 Keyboard (x1)
12. USB 3.0 2-port conjoined Female Port (x1)

Here is some pictures of the components in case you can't find it:

USB 3.0 2-port conjoined Female Port:

Rii Mini X1 Keyboard:

8Ω 2W Wired Water-proof Speaker:

3.7v 3000mah Lithium Polymer Battery:

The case

Then, based on the size of the components, I modeled a case for it in Autodesk Fusion:

After creating the model, I bought the components, and the price was totaling about 150¥ (CNY) or about 21$ (USD), excluding the Raspberry Pi and the 32 Gigabyte MicroSD Card which I already have, then I pieced the components together and got it working without the case!

Note

Originally posted on my old blog in March 2024. The "Geeker tablet" it ends on is the Raspberry Pi PDA I wrote up a week later.

Hey guys!

Long time no see after the Chinese New Year vacation, I along with my teammates, came home with a 2nd place in the NSL RC Racing competition, there was a few moments that left our hearts pounding, but eventually we got a 2nd place, which is very impressive to me seeing how we all collaborated together. I went to a few different places before and after the race, of which cities are all in China of course (Chongqing, Fuzhou, Xiamen (Competition place)) it all came out to be pretty fun, In Chongqing, I Had a delicious meal of authentic Chongqing hotpot (Not very spicy for a person from Sichuan like me lol, from my POV I would give it a 6.5/10 spicy rating but if you are a foreigner, watch out! it's bound to be the spicest thing you've ever had), In Xiamen, I went to several beaches (BaiCheng Beach, HuangCuo Beach and much more views, all of which were amazing! They had a incomparable view of the sea, which I definitely couldn't see in Beijing). In Fuzhou, I went to the infamous San Fang Qi Xiang (three squares and seven lanes) and visited various artists, poets, and author's former residences. So anyways, this trip was a total blast for me! :33333

Ok and now with the updates… I have not worked on anything in the vacation, but after the vacation, which is now (oh and sry for writing a post this late) I joined a Maker's Club and decided to build a Geeker tablet powered by the Raspberry Pi 4B that has multiple Functions, I used "The world's smallest keyboard" as the keyboard and trackpad (yes you did not look at the wrong sentence, it does indeed have a small trackpad), 3000+3000=6000mah battery for long tinkering sessions (lol jk it's mainly just for the battery life to be longer because I want it to do more things instead of just die in 1hr without charging), ports for extending, and at last a proper Linux install for E F F I C I E N C Y and Security! I am working on this project as of now and prepare to finish it before May 2024, so check out my new updates!

That's about it for this update and I'll see you (404 undefined)!

Note

Originally posted on my old blog in January 2024.

We meet again!

It has been 8 months and if you are being stricter, a whole new year since I have posted a new blog, I almost completely forgot about it until now in 2024, schoolwork and things are fine, Maths are hard as always, and I don't play games that much (btw cs2 fps and ping sucks on my gtx960 and gunk-filled pc), semester 1 in 8th grade has not ended for me or others just yet, we'll just have to wait another 3 weeks and then it will be Chinese New Year of 2024 (Year of the Dragon according to the Chinese Zodiac). At this time of the year we get to relax, travel to places and mostly, enjoy our time with our own families. I have a STEM RC Car Competition coming up on Feb 6th in Xiamen, and my birthday lands right after the break!

For programming projects (Check out all of them on my Github), I have been working on two new things, one of them is YAUMSI (Yet Another Universal Minecraft Server Installer) because I wanted people to create new minecraft servers at home more easily instead of finding online hosting services which are pretty expensive (if you are rich please skip this entire part, Thanks! :3), and SafeSphereX, which is basically an Antivirus for mac (does not really detect viruses tbh).

I guess that's all for today (or perhaps this week).

See you around, Friend!

Note

Originally posted on my old blog in May 2023.

Hello Readers!

Smart People (You Probably) have realized that I have released ezcite 2.0! (*but its like released on march... so sorry for being so late), or realized that the ezcite isn't in my repos! That's because I moved it to my organization! (The Interstellar Progeammers). Anyways, if you see that, then congrats! you are officially a huge fan of ezcite!

The Download Link (DMG FILE! ONLY FOR MAC RN) is here in case you can't find it

Download Link For Font File "Ubuntu" (Please download for best experience!)

Download Link For Font File "StarJedi" (Optional)

P.S. The reason ezCite has no new versions is because me, as a 'professional' programmer, forgot to sync all of my files (Wow Leo why u so dumb... eh?), and my school computer broke down... so yeah, my data is fine but the technicians are fixing it.

Note

Originally posted on my old blog as two posts a day apart in April 2023, merged into one here. The server is long gone, so I've dropped the live status banner and the IP address.

Long time no see!

I've been having a lot a trouble on schoolwork and time recently, so no time for blogs, during the Qing Ming Festival Break in China (Similiar to Mexico's Day of the Dead but not quite), I finally can have a little break where I can make projects I like!

As I said before, I am obsessed with old games and old tech, which led me to think about old Online Multiplayer Games such as GMOD, Counter Strike 1.6, Source and more, so I thought: Why not make a old Game server to bring that sense of nostalgia back? Well I did it, looking for tutorials and asking on the AlliedModders Forum for a lot of time, and setting up all kinds of plugins. Now what I Have is a Full On DeathMatch Server running on my old Thinkpad with Upgraded 8 GB RAM and 128GB SSD, which working amazingly good in 2023!

I Will Post The IP Address of my server Later in the Month, and I wish you all a good holiday!

:3

The next day: the link, and more

So as I promised, here's the banner of my server, including the ip address of my CSS Server: it was a GameTracker badge pointing at my home connection on port 27015.

Oh and also my server has SourceMod, MetaMod, and some plugins Installed on it, I have a list of the plugins at the bottom of this page if you guys want to see for yourself, it is really just a few files and the SourceMod Plugins command just shows all of the files associated with each plugin.

Anyways the way I got the server running over my network was pretty frustrating, I will come up with a tutorial on How to build a Source Dedicated Server and how to setup a NAT Reverse Proxy. I would also consider opening more Source/HLDS Servers from different games and test it out myself! I've filtered the possible candidates for the server creation which are: Lead 4 Dead 2, HL2 DM, TF2, and maybe GMOD.

Well I think that's that for this hour, c u 4 hours later with a NAT Tutorial! Bye! :3

The list of plugins on my CSS server

• "Admin Help" (1.11.0.6934) by AlliedModders LLC
• "Basic Commands" (1.11.0.6934) by AlliedModders LLC
• "Player Commands" (1.11.0.6934) by AlliedModders LLC
• "Show Damage" (1.0.7) by exvel
• "Fun Commands" (1.11.0.6934) by AlliedModders LLC
• "MapChooser" (1.11.0.6934) by AlliedModders LLC
• "Sound Commands" (1.11.0.6934) by AlliedModders LLC
• "Basic Info Triggers" (1.11.0.6934) by AlliedModders LLC
• "Basic Votes" (1.11.0.6934) by AlliedModders LLC
• "Basic Chat" (1.11.0.6934) by AlliedModders LLC
• "Anti-Flood" (1.11.0.6934) by AlliedModders LLC
• "Basic Ban Commands" (1.11.0.6934) by AlliedModders LLC
• "CS:S DM Bot Quotas" (2.1.6-dev) by AlliedModders LLC
• "Client Preferences" (1.11.0.6934) by AlliedModders LLC
• "RankMe" (2.8.3) by lok1
• "Nextmap" (1.11.0.6934) by AlliedModders LLC
• "Fun Votes" (1.11.0.6934) by AlliedModders LLC
• "Basic Comm Control" (1.11.0.6934) by AlliedModders LLC
• "Admin Menu" (1.11.0.6934) by AlliedModders LLC
• "Rock The Vote" (1.11.0.6934) by AlliedModders LLC
• "Advertisements" (2.1.1) by Tsunami
• "CS:S DM Spawn Protection" (2.1.6-dev) by AlliedModders LLC
• "CS:S DM Basics" (2.1.6-dev) by AlliedModders LLC
• "CS:S DM Equipment" (2.1.6-dev) by AlliedModders LLC
• "CS:S DM Preset Spawns" (2.1.6-dev) by AlliedModders LLC
• "Admin File Reader" (1.11.0.6934) by AlliedModders LLC
• "Reserved Slots" (1.11.0.6934) by AlliedModders LLC

Note

Originally posted on my old blog in November 2022.

Hello! It has been a stressful three weeks so I didn't post anything, summatives, formatives are now crawling up my leg and pulling me into a endless hole.

So, updates… I have recently been working on a free-and-no-ad citation generator called ezCite, and I already have the terminal version of that, so good for me…. More Updates later!

Note

Originally posted on my old blog in July 2022, lightly trimmed since. It points at a "Downloads" page that only existed there, so that reference has nowhere to go now.

So, Recently I was spending a lot of time doing boring online classes of 6th grade (Which sucks, IRL SCHOOLS ARE THE BEST), and also my programming project "HackGen: A hacking/programming simulator" which is currently now available on MacOS and Linux! (Most distros) … find it on the "Downloads" Page of my blog to download it if you want, or just click on this repo card and go to the "releases" section of the repo page.

Oh right, check out and follow my Github profile too!

For fun I played like 40 mins of CS:GO every week on my "low-end pc", CSGO was running smoothly at 120-140 fps at lowest settings (but models at the highest settings) with a NVIDIA GTX 960 GPU. Here are some funny screenshots:

Hey! Whatcha lookin' at!

Hi i'm dead

T (*pats on CT) : Buddy, how's this match? CT (*pats back): oof, pretty good and goofy, I would say

Anyways even though I was born in 2010 (12 years old now), Old games still bring me nostalgia, like Counter Strike 1.6, Source, Half Life (Wasn't born when these games are made).

Later I will add some webpage games that you guys can play in your web browsers!

One last thing, I've been wanting to start a novel for months, I finally got a chance about this summer, the novel's name is "Escape from planet Earth", it's kind of an sci-fi novel, I got partial inspiration of another Mars related novel "The Martian" by Andy Weir, It's a great novel! Go read it!

Well I think that's all for this update! Bye! :3

JULY 5TH UPDATE:

Disqus was added to the site! Also I am going to write in diary every week or so.

Note

Originally posted on my old blog in April 2022. Kept as written. The prices, the links and the advice are all from 2022.

Imagine this senario, you need a lot of pictures and/or important files stored someplace locally, and you want to access it through every computer/phone, but all of your storage is full, how do you store those pictures/files?

Well, the Raspberry pi can be a great soulution. The Raspberry Pi uses a lot less power than a regular NAS server, and it's pretty cheap and easy to setup. So here's how to make it...

Step 1: Getting the components

First, you need these components, some are needed and some are optional:

1. Raspberry Pi 4B / 2G RAM: $35 Dollars ¥223 Yuan (You can buy the 4G and 8G version, but it's more pricey)
2. Case for Raspberry Pi (Optional): If you are a geek, you can 3D print one like I did, anyways, here it is. (Credit to Michael Klements for designing the case (Aaaand making his own tutorial of the making of the case), he is a great tech youtuber and you should definitely check him out!)
3. Micro SD Card (Sandisk 32 GB here): 14 Dollars/89 RMB. This is for system installation, or if you only have a few files, using a 32 gigabyte sd card would be fine.
4. SSD or HDD (Optional) (Can be Leftover SSD or HDDs)
5. I2C display (Optional if you want the case)
6. 3.3V Fan (Optional if you want the case)

Step 2: Installing the Raspberry Pi OS

1. Download the Raspberry Pi OS from here. If you want a GUI Graphical Desktop to do gui applications, you can download the full version, but if you want it to be a lighter system and run more smoothly as a NAS server, use the lite version of the OS.
2. Open Win32DiskImager and choose the image and transfer it to the Micro SD card OR use Etcher on mac and Rufus on windows, same steps.
3. Plug the Micro SD card into the raspberry pi and start it.

Step 3: Commands for the SMB server

1. Open a terminal and enter this command, this command installs the samba module which is used to create the SMB server:

   sudo apt-get install samba

2. After the necessary installation, use nano or vim to edit this file:

   sudo nano /etc/samba/smb.conf
   # or
   sudo vim /etc/samba/smb.conf

3. Write these lines of code at the end of the file. Inside the top big braclet [], you should write your NAS Share name there without spaces, e.g. admins-nas-share, Nas-share. The path should be the folder you want to share (Must be created) e.g. /home/pi/NAS-SHARE.

   [Your NAS Share Name (No Spaces)]
   path = /Your/path/to/the/folder
   writeable=Yes
   create mask=0777
   directory mask=0777
   public=no

4. Create an account on samba with your Raspberry Pi username. After the terminal prompts you for an password, enter your desired password for samba.

   smbpasswd -a (your raspberry pi user account)

5. Restart the samba service:

   sudo systemctl restart smb

6. Connect to your file-sharing service. On macOS, go to the "Finder Menu bar":

   

   Click "Go" and click "Connect to server":

   

   After that, enter your NAS server's ip address and your NAS share name and click "Connect":

   

   Click on your server and enter the samba credentials.

Now you are done! Access all of your saved files, images, videos on the server!

Here's a showcase of the server:

Now doesn't that look good? :3

Bye!

Note

Originally posted on my old blog in April 2022. It was the first thing I ever put on it.

Hello, World!

This is my first blog running on my Raspberry Pi server, using the hexo blog framework and linked with github!

See my next blog for more.