Since I want to keep things minimal I’m gonna use that option, as I don’t want to get down the rabbit hole of burning stylized captions in the video itself like you see all over short form content. That’s for another day.

Most of the options to create subtitles from audio require to call a paid transcription API, like OpenAI’s gpt-4o-transcribe or ElevenLabs. But I’m not paying to caption my random yapping on X, thank you.

The best local option

As far as I can tell the best open-source model for this that can be run locally is OpenAI Whisper, originally released in 2022, with a v3 update in 2023.

While not state of the art, we can run this locally for free and it performed perfectly in my case of speaking English with a heavy French accent (which often defeats transcription models including the ones of Slack and YouTube).

The following is for a Silicon Mac using Apple MLX for performance:

brew install pipx
pipx install mlx-whisper

Then:

mlx_whisper your-video.mp4 --model mlx-community/whisper-large-v3-mlx -f srt

This will produce a SRT file next to the input video.

You can see how it performs with the captions on this post on X (spoiler: it’s good).

Turbo version

It’s also possible to use the Whisper v3 Turbo variant that OpenAI released in 2024, which is “way faster at the expense of a minor quality degradation”.

mlx_whisper your-video.mp4 --model mlx-community/whisper-large-v3-turbo -f srt

However I had some slight glitch with it that didn’t happen in the normal version. Also it seems to make longer lines in captions, and I like the way the non-Turbo version splits lines better.

Non-MLX

For the non-MLX version if you need. This should run on any Mac.

brew install openai-whisper
whisper your-video.mpk --model large --output_format srt
whisper your-video.mpk --model turbo --output_format srt

Even faster?

For even faster transcription, I heard about lightning-whisper-mlx, but didn’t get to try it as it doesn’t come with a CLI. Need to call it from Python instead, and I’m lazy to do that given that mlx_whisper is way fast enough for my short videos anyway.

Let me know how it goes if you try it. ✌️

This year it randomly started flickering. Literally once second it was OK, and the next it was flickering. It’s been plugged the same way for years (I use it with a Lightning cable on my MacBook, which also powers the laptop). Nothing changed.

Tried a bunch of things including unplugging and re-plugging the display, both from the laptop and from the power outlet, as well as restarting the computer. No change.

Flickers varies from the whole screen flashing black at a fast rate, or some specific portions of the screen flashing with more of a “noise” pattern? And more recently, ghosting of what I had on screen at the time it started flickering.

The only report I found is this Reddit post but sadly no solution there (until I posted mine more recently).

Solution

The only thing that seems to reliably fix this for me is to plug the laptop with a power adapter, instead of relying on the screen to power and charge it.

It’s not instant but it seems after leaving the computer plugged for a few minutes or sometimes a few hours, the flickering is gone.

Then you can use the screen for power again, and in my experience it’s fine again for weeks or even months until the next instance of flickering. 🤷

According to my own usage, 10x. If you need more than 10% extra usage from the Pro plan, don’t use on-demand pricing, get a second Pro plan. If you need more than 10% extra of that second one, get Pro+.

Context

I’ve been using Composer 2.5 in Cursor since it came out on May 18, 2026.

I actually had no clue. I had just ran out of Codex quota and wanted to try Cursor again to see how much output I can get from the “Auto” mode in the subscription.

By pure coincidence, the day I want to subscribe, they release Composer 2.5, a significant update to their own model (where “own” means reinforcement learning fine-tuning of Kimi K2.5).

What I think of Composer 2.5

I was instantly impressed by the quality to price feel of that model. It’s one of the cheapest models available, yet it seems to rival GPT-5.5 and Opus 4.8 when it comes to coding? Although it’s tricky to really evaluate that because Composer 2.5 is only available through Cursor, so it’s not possible to rank it on traditional benchmarks like Arena AI’s Code Arena.

Instead we have to rely on Cursor’s own CursorBench. To be fair their scoring of other models is not out of ordinary compared to other coding benchmarks, and the fact the benchmark is private means that it can’t be “gamed” by optimizing for it (except by Cursor themselves 🙃). So if we can’t necessarily trust it for Composer’s performance (it could be trained to perform well on that benchmark specifically without that translating in real-world performance), it might actually be a really good benchmark to compare other models.

That being said in day to day use in real projects, not just toy demos or throwaway stuff, I’ve been pretty happy. The quality is here and I get a fuckton more usage than I was getting with Codex for a similar price.

And that’s despite, with Codex, me trying to aggressively limit the spend by using low thinking most of the time, and older models like GPT-5.3-Codex. Which also resulted in poorer quality and more frustration.

In comparison with Composer 2.5, I stick it to the normal mode (not the “fast” mode they select by default), which is already insanely fast compared to anything else I’m used to (Codex and OpenCode Go), and I don’t have to think about what model or level of thinking to select for every prompt, and deal with the resulting variable quality output. I get consistent quality output and more usage than the competition at the same price point.

Composer 2.5 vs. Composer 2.5 (Fast) vs. Auto

Although there’s no way to know for sure, it feels like picking “Auto” in Cursor often results in using Composer 2.5. Unclear whether it’s in fast mode or not though.

When it comes to pricing, here’s what they charge (price per 1M tokens):

So Composer 2.5 (Fast) is 6 times more expensive than Composer 2.5 (it’s not clear to me that it’s 6 times faster though, as far as I’m concerned if I’m not in a rush I’m happy with the normal mode).

As for Auto, it’s 2.5 times more expensive than Composer 2.5, and it seems that you get Composer 2.5 at the end anyway. Maybe a bit faster but no guarantee to be Composer 2.5 (Fast) speed all the time either.

When it comes to the subscription, there’s no indication that the usage you get is proportional to the public pricing of those models. But it would seem logical to me that using a cheaper option results in less quota usage than using a more expensive option.

So as far as I’m concerned since I want to maximize my quota usage, I’ve been using Composer 2.5 explicitly (not through Auto, and not the fast mode) most of the time.

What happens when you run out of “Auto + Composer” quota?

When you max out your “Auto + Composer” quota, if you still have API quota left, Cursor starts to dip into this for Auto and Composer requests.

On the $20 plan, Cursor says that the API quota includes “at least $20 of API usage”, so you can expect that from this pool once you start using it. In my experience it’s indeed a bit more, see below.

How much inference do we get on the $20 Pro plan?

Your mileage may vary, but here’s what it came out for me after one month of using (mostly) Composer 2.5.

Auto + Composer:

API:

Free:

After I used 100% of my subscription quota, everything kept working and appeared as “free” in the billing usage log. I’m assuming that’s falling back to their Hobby (free) plan once the subscription is exhausted, which has much lower limits (although I didn’t have time to reach them this time).

Grand total:

So if my computations are correct, the $20 plan gave me $208 worth of tokens. $163 of that was in the Auto + Composer pool, and the remaining $46 was in the API pool. (And $7 Hobby fallback.)

Should I enable on-demand usage or upgrade my subscription?

Cursor has an option to enable on-demand spending, where usage is billed at API price after you exhaust your subscription.

When it comes to using Composer 2.5, the subscription gives a 10x boost in tokens compared to API prices.

The next subscription tier is the $60 Pro+ plan which comes with 3x the usage, or you can get a second $20 Pro plan (to get obviously 2x the usage).

This gives us a table like this (based on my own 1 month data, your mileage may vary):

If you run out of the $20 plan, first you might as well max out the Hobby (free) quota as well (worth at least $7 apparently).

Then if you need 10% or less extra usage compared to your Pro plan, on-demand is worth it.

More than that, get a second $20 Pro plan.

If you max out that second plan, the same 10% rule applies for upgrading to Pro+.

Conclusion

Composer 2.5 appears to be quite subsidized, where a $20 plan gives over $200 worth of tokens, about 10 times more than what you pay for.

Though it’s not necessarily as subsidized as other subscriptions, as there’s reports of people getting between $2,000 and $8,000 (???) worth of tokens with the $200 Claude plan.

But because I’m the one paying this subscription and not my employer or some VC, and because I don’t have unlimited money, I find Composer 2.5 is a lot more interesting for my current usage.

HEAD flaky? Use GET with Range: bytes=0-0 instead.

Context

Had a wild bug with S3 recently. Let’s start with some context.

I’m currently building Cloudmotion, a hosted Remotion Lambda. Remotion is the GOAT when it comes to making programmatic videos, and Remotion Lambda is the fastest way to render those videos in the cloud at scale. Cloudmotion is that but I deal with AWS so you don’t have to.

Part of the challenge is supporting any Remotion version. There’s currently over 1,200 published versions on npm, and new versions are released about every other day.

In order to do that, the first time a new version is requested, I trigger a AWS CodeBuild job that prepares the Lambda source, and uploads a ZIP file to S3 that the function can be created from. In the finally phase of the buildspec, I send a webhook to notify the app to continue the provisioning with the newly built artifact.

The app then does a HEAD requests to check that the ZIP file exists and then creates the Lambda from it. This is where things go sideways.

Flaky HEAD response

I’m always calling the S3 API with the same, valid, credentials. So I’m expecting 2 answers: 404 when the file doesn’t exist, and 200 when it does.

However here’s some logs I’ve observed:

And another weird instance:

So while at first it felt like it could be due to doing the HEAD call really shortly after the upload succeeded, that second instance actually shows us that even calls that expect a 404 can get a wild 403 instead, with the same credentials and permissions that got a 404 and eventually a 200 seconds later.

A note about eventual consistency

S3 has “strong read-after-write consistency” since 2020, so it’s been a while there’s no more eventual consistency to deal with when calling S3.

That being said I’m now realizing they say:

Effective immediately, all S3 GET, PUT, and LIST operations […] are now strongly consistent.

This doesn’t include HEAD, so maybe HEAD is still eventually consistent? But even with eventual consistency I’d expect a 404 after a successful upload that eventually becomes a 200. In no way eventual consistency should result in a 403 with valid credentials and appropriate IAM permissions.

Workaround

I never managed to understand the root cause of why those HEAD calls randomly return a 403.

Instead I switched to doing GET calls with Range: bytes=0-0. Returns a 404 consistently when the file doens’t exist, and a 206 (partial content) when it does.

Bonus is that the GET method allows the S3 API to return proper XML error responses, whereas HEAD by design doesn’t have a HTTP body and thus can’t communicate any useful error information (especially in the case of those 403s).

This is well integrated in Xcode, and frameworks like Electron and Tauri also have direct support for this (see How to sign and notarize an Electron app and Tauri macOS code signing).

But the app I’m building, TZBar, is native (no Electron or Tauri), but small enough that I didn’t want to bother with Xcode at all. Just plain swift build. This also meant doing the code signing and notarizaiton from the CLI, which luckily is well documented in this Stack Overflow answer.

That’s how I learnt about the stapling process. While notarization means uploading your app for Apple to scan and approve it, that “verification ticket” can be “stapled” onto the app file itself so that the verification can be done offline on users devices.

This is optional since when connected to the internet, the system will just check the app’s signature for notarization status online, and users who just downloaded your app are typically connected to the internet. 😂

Anyway, it’s done with this command:

xcrun stapler staple App.dmg

Error 65

However the above command failed with:

$ xcrun stapler staple App.dmg
Processing: ~/App.dmg
Could not validate ticket for ~/App.dmg
The staple and validate action failed! Error 65.

Sounds like this error happens for many unrelated reasons with no way to know exactly what’s wrong…

In my case, the Apple root certificates were set to “always trust” instead of “system defaults” (probably from attempts to troubleshoot signing issues of past apps I worked on).

This is apparently a problem, and the stapler will fail if the certificates not set to “system defaults”.

So go in Keychain Access > System Roots, and for Apple Root, G2, G3 and WWDR, make sure to select System Defaults if it’s not the case already.

If this doesn’t solve it for you, this GitHub answer describes a few more steps that you can use to troubleshoot “health” of the signing setup.

$ xcrun stapler staple App.dmg
The staple and validate action worked!

Better!

sudo ln -s ~/.colima/default/docker.sock /var/run/docker.sock
export DOCKER_HOST='unix:///var/run/docker.sock'

Context

Working on a Supabase project, wanna run the whole stack locally using supabase start.

Supabase local development environment is based on Docker containers, so we need a runtime for it. Docs mention Docker Desktop, Rancher Desktop, Podman and OrbStack.

But I like to be different and I want to use Colima. 😂

However supabase start fails with:

failed to start docker container "supabase_vector_myapp":
Error response from daemon: error while creating mount source path '~/.colima/default/docker.sock':
mkdir ~/.colima/default/docker.sock: operation not supported

Found the same error on this Reddit post with the following fix:

ln -s ~/.colima/default/docker.sock /tmp/docker.sock
export DOCKER_HOST='unix:///tmp/docker.sock' 

But in my case, while this goes a bit further, I just get another error. (And the post is archived so I can’t even mention the final solution there, oh well.)

ERROR source{component_kind="source" component_id=docker_host component_type=docker_logs}:
vector::sources::docker_logs: Listing currently running containers failed.
error=HyperLegacyError {
  err: hyper_util::client::legacy::Error(Connect, Os {
    code: 111,
    kind: ConnectionRefused,
    message: "Connection refused"
  })
}

Nothing came up online for this error so hopefully this blog post will help if anyone runs into this.

However I stumbled more generic threads of trying to configure Colima to use the default Docker socket, where the way to do this is:

sudo ln -s ~/.colima/default/docker.sock /var/run/docker.sock
export DOCKER_HOST='unix:///var/run/docker.sock'

So same as before but with /var/run/docker.sock instead of /tmp/docker.sock.

That worked flawlessly for me!

pnpm add -D @typescript-eslint/parser so eslint-plugin-astro picks it up instead of Espree. Mandatory for TypeScript, but also helps with things like early return in frontmatter even in plain JS.

Context

After upgrading to pnpm 11, ESLint started flagging every .astro page that returns early from the frontmatter:

src/pages/login.astro
  9:3  error  Parsing error: 'return' outside of function

The line points to something like this:

---
export const prerender = false

if (Astro.locals.user) {
  return Astro.redirect('/')
}
---

<Login />

To lint Astro files I use eslint-plugin-astro with a pretty basic config.

Same error reported on GitHub, still open at time of writing, no resolution except for disabling the rule entirely.

Works from CLI but not from editor

Running ESLint from a pnpm script i.e. pnpm eslint actually still worked. Only inside Cursor with the ESLint extension I had the issue.

Nothing specific to Cursor though, figured out just using the programmatic API with new ESLint().lintFiles() failed with the same error.

Turns out that pnpm wraps node_modules/.bin/eslint and sets NODE_PATH to node_modules/.pnpm/node_modules, a flat bucket of symlinks to everything installed in the project.

Sounds like we have a dependency graph problem. Something is missing an explicit link and that’s why it only works when everything is hoisted.

pnpm history of hoisting of ESLint

Interestingly, pnpm 10 used to hoist *eslint* by default.

This was because ESLint old config format used to have stuff like plugins: ['astro'] that had ESLint itself translate this to require('eslint-plugin-astro'). This notoriously doesn’t work with pnpm style of node_modules where packages only see their explicit dependencies and not everything in the entire project.

Since then, ESLint moved to flat config that doesn’t rely on those implicit dependencies.

Everything in my project uses ESLint flat config so this wasn’t the issue, but this default hoisting of *eslint* packages was still helping me when it comes to my Astro parsing.

Root cause

eslint-plugin-astro probes for @typescript-eslint/parser at load time (optional, not an explicit hard dependency). When it cannot resolve the package, it falls back to the Espree parser.

Espree seems to treat frontmatter return as a module-level return and errors. @typescript-eslint/parser does not.

RTFM, kinda

Guess what? eslint-plugin-astro documents:

If you write TypeScript in Astro components, you also need to install the @typescript-eslint/parser:

npm install --save-dev @typescript-eslint/parser

I do use TypeScript, although the above failing example was JavaScript-only. Docs frame it as a TypeScript dependency, but in practice @typescript-eslint/parser seems to play better with astro files in general, even JavaScript, at least when early return is involved.

So with pnpm:

pnpm add -D @typescript-eslint/parser

In a hurry? Jump to the results or the conclusion. Otherwise make some tea, relax and read on.

It started with this error:

Usually I just lsof /Volumes/Data and kill whatever is causing the issue (99% Spotlight or QuickLook).

But you know what, I’m at the point where I need to renew my AI coding subscription and after a while on Claude in Cursor and a bit of GPT 5.4 in Codex, I wanted to see what’s out there, and especially compare the big two to the open weights models available through OpenCode Go.

After all, Cursor based their Composer 2 model on Kimi K2.5 so it’s probably decent, and I’ve heard good things about GLM-5.1.

So I decided to compare those models to build a native macOS app to make the above experience a bit nicer.

• Show external drives and allow to unmount them.
• When unmounting from the app, show a popup with what’s blocking and allow to kill the process.
• If unmounting from the normal macOS context menu, the app should also detect a disk that failed to unmount, and show our popup.

Simple as that.

When it comes the planning and building experience, I’ll document vibes only, because nothing really stood out here. And this is all that matters these days anyway doesn’t it?

As for code analysis and final ranking, it’s a bit more thorough, don’t worry.

Planning

I ran all models through OpenCode. Started in planning mode, and answered all questions they asked if any.

They all had a pretty similar plan. Slight variations in irrelevant details, but everything was reasonable when it comes to the underlying commands and APIs to built upon.

The only one that stood out was MiMo, kernel API instead of shelling out to lsof. Do what you want with that but I don’t really care.

It’s a tie for me on this aspect.

Building

OpenCode lets the model run shell commands so they were all able to compile the app and iterate on build failures on their own.

This means when the models were done, the code was compiling. It’s a tie again.

Runtime

Despite compiling successfully, a few of them crashed as soon as I launched the app.

When you make a web app, most harnesses allow browser use for the LLM to test its own output live. This gives us the same success loop we had with compile-time errors.

But there’s no such thing for native apps yet.

Nothing to blame the actual models on though.

After fixing those, all apps had one of two outcomes:

• Can’t find any disk.
• Finds disks but crashes when trying to eject.

For all of them I could just have keep the vibe coding loop until it works. (I did not, I have some real work to do and as you can notice, I’m spending way too much time on this already.)

But as far as I’m concerned it’s more or less a tie. Maybe they didn’t work for different reasons, but it would take a comparable amount of effort to fix.

The code

Let’s take the hypothesis for a minute that code quality, as subjective as it is, is still relevant.

Then, I have a slight preference for the output of GLM-5.1 and GPT-5.4.

Both are more lean and easier to reason about than the other ones.

This is usually synonymous with the software being less buggy now, as well as less buggy in the future when we add/change stuff around. And in my experience this seems to apply to both LLMs and humans.

But I’m sure you can steer all of them to output a clean and maintainable app by prompting a bit more, that is, if you know how to code and care about the code at all.

Getting the models to review each other

That was a fun experiment. I asked the LLMs to review each other’s work, rank it, and score the cleanliness and technical approach.

I was worried this was gonna be a slop spiral but the results were not as over the place as I expected. 👀

GPT-5.4 and Opus 4.6, the two frontier proprietary models, nearly always came up in the top 3, with an edge for GPT.

MiMo V2 Pro also had a tendency to rank quite high, close to the two leaders, even if the consensus wasn’t as striking.

The caveat is that it scored on the low side for cleanliness, despite standing out for technical approach.

GLM-5.1 had a pretty consistent 4th place, but it ranked really high on cleanliness specifically.

This means it’s a decent choice is you want relatively clean code out of the box and don’t mind giving it guidance when it comes to technical approach.

This is actually something that works best for me. I’d rather steer the technical approach if it means I don’t have to refine output quality as much.

Kimi K2.5 and MiniMax M2.7 were consistently at the bottom, and in that order. Which is pretty consistent with their cost.

Here’s the raw data. Row is candidate, column is judge. Cleanliness and technical approach are rated out of 10.

Absolute rank

Cleanliness

Technical approach

A surprising finding on (lack of) biases

The most impressing thing for me was that models didn’t seem to be biased by their own performance??

All models gave their own output a score that was either very close to, or lower than their average score. Even when the average score was low.

GPT-5.4 is the only one that ranked itself first, but guess what, the consensus also agreed on that. 😎

Conclusion

I’m gonna keep using GLM-5.1 via OpenCode Go for the rest of the month or until I run out of usage. Then switch to GPT-5.4 via Codex Plus to see if it’s worth the extra $$$, both in terms of quality and quantity.

Though by then I’ll probably have 5 other models to test. 😂🙃

Meta conclusion

Comparing models is peak procrastination. Any of the top models will do just fine.

And I guess GLM and MiMo are now playing in that league at a fraction of the cost.

If you have a clear idea what you want, you’ll need to steer all of them in one way or another. Just pick one and get back to work.

We initially released it only on Mac as a MVP. Some folks on Reddit showed interest but were on Windows and Linux. I’m pretty eager to get more hands on the product in those early stages, to gather feedback and learn from users where to take it from there, so making it cross platform early on sounded like a quick win.

Quick note on the Windows build

Not the topic of this post but I might as well throw that here in case it’s useful to anyone. Building for Windows from Mac turned out pretty easy following this guide. In short:

brew install nsis llvm
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
rustup target add x86_64-pc-windows-msvc
cargo install --locked cargo-xwin
export PATH="$HOME/.cargo/bin:$PATH"
tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc

This works like a charm, signed auto updates and all.

Signing the app to avoid the SmartScreen warning is not handled out of the box by Tauri when cross-compiling (it only knows to use signtool.exe from a Windows host), but you can configure a custom signing command like osslsigncode and do it from Mac or Linux as well (I haven’t tried it).

What about GitHub Actions

Yeah honestly, should have just done that. I got nerd sniped by wanting to compile for all platforms from my own machine without renting hardware in the cloud. And the idea of generating a working x86-64 Windows and Linux build from my ARM Mac with near-native build performance (so without using QEMU) sounded kinda cool to me.

But really, Tauri has everything ready to use GitHub Actions and output binaries for all platforms, it’s a no brainer.

And the free tier for GitHub Actions is high enough that unless you’re releasing updates every other day, you probably won’t need to pay for it? The Mac runner is by far the most expensive so you could also go a long way building for Mac from your dev machine and delegating only Windows and Linux to GitHub Actions.

OK but I’m here for cross-compiling Linux, remember?

Oh yeah, sorry. I got distracted. 😂

The strategy:

• Use macOS Virtualization framework to run a ARM Linux VM at near-native performance.
• Inside that VM, configure Linux to cross-compile the app for x86-64.
• Use Rosetta from Linux (yeah this is a thing) to run any x86-64 binaries we need along the way at also near-native performance.

Creating the VM with Lima

We use Lima to manage a headless Linux VM.

brew install lima

limactl create --name=linux-builder \
    --vm-type=vz --rosetta \
    --cpus=6 --memory=8 --disk=60 \
    --containerd=none

limactl start linux-builder

• --vm-type=vz to make sure we use macOS Virtualization framework. It’s the default in Lima but we’re explicit about it.

  Virtualization framework only works for same-architecture VMs, so here we’re making an ARM Linux VM, even though we want to build for x86-64.

• --rosetta to use Apple Rosetta to translate x86-64 instructions to ARM on the fly, for binaries we run inside the VM.

• --containerd=none because we don’t need containerd (not running Docker here).

Provisioning the VM

Now we’ll run a shell inside the VM to provision it with everything we need to cross-compile a Tauri app.

limactl shell linux-builder

Add AMD64 architecture

# No interactive prompts
export DEBIAN_FRONTEND=noninteractive

# Enable AMD64 multi-arch
sudo dpkg --add-architecture amd64

# VM defaults to `ports.ubuntu.com` which only has ARM64 sources.
# We need to add `archive.ubuntu.com` for AMD64.
CODENAME="$(. /etc/os-release && echo "${VERSION_CODENAME}")"

sudo tee /etc/apt/sources.list.d/ubuntu-amd64.list > /dev/null << EOF
deb [arch=amd64] http://archive.ubuntu.com/ubuntu ${CODENAME} main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu ${CODENAME}-updates main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu ${CODENAME}-backports main restricted universe multiverse
deb [arch=amd64] http://security.ubuntu.com/ubuntu ${CODENAME}-security main restricted universe multiverse
EOF

# Constrain the native sources to ARM64 so APT doesn't try to fetch
# AMD64 packages from it.
sudo sed -i '/^Architectures:/d' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's/^Types: deb/Types: deb\nArchitectures: arm64/' /etc/apt/sources.list.d/ubuntu.sources

sudo apt update

Install system dependencies

PKGS="git ca-certificates"

# Tauri prerequisites from <https://v2.tauri.app/start/prerequisites/#linux>.
# Added AMD64 suffix for cross-compilation.
PKGS="$PKGS
build-essential curl wget file
libwebkit2gtk-4.1-dev:amd64 libxdo-dev:amd64 libssl-dev:amd64
libayatana-appindicator3-dev:amd64 librsvg2-dev:amd64"

# Tauri needs the AMD64 version of `xdg-open` to bundle in the app
PKGS="$PKGS xdg-utils:amd64"

# Cross-compilation toolchain
PKGS="$PKGS gcc-x86-64-linux-gnu g++-x86-64-linux-gnu"

sudo apt install -y --no-install-recommends $PKGS

Install Rust

Native ARM Rust with x86-64 cross-compilation target.

# `sh -s` to force reading from stdin and allow passing arguments without a
# filename. Configure the installer to be non-interactive (default yes) not
# modify the # `PATH` (we do it ourselves) and install stable.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
    | sh -s -- -y --no-modify-path --default-toolchain stable

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.profile
export PATH="$HOME/.cargo/bin:${PATH}"

rustup target add x86_64-unknown-linux-gnu

Install Node.js

I like to use asdf for this.

ASDF_URL=$(curl -fsS https://api.github.com/repos/asdf-vm/asdf/releases/latest \
    | grep -o '"browser_download_url": *"[^"]*linux-arm64\.tar\.gz"' \
    | grep -o 'https://[^"]*')

curl -fsSL "$ASDF_URL" | sudo tar -xz -C /usr/local/bin asdf

echo 'export ASDF_DATA_DIR="$HOME/.asdf"' >> ~/.profile
echo 'export PATH="$ASDF_DATA_DIR/shims:$PATH"' >> ~/.profile

export ASDF_DATA_DIR="$HOME/.asdf"
export PATH="$ASDF_DATA_DIR/shims:$PATH"

asdf plugin add nodejs

# Optionally pnpm or whatever package manager you use
# asdf plugin add pnpm

# Assuming we already have a `.tool-versions`
asdf install

Rosetta AppImage support

This was the biggest culprit of this whole setup.

Tauri build uses linuxdeploy to build AppImages, and linuxdeploy itself is distributed as an AppImage.

Lima with --rosetta configures binfmt_misc to use Rosetta for a particular ELF signature. However their pattern is not compatible with AppImages.

Normal ELF format normally uses 0x00 0x00 for bytes 8-9 (EI_ABIVERSION and the start of EI_PAD), but the AppImage format repurposes them as a magic identification bytes “AI” (0x41 0x49).

We need to patch Lima’s binfmt_misc pattern to handle this so we can use Rosetta for x86-64 AppImages like the linuxdeploy one.

Here’s the ELF identification bytes:

Lima’s mask is strict on EI_ABIVERSION and EI_PAD, and this causes it to exclude AppImage binaries. We can change the mask to ignore those bytes and match AppImages.

sudo tee /etc/binfmt.d/rosetta.conf > /dev/null << EOF
# Ignore \`EI_ABIVERSION\` and \`EI_PAD\` for AppImage support
:rosetta:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x3e\x00:\xff\xff\xff\xff\xff\xfe\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\xfe\xff\xff\xff:/mnt/lima-rosetta/rosetta:OCF
EOF

# Re-read all `binfmt.d` entries to activate the new rule immediately
sudo systemctl restart systemd-binfmt

Building the AppImage

The VM is now provisioned. The following we run for every build.

First, we sync the code in a VM-private directory, because we don’t want the Linux node_modules installation to mess up our macOS host node_modules.

VM_APP_DIR="/home/$USER.guest/my-app"

limactl shell linux-builder -- rsync -a --delete \
    --exclude='node_modules' \
    --exclude='src-tauri/target' \
    ./ "$VM_APP_DIR/"

If we’re signing the build and TAURI_SIGNING_PRIVATE_KEY refers to a file on the host side, we need to convert it to a plain string so the VM has access.

if [ -f "${TAURI_SIGNING_PRIVATE_KEY}" ]; then
    TAURI_SIGNING_PRIVATE_KEY="$(cat "$TAURI_SIGNING_PRIVATE_KEY")"
fi

Then we set cross-compilation environment variables, and configure Lima to forward them to the VM.

export PKG_CONFIG_ALLOW_CROSS=1
export PKG_CONFIG_PATH="/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/share/pkgconfig"
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=x86_64-linux-gnu-gcc

# We force AppImages to extract to a temp dir instead of FUSE-mounting, because
# the kernel's `compat_ioctl` layer does not fully translate x86-64 FUSE ioctls
# to ARM64. This allows to run x86-64 AppImages like linuxdeploy.
export APPIMAGE_EXTRACT_AND_RUN=1

export LIMA_SHELLENV_ALLOW="PKG_CONFIG_ALLOW_CROSS,PKG_CONFIG_PATH,CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER,TAURI_SIGNING_PRIVATE_KEY,TAURI_SIGNING_PRIVATE_KEY_PASSWORD,APPIMAGE_EXTRACT_AND_RUN"

Install dependencies (adapt to your package manager).

limactl shell --workdir="$VM_APP_DIR" linux-builder -- pnpm install

Actually build.

limactl shell --preserve-env --workdir="$VM_APP_DIR" linux-builder -- \
    pnpm exec tauri build "$@"

Finally copy the artifacts back to host.

BUNDLE_DIR="src-tauri/target/x86_64-unknown-linux-gnu/release/bundle/appimage"

mkdir -p "$PWD/$BUNDLE_DIR"

limactl copy --recursive \
    "linux-builder:$VM_APP_DIR/$BUNDLE_DIR/" \
    "$PWD/$BUNDLE_DIR/"

version=$(jq -r '.version' app/package.json)

for f in "$BUNDLE_DIR/"*"_${version}_amd64.AppImage"*; do
    echo "  $PWD/$f"
done

Wrapping up

Mainly because of the Lima default Rosetta binfmt_misc mask that rejects AppImages magic bytes, this was harder than I expected.

Again, should have really just used GitHub Actions for that. 😅

But hey, this was kinda fun, and I find it “aesthetic” to be able to make a x86-64 Linux build from an ARM Mac without emulation.

Update: Astro v6 and @astrojs/cloudflare v13 simplify a few things described below, including how you configure a custom worker entrypoint. See Astro v6!

Astro allows to prerender pages as static assets, so everything is compiled at build time and can be served super quick.

But also, Astro has the concept of a middleware, that allows to run custom logic in front of every request, which can be handy for things like auth, redirects, proxying and more.

The problem? The middleware is not run for static pages.

Why run the middleware on static pages?

In many cases this is not a problem, because you may not often need to run custom logic in front of static pages. After all if those pages needed custom logic per request, they’d probably be dynamic.

Pages behind auth are most likely dynamic so the content can be contextual to the logged-in user. As for redirects and proxies, they usually make sense when no actual page matches the URL, and Astro runs the middleware in both those cases.

However my use case is a bit different. I’d like to get a sense of what pages are visited on my site, and I don’t like the idea of client-side tracking, partly because of the privacy stigma, and partly because “you can’t trust the client”.

Unnecessary note on client-side tracking

At that point it seems that mostly everyone on the internet does client-side tracking, including every business I ever worked with. Yet I never encountered cases where the data got heavily manipulated.

The only anomalies I ever noticed are the occasional pen test with all sorts of injection attempts, but those typically just get ignored at ingestion because the data is broken, or at worst, it breaks queries because corrupted data was ingested (read: data type mismatch, hopefully we know how to avoid SQL injections by now).

However it seems that most people have something else to do than programmatically sending well formatted but fake tracking data on public endpoints for the mere pleasure of causing chaos for someone else.

Despite that, I’m still allergic to client-side tracking because on paper this is all still possible.

Unnecessary note on HTTP logs

You could say I can achieve all this with HTTP logs without bothering with an edge worker, and you’d be 100% right. However, Cloudflare only gives access to HTTP logs to Enterprise customers and this is not exactly an interesting option for me right now.

If not for that it would definitely be my favorite solution.

Running backend code in front of static pages

Back to the topic. Sadly there’s no generic way I found to run the Astro middleware in front of static pages. This means the solution is gonna be dependent on your adapter. In my case, I’m using the Cloudflare adapter.

We have two layers to deal with here. Out of the box the logic is as follows:

• Cloudflare Workers:
  • If there’s a static asset that matches the URL, serve that.
  • Otherwise, run the Astro worker.js.
• Astro worker.js:
  • If there’s a static asset that matches the URL, serve that.
  • Otherwise, run the user-provided middleware.

The Cloudflare part

In order to mitigate the first layer (Cloudflare), we need to configure the runtime to run the worker code in front to some or all static assets. This is done in wrangler.jsonc using the run_worker_first directive (relevant docs):

{
  "assets": {
    "binding": "ASSETS",
    "directory": "./dist",
    "run_worker_first": [
      "/",
      "/en",
      "/en/*",
      "/fr",
      "/fr/*",
    ],
}

In this case I force the worker to run for the index, as well as /en, /fr and anything under.

This means for other assets like JS/CSS/images, we still skip the worker, but for the static pages I have that match those paths, Cloudflare will run the edge worker.

The Astro part

Now we have Cloudflare run the Astro worker in front of static pages, but it’s still not enough, because the Astro Cloudflare adapter skips our middleware anyway when a static asset matches.

if (app.manifest.assets.has(requestPathname)) {
  return env.ASSETS.fetch(request.url.replace(/\.html$/, ''))
}

In order to solve that, we can’t use the Astro middleware anymore. Instead we need to configure a custom entry point for the worker. This means we now control the top-level worker code and run our logic there, regardless what the adapter decides to do.

This is done with workerEntryPoint option in astro.config.mjs:

import { defineConfig } from 'astro/config'
import cloudflare from '@astrojs/cloudflare'

export default defineConfig({
  // ...

  adapter: cloudflare({
    workerEntryPoint: {
      path: 'src/worker.ts',
    },
  }),

  // ...
})

Where src/worker.ts is a custom Cloudflare Worker entry file as documented here:

import type { SSRManifest } from 'astro'
import { App } from 'astro/app'

import { handle } from '@astrojs/cloudflare/handler'

type Env = {
  [key: string]: unknown
  ASSETS: {
    fetch: (req: Request | string) => Promise<Response>
  }
}

export function createExports(manifest: SSRManifest) {
  const app = new App(manifest)

  const fetch: ExportedHandlerFetchHandler<Env> = async (request, env, ctx) => {
    const url = new URL(request.url)
    const { pathname, search } = url

    // Do anything before Astro handles the request

    const response = await handle(manifest, app, request, env, ctx)

    // Do anything after

    return response
  }

  return {
    default: {
      fetch,
    } satisfies ExportedHandler<Env>,
  }
}

What about development?

The workerEntryPoint is great for production, but astro dev won’t pick up on that. So if you need any of this logic to also run in development, you need to abstract it and also include it in middleware.ts.

This works fine even for static pages because Astro do run the middleware when generating static pages, it just outputs a warning if you try to access things like request headers.

In my case, I chose to move all my production logic in worker.ts, so I don’t rely on the middleware whatsoever in production. I use a conditional export like follows in order to keep the middleware only in development, where it mimics what worker.ts otherwise does in production.

import type { MiddlewareHandler } from 'astro'

const handler: MiddlewareHandler = async (context, next) => {
  // ...
}

export const onRequest = import.meta.env.DEV ? handler : undefined

Astro v6 update

Astro v6 and @astrojs/cloudflare v13 change a few things (for the best). The Cloudflare part (run_worker_first in wrangler.jsonc) is unchanged.

The workerEntryPoint adapter option was removed. Instead, simpler, we just point main in wrangler.jsonc directly to our custom worker file:

{
  "main": "./src/worker.ts"
}

Inside there the syntax is slightly different since we’re in a raw Cloudflare Worker environment, not wrapped by Astro.

import { handle } from '@astrojs/cloudflare/handler'

type Env = {
  [key: string]: unknown
  ASSETS: {
    fetch: (req: Request | string) => Promise<Response>
  }
}

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    const { pathname, search } = url

    // Do anything before Astro handles the request

    const response = await handle(request, env, ctx)

    // Do anything after

    return response
  },
} satisfies ExportedHandler<Env>

As for development, astro dev now runs on Cloudflare’s workerd using the same entrypoint as production, so no need for the middleware workaround anymore. Sweet!

Wrapping up

In short: configure run_worker_first on Cloudflare so it runs the worker in front of static pages, then use a custom workerEntryPoint (Astro v5) or a custom main in wrangler.jsonc (Astro v6) so you get full control over the worker, and can run code outside of the middleware (which does not run for static pages).

nodejs 24.13.1

Then your Cloudflare deploy fails with:

Initializing build environment...
Success: Finished initializing build environment
Cloning repository...
Found a .tool-versions file in repository root. Installing dependencies.
Restoring from dependencies cache
Restoring from build output cache
Failed: error occurred while installing tools or dependencies

There’s a couple threads on Cloudflare Community about this and similar .tool-versions issues. They get closed after 15 days without any answer, with the oldest one from 2023 and still no solution to this day.

The fact Cloudflare Workers (and Cloudflare Pages) look at .tool-versions is undocumented, it so happens that it chokes on even the most basic .tool-versions possible, so it essentially means the mere presence of this file in your project will break your build on Cloudflare, without any way to turn off this behavior (like forcing Cloudflare to ignore that file). As reported in this issue, the SKIP_DEPENDENCY_INSTALL environment variable does not help with this behavior.

The solution

So what’s left? Well, I had to remove .tool-versions from my repository.

Instead, I moved it to .tool-versions.template, and when setting up the repo in any environment that actually supports .tool-versions, I just cp .tool-versions.template .tool-versions (with .tool-versions being in .gitignore).

Setting the correct Node.js version on Cloudflare

As for Cloudflare, in order to set the proper versions, I’m using the NODE_VERSION and PNPM_VERSION build environment variables. (Also NPM_VERSION and YARN_VERSION depending on your package manager of choice).

NODE_VERSION=24.13.1
PNPM_VERSION=10.29.2

This is, of course, also undocumented, but it works!

Squamish

I’m well settled in Squamish now. Two years already!

As an introvert and working remote, it was a bit of a slow start rebuilding social circles from scratch. It really takes being intentional about it. Facebook groups and the Oak app are pretty sweet, and believe it or not, talking to strangers IRL also works! The good thing is that the more people you know, the more people you meet, so it gets pretty effortless over time.

Mountains 🏔️

In 2025 I’ve been out in the mountains like crazy, and hit 130,000 meters of elevation gain all sports combined (ski touring, trail running, gravel and mountain biking). It’s my biggest elevation gain year lifetime, 30,000 meters more than 2024. 💪

That includes scrambling Sky Pilot, climbing Star Check (3 times lol), Cloudburst, Goat Ridge scramble, Blackcomb Peak ridge scramble, a marathon to Castle Towers, Gentian Peak and Panorama Ridge, Ossa Mountain, Rainbow Mountain, the Armchair Traverse (Mount Cook and Mount Weart), Locomotive Mountain and its loop scramble, Coliseum Mountain, and finishing with the Howe Sound Crest Trail (with extra Harvey, Brunswick and West Lion lol get rekt). What a year!

About part-time work

If you’re wondering how I go in the mountains that much, you need to know I’ve been working part-time as a software contractor since 2021. Going part-time was the best thing I’ve ever done in my career (other than connecting a ping-pong table to the internet 🏓) and I’m incredibly grateful to have worked with companies who gave me that opportunity.

Maybe I should write more about this because it’s still really uncommon in the industry, but believe it or not, those years have also been the most productive of my career.

It’s definitely a combination of factors. Despite working only 20 hours a week:

• I’m naturally more experienced now than I was years ago.
• I have been intentional about working with small companies (read: less than 10 people) where I can have a sizable impact, without being slowed down by corporate friction, processes and politics.
• Parkinson’s law is a thing (“work expands so as to fill the time available”).
• And of course since a few years and increasingly, using AI.

Still, this means that there’s a sweet spot for time-to-productivity ratio, especially when it comes to creative work like building software, and in many cases I’m not convinced that it’s at or above 40 hours.

Travel ✈️

Mexico 🇲🇽

Went to Mexico for a work retreat.

Montreal

Did a pit stop by Montreal to catch up with friends and the 🔥 food scene there.

Toulouse

Did a quick pit stop in Toulouse, which I visited for the first time, since my flight landed there.

Andorra 🇦🇩

Visited friends in Andorra, also first time for me there. There’s some sick mountain biking and trail running. Lots of ridges to scramble, everywhere, and all the mountains are connected by trails, so it feels like there’s really no limits to the terrain!

Camargue 🦩

Another pit stop at Saintes-Maries-de-la-Mer to cut a long drive in half. Also first time here, very pretty!

Metz & Nancy

Finally some family time around Metz and Nancy.

Cakes 🍰

I also happened to turn 30 on that trip. While I don’t believe the specific number means much at all, I still see no reason to not treat myself to 3 different cakes. 😜

Nova Scotia 🦀

I bundled all the above destinations together in July. Nova Scotia was a separate trip.

A good friend of mine was getting married there, and I got to stand at his wedding. Took that as an opportunity to go explore around the Cape Breton and particularly ride the Cabot Trail on my friend’s road bike that I borrowed. Around 300 km and 3,000 meters of elevation that I split in two days. It was beautiful.

Shortest move ever

At the end of the summer, my landlord sold the place I was renting, and I had to move. I got lucky and found a place in the same building just across the floor the same day I got the notice. Still can’t believe this happened. 🙏

This made for a pretty easy and quite ridiculous move, with me dragging my stuff across the hallway.

The big jump 🏃

Remember how I was writing about part-time work earlier? Well all good things have an end, and this was not an option anymore at the company I had been working until then.

Going full-time right before ski season didn’t feel exactly right, and it really felt like a sign for me to 1. take some proper time off and 2. get out of my comfort zone and try something a bit scarier.

The time off consisted of a fuckton of climbing, then skiing. Being in BC, we eventually got a few of the usual warm storms where it rains all the way to the top of mountains and destroy the skiing conditions until it snows again. This gave me some solid windows to start building again.

We got together with my friend Ben and started EveTools, where we make apps for developers.

The first app is Flame, and its goal is to remove as much friction as possible from the Firebase local development experience, especially when it comes to dealing with the emulators.

We’ve been working with Firebase quite extensively for over 3 years now, so we have a pretty good understanding of the pain points of the current experience. There’s a lot to do, and I hope we can have a positive impact on that platform.

At the time of writing it’s in private beta, but we’re planning on opening it up pretty soon! If you find about Flame via this post, shoot me an email and I’ll send you a discount! 🫶

Two interesting realizations since this happened.

Buildingception

First, building a product, and doing so end to end (read: not just the tech), reveals a lot more pain points and problems to be solved. Some specific to the stack we work with, and some broader ones too. And the good news is, a lot of them can be solved with more tech!

In other words, the more I build, the more ideas I get about what to build next.

Granted it’s not the best way to source ideas if you’re optimizing for maximum revenue, but it seems to be doing a decent job at optimizing for maximum motivation, and I do enjoy that for the time being.

So much for part-time

Second, is that despite advocating for the benefits of part-time work for the past 4 years, including higher up in this article, I’m actually having a really good time working every single day right now, weekends included. Working on your own thing does hit different.

I hope my fellow coastal BC skiers don’t read this, but I’m lowkey grateful for this rain-into-dry-spell event a few weeks ago, so that I feel no guilt and FOMO to be so much on my laptop.

Ultimately, I still believe in part-time work, and in fact, being an independent developer is my current best bet on building that lifestyle back one day or another. But it also seems like a futile dream until I generate any sustainable income.

Let’s see where the snow takes me…

On coffee ☕️

I’m back to drinking caffeine, after years of being on decaf. 🤷‍♀️

Seems to pair well with the business hustling for now. We’ll see if I build up a tolerance again. If it stops being a net positive I’ll readjust.

And weirdly, after being into specialty coffee for years (read: small batch micro roaster beans I weigh and grind before brewing), I’m back with my moka pot and sous vide Italian pre-ground. Who would have thought?

A few words on 2024

I know, I know, I skipped the routine update last year. To be fair there was no important update to write about, which is probably why I didn’t feel the need to write. Still it included many cool adventures and trips that I might as well slide in this post.

First there was the northern lights. Took the camera out for the occasion.

Of course, the usual local mountain adventures. Including skiing Panorama Ridge, scrambling West Lion and Black Tusk, Mount Currie, running a 60K to Diamond Head and Mamquam Lake, Sigurd Peak, biking the Triple Crown (Cypress, Grouse and Seymour), and finishing with a marathon to Overlord Mountain!

Went to Jackson Hole for a work retreat, and took some extra time off there to explore the mountains and do a lot of road and gravel biking, including riding around Yellowstone, with a colleague who’s an absolute triathlon machine. Those few weeks are probably the most volume I’ve done in a continuous stretch to this day, although the Andorra trip from last year was a close contender.

Also went sailing in Majorca with a few friends!

And finished by some trail running in the Vosges.

On reflecting

Putting together all those photos is pretty time consuming, but honestly it feels valuable to take that time to reflect on the past and really appreciate everything that I experienced.

It’s easy to get caught up in the fast paced train of life and never take a step back to contemplate the big picture. Those “now page” updates help me do exactly that.

macOS has a setting where it shows fixed scrollbars to people using a mouse, while people using a trackpad have tiny “floating” scrollbars that are entirely hidden when not actively scrolling.

You can find it in Appearance > Show scroll bars and either force it to always on or always off (or keep it auto).

Story time

While developing a macOS app (in my case with Electron, although this problem is not specific to Electron), I encountered a wild bug.

Some users reported having scrollbars visible in different parts of the app, and looking quite “off” visually:

However on my side it looked just fine:

I could not understand what was causing this. After all, it was happening across the same version of Electron, Chromium, of the app itself, and of macOS!

It’s only when another developer reported having the bug that I jumped on a call with him to debug the issue.

While messing with the dev tools, one thing jumped out to me: inside his dev tools, scrollbars were visible at all times:

While on my side I only had floating scrollbars while I was scrolling, and they would disappear entirely otherwise:

Same version of macOS as well!

What was going on?

It turns out the culprit was that my colleague was using a mouse, while I was using the trackpad of my laptop.

What the mouse vs. trackpad have to do with this? Meet this setting:

By default, macOS shows scrollbars at all times when using a mouse, but uses floating scrollbars when using a trackpad!

Now I could force this setting to “Always” to reproduce the issue locally, and update the app to look OK even for people who use a mouse. 🙃

In many places, we had unnecessary overflow: scroll in places where overflow: auto would do, and a few places where we had to hide scrollbars entirely with overflow: hidden.

It was easy to make those silly mistakes when all the devs working on the app were using a trackpad. 😂

Bonus: dark mode scrollbars

For the places where we did want scrollbars, there was a remaining issue: we force our app in dark mode, but the scrollbars were showing in light mode nevertheless!

The way we force our Electron app in dark mode is by doing:

import { nativeTheme } from 'electron'

nativeTheme.themeSource = 'dark'

However in order for native scrollbars to show in dark mode, we also had to add the following to our HTML file:

<body style="color-scheme: dark"></body>

(This is not the place where we actually needed scrollbars, but for lack of a better screenshot, here’s what it would look like with both directions scrollbars:)

• Signing Electron apps with GitHub Actions
• Installing an Apple certificate on macOS runners for Xcode development
• Setting up hosted macOS GitHub Actions workflows for Electron builds

But what to do if your GitHub workflow just hangs forever at the Electron signing step?

This appears to be a symptom of not properly configuring the macOS Keychain in the CI environment. Sadly there could be a bunch of reasons for that and the hanging doesn’t really tell us which one specifically is a problem.

There’s two issues I found with that hanging problem, and the solutions there may or may not solve the problem for you.

What I’m gonna suggest though is really double checking the code you’re using to import the signing keys based on all the links I shared above, and see if you’re missing something.

If it can help, here’s the code that ended up working for me:

name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - uses: swift-actions/setup-swift@v2

      - name: Import certificate
        env:
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
          PRIVATE_KEY_PASSWORD: ${{ secrets.PRIVATE_KEY_PASSWORD }}
          CERTIFICATE: ${{ secrets.CERTIFICATE }}
        run: |
          # Create a temporary keychain
          security create-keychain -p "" build.keychain

          # Set it as default for the user session
          security default-keychain -s build.keychain

          security unlock-keychain -p "" build.keychain

          # Set it to lock in 1 hour (should be long enough, and probs longer than the macOS default that could be too short)
          security set-keychain-settings -t 3600 -l ~/Library/Keychains/build.keychain

          mkdir -p ~/certificates
          cd ~/certificates

          echo "$PRIVATE_KEY" | base64 --decode > "My App.p12"
          echo "CERTIFICATE" | base64 --decode > "My App.cer"

          security import "My App.p12" -k build.keychain -P "$PRIVATE_KEY_PASSWORD" -T /usr/bin/codesign
          security import "My App.cer" -k build.keychain -T /usr/bin/codesign

          # Check certificates
          security find-identity -v -p codesigning build.keychain

          # Add keychain to search list
          security list-keychains -d user -s build.keychain
          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "" build.keychain

      # ...

Here, PRIVATE_KEY is a Base64-encoded version of the .p12 private key, password protected by PRIVATE_KEY_PASSWORD.

CERTIFICATE is a Base64-encoded version of the .cer file that Apple provided for your application.

Hope that helps!

This is neat, but what if you want to do do the same thing from your own app?

I’ve had to do this recently, so this blog post will compile everything I learnt about and especially the undocumented quirks I encountered and worked around.

kCMIOHardwarePropertyAllowScreenCaptureDevices

The very first thing you need is to enable kCMIOHardwarePropertyAllowScreenCaptureDevices.

This is a “hardware property” (whatever that means) that, when set, allows the current process to access USB-connected mobile devices for screen recording.

You can find many flavors of how to do this online, and here’s mine anyway:

import CoreMediaIO

// Sets the "hardware" prop that allows to discover USB mobile devices for screen recording.
func allowScreenCaptureDevices() {
  let element: CMIOObjectPropertyElement
  if #available(macOS 12.0, *) {
    element = CMIOObjectPropertyElement(kCMIOObjectPropertyElementMain)
  } else {
    element = CMIOObjectPropertyElement(kCMIOObjectPropertyElementMaster)
  }

  var prop = CMIOObjectPropertyAddress(
    mSelector: CMIOObjectPropertySelector(kCMIOHardwarePropertyAllowScreenCaptureDevices),
    mScope: CMIOObjectPropertyScope(kCMIOObjectPropertyScopeGlobal),
    mElement: element)

  var allow: UInt32 = 1
  let dataSize: UInt32 = 4
  let zero: UInt32 = 0

  CMIOObjectSetPropertyData(
    CMIOObjectID(kCMIOObjectSystemObject), &prop, zero, nil, dataSize, &allow)
}

This will allow you to discover USB mobile devices as part of your usual AVCaptureDevice.DiscoverySession.

Now while this code uses a relatively verbose low-level old C interface (because it’s the only way to do this right now), it’s fairly straightforward. It’s spiritually equivalent to doing kCMIOHardwarePropertyAllowScreenCaptureDevices = 1 (no shit).

But this hardware property is not as innocent as it looks, and I’m about to infodump on you everything I found out about it. Brace yourselves (or skip to the next section until you encounter weird issues and need to come back here 😂).

It’s not instant

When you set kCMIOHardwarePropertyAllowScreenCaptureDevices, the effect is not instant, meaning if you do a AVCaptureDevice.DiscoverySession right after, you’re basically guaranteed to not see the connected USB mobile devices.

This is not necessarily a problem. For example if your Swift process is long-running, you set that prop first thing on boot, but you actually list the devices later on upon user interaction, everything will be fine.

However if you’re working with a CLI (i.e. my-cli list-devices / my-cli record-device <device>), or simply need access to the mobile devices immediately upon starting the app, this is not gonna cut it.

After setting the prop, the devices are gonna take up to a few seconds to “show up”, and you can listen to the AVCaptureDeviceWasConnected notification from the NotificationCenter to know about it. There’s a good example for that in this Gist.

// See "The get devices warmup side-effect" below for why this is necessary...
let _ = AVCaptureDevice.devices()

NotificationCenter.default
  .addObserver(
    forName: NSNotification.Name.AVCaptureDeviceWasConnected, object: nil, queue: nil
  ) { (notif) -> Void in
    let device = notif.object! as! AVCaptureDevice
    // ...
  }

This works, but it also means there’s no way to tell immediately that no device is currently connected. This is a problem if you want to implement my-cli list-devices. Your best option is to time out after a few seconds, but it’s not ideal because of the added delay when no device is connected…

The get devices warmup side-effect

This one is super sneaky and I wasted a lot of time on it. It turns out that if you don’t call an API to list the devices, i.e. the deprecated AVCaptureDevice.devices, or now a proper AVCaptureDevice.DiscoverySession, the AVCaptureDeviceWasConnected notification will never arrive.

So you need to start a DiscoverySession first, expecting to get 0 devices back (because you just set the hardware prop and its effect is not instant), just to “warm up” the system, so that it will actually send the notification.

In the Gist I linked earlier, the print("\(AVCaptureDevice.devices().count)") line is actually significant and the code will not work without it:

func start() {
  print("\(AVCaptureDevice.devices().count)")

  NotificationCenter.default
    .addObserver(
      forName: NSNotification.Name.AVCaptureDeviceWasConnected, object: nil, queue: nil
    ) { (notif) -> Void in
      self.iosDeviceAttached(device: notif.object! as! AVCaptureDevice)
    }
}

It’s not just the innocent debug print that it seems. The fact it calls AVCaptureDevice.devices is what allows to warm up the system and for the notification to actually be sent later on. Without it, the notification will never arrive.

I like to make it a bit more explicit with:

// We don't need the data but this appears to be required to "warm up"
// the system. If we don't make the system call to get devices first,
// we can't discover new devices with `AVCaptureDeviceWasConnected`. 🤷
let _ = AVCaptureDevice.devices()

It’s rate limited?

This one also made me pull my hair out for a while. So I start my app that sets the above hardware prop, listen to device connected notifications, and can see the iPhone available for screen recording.

Then I iterate on my code, maybe add some logging or write come code to actually start capturing the video feed, and then restart the app.

And then, not only setting kCMIOHardwarePropertyAllowScreenCaptureDevices takes a few long blocking seconds to complete, but on top of that I don’t ever get any device connected notification despite the iPhone being plugged in!

It appears to me that setting this prop is somehow rate limited. I would need to wait around a minute before launching my CLI again in order for it to behave “normally” (where setting the prop is near-instant, and I do get a notification for the plugged-in devices).

However, and that’s where it gets interesting, I noticed that if any other process on the computer also sets that same hardware property (i.e. QuickTime), and that process stays running in the background, then my CLI would reliably work every single time, even if I launch it many times in a short time span. So it’s like that “rate limit” is really an issue if my CLI is the only process on the system to set that prop.

So what did I do? I made a my-cli background command that literally only sets the kCMIOHardwarePropertyAllowScreenCaptureDevices prop, then sleeps indefinitely. Ran that in the background, then could do my-cli list-devices and so on as much as I wanted.

Wasn’t gonna cut it for me for production, but at least that was useful during development to allow me to iterate quickly.

Actual device recording

I won’t go in much details here because there’s actually no quirks on that side of things. It’s just your typical AVFoundation recording which is very well covered online already.

First we get the external devices via a DiscoverySession:

let devices = AVCaptureDevice.DiscoverySession(
  deviceTypes: [.external],
  // Muxed type seems to be a decent way to distinguish USB connected
  // mobile devices from other external devices like e.g. "OBS Virtual Camera".
  mediaType: .muxed,
  position: .unspecified
).devices

This returns a list of AVCaptureDevice. Alternatively if we have the ID of a mobile device already:

let device = AVCaptureDevice(uniqueID: "...")

Then we make an input from that device:

let deviceInput = try AVCaptureDeviceInput(device: device)

And the rest is the usual AVCaptureSession protocol.

Wrapping up

If you encountered any if the quirks above, I hope that it helped you work around them and hopefully you didn’t waste as much time on this as I did. Happy device recording!

This is a nice feature when you’re looking at the logs after a run is completed.

However when you’re trying to debug a timing-based issue live, this makes it really annoying because the logs are buffered the entire time the process runs and only spit out at the end! And then we can’t see which package logged what first because the logs got grouped by package instead of being in a merged stream.

I ended up dissecting the source of Turborepo to figure out what causes this behavior inside GitHub Actions. I found it.

It’s triggered by the GITHUB_ACTIONS environment variable being present.

So running unset GITHUB_ACTIONS before running turbo run turns off this behavior!

In theory that should suffice but I had the following in my notes so I’ll also leave it here in case it helps:

unset $(env | grep RUNNER | cut -d= -f1)
unset $(env | grep GITHUB | cut -d= -f1)

Triggering a full index

BTW to trigger a full index, either change the Algolia extension config from the Firebase console, and make sure that the Full Index existing documents field is set to true.

If it’s already on true (so that won’t trigger an actual config change) and you don’t want to change anything else in the config, you can set it to false, wait 5 minutes for it to deploy, then set it to true again (lol). Or, better, go in Google Cloud Console, in Cloud Task, and for the ext-firestore-algolia-search-executeFullIndexOperation task queue, select Actions > Force a task run.

Errors during full index

I was looking at the ext-firestore-algolia-search-executeFullIndexOperation Cloud Function logs to monitor the index operation, and after a few minutes it choked with a 400 error (but I’ve also seen 403).

The logs are really unhelpful because the request body gets logged entirely first, but in my case it’s too big truncates the log line, and so if this function logs the response body (which I’m not even sure), it’s not accessible because the line got truncated in the request part.

It took me longer than I’m willing to admit to figure that, but I found out that there’s a API Monitoring section on Algolia where we can Search API Logs and I could see the 400 and 403 errors there!

In my case the errors were:

{
  "message": "Record at the position ... objectID=... is too big size=.../10000 bytes. Please have a look at https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/in-depth/index-and-records-size-and-usage-limitations/#record-size-limits",
  "status": 400
}

{
  "message": "You have exceeded your Record quota. You’ll need to change your plan for more capacity, or delete records. See more details at https://www.algolia.com/account/billing/details?applicationId=...",
  "status": 403
}

That’s much more useful.

Turns out my staging env had too many records already for its plan (free plan) so I couldn’t sync more during the full index, and in another case the record I was trying to write was too big for the free plan max record size.

I wasn’t having the error in prod because we use a paid plan there.

So the solution was simple. Upgrade staging to a paid plan so I can do my testing!

After that I triggered a full index again and it worked just fine. 🙏

Also: queue name length

Another reason the full index could fail, as reported by a reader (a friend who independently stumbled upon my blog, love when this happens lol), is if you give a name to the extension that’s over 33 characters, because after that the queue name gets truncated and the extension can’t find the queue.

In my example above the full queue name is ext-firestore-algolia-search-executeFullIndexOperation, and we control the firestore-algolia-search part of the name. That’s what can’t be more than 33 characters. If it is, then you get something like ext-firestore-algolia-search-workspaces-executeFullIndexOperati which Algolia can’t handle.