DEV Community: Duvan Jamid Vargas

Two Phones, One Dongle, One Car: Building a Phone Switcher for Android Auto (and Knowing When to Stop Reverse Engineering)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:30:12 +0000

It started with a small question: what can we improve on our wireless Android Auto dongle?

Two people, one car, one Carlinkit CPC200-2Air dongle (5.0 / U2AC, AutoKit firmware), and every time we swapped phones it was a manual, slightly miserable dance: turn Bluetooth off on one phone, wait, hope the other one connects first. A lot of poking later we had a full Android app with its own screen inside Android Auto, a BLE presence protocol between phones, a live dongle monitor, a CI pipeline that ships signed releases, and a pile of research notes about what the dongle does inside, including the exact point where we decided to stop.

This is the whole story, dead ends included. The code is MIT-licensed and public: muvatec/switch-phone-aa.

Disclaimer. This is an independent project, not affiliated with Carlinkit, HeWei, Google or Android Auto. It uses the web API the dongle itself exposes for its own settings page, and it contains no manufacturer binaries or code. Use it at your own risk: some actions restart the dongle and may require re-pairing.

1. The problem

A wireless Android Auto dongle stores several paired phones, but it only keeps one linked at a time. When two people share the car, "who gets the car now?" has no first-class answer:

The dongle has a list of saved phones, but no "connect to phone X" command.
It doesn't tell you which phone is currently connected (more on that below).
The phone that was connected before tends to reconnect on its own, because its Android Auto is in automatic mode.

So the goals grew as we learned:

Understand how the firmware works and what could be improved.
See how the dongle behaves without sitting in the car.
Support several phones and switch between them easily, ideally from the car screen.

2. First dead end: speaking the "Carlinkit protocol"

Plugged into a Mac, the dongle enumerates as 12D1:0001 named AutoKit (later VISION after a firmware update), with a vendor-specific interface, bulk endpoints and one interrupt endpoint.

The community has built several open-source clients for these dongles (pi-carplay, FastCarPlay, node-CarPlay) that speak a proprietary protocol with a 0x55AA55AA header, a length, a type and an inverted type. We patched pi-carplay to accept this VID:PID and sent it the usual messages. The dongle answered every message with the same 12 bytes:

0c000000 03000520 <n>

It never sent video, never reported a phase, and reset USB after two to four seconds of silence. We tried the optional USB encryption some newer firmwares use (header 0x55BB55BB, AES-128-CFB). No change.

For a while we assumed this firmware spoke some newer, undocumented variant. We were wrong in an instructive way: those 12 bytes were MTP.

Later, reading the dongle's own plain-text boot scripts, we found start_mtp.sh: in its idle mode (no car attached) the dongle presents itself as an MTP device (mtp-server). Decoding the reply as an MTP container:

Field	Value	Meaning
length	`0x0000000c`	12 bytes
container type	`0x0003`	Response
response code	`0x2005`	Operation Not Supported
last field	`<n>`	the transaction id, copied from whatever bytes we sent

The dongle wasn't speaking a secret protocol. It was politely telling us, twelve bytes at a time, that it didn't support what we were asking, because we were talking to the wrong USB personality. A good reminder to identify the mode of a device before reverse engineering its protocol.

3. The first big hit: the dongle is an Android accessory

Sending the standard USB control request 51 (GET_PROTOCOL) from Android Open Accessory (AOA) returned 2. The dongle presents itself to the car as an Android phone in accessory mode:

It enumerates as 12D1:0001 in its idle MTP mode.
When a "head unit" performs the AOA handshake, scripts kill adbd and mtp-server and the device switches to 18D1:2D00 (accessory).
It then speaks Android Auto 1.7 over TLS 1.2 (ECDHE-RSA-AES128-GCM-SHA256).

That means Google's official Desktop Head Unit (DHU), the tool for testing Android Auto apps without a car, can act as the car, talking directly to the dongle over USB:

DONGLE_SERIAL=<usb serial> tools/run-dhu.sh

Two gotchas we paid for:

Always pass the dongle's serial. Without --usb=<serial> the DHU grabs every compatible USB device, including your phone on a cable, and flips it into accessory mode (which also kills USB tethering).
For the dongle to stream anything, a phone must already be linked to it over Bluetooth and WiFi, exactly like in a real car.

From that moment we could develop and test the whole thing on a desk.

4. The second big hit: the dongle's web API

The dongle creates a WiFi network (AutoKit_xx) and serves a configuration page on its own address using a small embedded web server (Boa) with a Vue front end. Chrome on Android often forces HTTPS and refuses to load it, which is one reason a native app is useful.

We downloaded the page's JavaScript and read how it talks to the device. Everything goes through one CGI endpoint:

POST /cgi-bin/server.cgi
Content-Type: application/x-www-form-urlencoded

cmd=<command>&[item=<key>&val=<value>&]ts=<epoch ms>&sign=<md5>

The signature is an MD5 over the sorted fields plus a constant that the page's own JavaScript sends to every client, so it is an integrity check on the form, not a secret. (A first 400 Bad Request turned out to be a missing /cgi-bin/ prefix.) The commands we use:

`cmd`	What it does
`infos`	Everything: `BoxInfo`, `Settings`, `DevList` (saved phones), `WifiChannelList`, `ModuleInfo`
`set` (`item`, `val`)	Change a setting
`restart`	Reboot the dongle (~20 s)
`BoxMonitor`	CPU rate/temperature/frequency, memory rate, WiFi RX/TX in Mbps
`carInfo`, `syncTime`, `logFile` ...	Car metadata, time sync, logs
`reset`	Factory reset (we don't touch it lightly)

From infos we could finally see the real firmware version, read every setting, and change a couple (fastConnect, mediaDelay). We also discovered what the API doesn't give us, which shaped the entire design.

5. What the dongle knows, and what it doesn't

DevList stores paired phones, but there is no "connect to X" command.
There is no reliable "who is active" field. MDLinkType says AndroidAuto when linked, but MDModel comes back empty, and the index field in DevList lies (we first used it and marked the wrong phone as active).
A saved phone may have no name; you learn it when the phone connects, or rename it by hand.

So how do you switch? Restart the dongle. When it comes back, whichever saved phone is actively looking connects first. With both people nearby this worked with no tricks, in about 30 seconds: ~5 s to shut down, ~21 s to boot, ~5 s for the new phone to connect.

The remaining problem: who is where? The dongle can't say. So the phones have to.

6. Presence over Bluetooth Low Energy

Every phone running the app advertises its own state over BLE and listens for the others. There is no GATT connection; everything rides in a non-connectable advertisement:

service data (9 bytes) = hash(4) + flags(1) + target(4)

hash   = first 4 bytes of MD5(lowercase Bluetooth name)
flags  = bit0 projecting Android Auto
         bit1 requesting control
         bit2 rejected
         bit3 accepted
target = hash of the phone this message is addressed to (00000000 = nobody)

The 4-byte hash is matched against the names the dongle has saved, which yields three states per phone:

State	How it's decided
ACTIVE	The phone itself knows (`CarConnection` says it's projecting); others see the `projecting` flag in its beacon
AVAILABLE	Saved in the dongle and its beacon was heard in the last 45 s
SAVED	Saved in the dongle, not heard

The request / accept protocol

Phone B sees that A is projecting and offers Switch to this phone (or the user taps Request connection in the app, in a quick-settings tile, or from a launcher shortcut).
B sets the requesting bit for 45 s, addressed to A.
A hears it and shows an accept / reject prompt: a heads-up notification delivered through Android Auto itself (so it reaches the driver even while Waze or Spotify is on screen), a modal in the app, and a regular notification.
If A accepts, it asks the dongle to restart. B, now the only phone looking, connects.
A answers over the same channel for 30 s with accepted or rejected, so B can show what happened and let the user retry.

stateDiagram-v2
    [*] --> IDLE
    IDLE --> WAITING: user requests control
    WAITING --> ACCEPTED: A accepts
    WAITING --> REJECTED: A rejects
    WAITING --> TIMEOUT: no answer in 45 s
    REJECTED --> WAITING: retry
    TIMEOUT --> WAITING: retry
    ACCEPTED --> IDLE: phone B is now projecting

The security trade-off we chose

The beacon isn't authenticated: anyone who imitates a saved phone's 4-byte hash could ask for a switch. So the active phone must approve. Auto-accept exists, but is off by default, and the contribution rules forbid changes that enable anything that gives up the car without confirmation. The beacon contains only a hash of the Bluetooth name, no personal data.

7. Drawing our own screen in the car

Our first car UI used the standard Android for Cars templates (IoT category): a list and a grid. It worked, and it looked like every other templated car app. You can't change backgrounds or cards.

We wanted rounded cards, light/dark theme, colored states. The only way to draw freely on the car screen is the navigation category: you receive a Surface through a SurfaceCallback and paint on it with a Canvas. Touches arrive through SurfaceCallback.onClick; the theme comes from CarContext.isDarkMode.

The costs, stated plainly:

It needs the androidx.car.app.NAVIGATION_TEMPLATES and ACCESS_SURFACE permissions.
Navigation apps have extra review requirements on Google Play, so for now we distribute an APK and rely on Android Auto's Unknown sources developer option.

The honest failure: it didn't show up in a real car

Tested in a real car with a Pixel 9 and Unknown sources enabled, the app did not appear in the car's launcher or in "Customize launcher". In the DHU it appeared perfectly. The system log buffer (256 KB) had already rolled over by the time we looked, so we couldn't see why.

Our hypothesis (not a confirmed fact): Android Auto is stricter with the navigation category for sideloaded apps; other sideloaded navigation apps report the same. What we did about it:

Added a second entry in the IoT category with standard templates as a fallback.
Added CarLog, a persistent 200 KB log of what Android Auto does with the app (service created, host, screen, size, touches) that can be shared from the app, so the next attempt has evidence.

Everything has been validated with the DHU and the dongle on a desk. We say so in the repo.

8. Bugs that taught us something

A short list of real ones from the project log:

Symptom	Cause	Fix
App crashed when opening in Android Auto	A `Row` without a title, because the dongle returned a phone with no name	Always provide a label fallback
Crash when switching phones	A template in `loading` state can't carry an icon or actions	A separate template for the loading state
"Active" marked the wrong phone	We trusted `DevList.index`	Each phone reports about itself
The idle phone gave up the car without asking	First design executed requests directly	`RequestInbox` plus explicit accept/reject
No way to retry	The requester never learned the result	BLE response and `WAITING / REJECTED / TIMEOUT / ACCEPTED` states
"No requests load" on phone #2	Its Bluetooth had been turned off; presence only started once at app launch	Presence restarts with Bluetooth state; the screen now says Bluetooth off / Missing permissions / Searching...

Two longer investigations are worth telling.

A new phone wouldn't connect. Android Auto's logs showed WIRELESS_SETUP_FAILED_TO_START_NO_HFP_FROM_HU_PRESENCE: the Bluetooth link to the dongle dropped after ~2 s, and wireless Android Auto requires the dongle's hands-free profile (HFP). The dongle serves one Bluetooth connection at a time. Turning off Bluetooth on the other phones, forgetting the pairing and re-pairing with "Phone calls" enabled fixed it.

Android Auto felt slow on one phone. The link itself was healthy: audio acks around 23 ms, 5 GHz WiFi at 270 to 300 Mbps. But the phone was nearly out of RAM with swap at 92 %, system_server at 94 % CPU, and Android Auto's frame limiter flapping between 60 and 30 fps. The dongle and the WiFi were innocent. That's why the app now measures the phone's own memory and warns, next to a live dongle monitor (temperature, CPU, memory, WiFi throughput with an overheating alert).

9. The wall: `server.cgi`

The obvious next question: is there a hidden command to switch phones without a 30-second reboot? The CGI binary behind that API might know.

We took the public 2024.10 firmware published by the community (the same community whose work made much of this possible: ludwig-v/wireless-carplay-dongle-reverse-engineering) and ran strings on server.cgi. Nothing useful. The reason:

Fact	Value
Format	32-bit ARM EABI5 static ELF, no section headers
Size	42,304 bytes
Entropy	~7.9 bits/byte almost everywhere (compressed or encrypted)
`strings`	478 lines, all noise

A small disassembly of the loader (725 ARM instructions, with capstone) showed a UPX-style in-memory self-extractor with LZMA, plus a hardware-encryption layer:

Open /proc/self/exe and locate the payload.
mmap2 an anonymous buffer.
If the payload is large enough, open /dev/hwaes (the string is assembled byte by byte so it isn't greppable) and call ioctl(fd, 0xC00C6206, {src, dst, len}): a request served by a kernel driver, not by code in the file. The key never appears in the binary.
Decompress LZMA, cacheflush, mprotect, and jump into the real program.

We also checked the USB kernel-module archive of the same firmware (g_android_accessory.ko, g_android_autobox.ko, g_iphone.ko and friends: Linux 3.14.52, ARMv7, GPL). None contains hwaes. The decryption driver presumably lives inside the kernel image.

Where we deliberately stopped

Going further means recovering device-bound cryptographic material from the manufacturer's hardware. We chose not to. That's a line we draw on purpose, not a limitation we lament, even though it's "our own" dongle and even though a plausible next step existed (unpacking the kernel image). The repository's contribution rules say the same: no code that tries to decrypt, decompile, or extract key material from the firmware binaries, and no manufacturer binaries in the repo. Static analysis of plain-text scripts and unencrypted binaries is welcome. The analysis was purely static: we never ran the binary, and we never tried guessed commands against the dongle's API (an unknown command could reboot it or worse).

10. What the plain-text scripts told us

Everything legible was enough to map the system. The key script is phone_link_deamon.sh <CarPlay|AndroidAuto|HiCar|ICCOA> <start|stop>. For Android Auto it:

copies the binaries to RAM (/tmp/bin, /tmp/lib; the flash is read-only),
starts hfpd (Bluetooth hands-free) in the background and ARMAndroidAuto in the foreground,
and runs inside a supervisor loop: while a lock file exists, every second it relaunches whatever died.

That implies a much lighter "soft switch" than a full reboot: kill the two link processes without removing the lock file and the supervisor restarts the link in 1 to 2 seconds. The candidate sequence, run inside the dongle, would look like:

hcitool dc <phone MAC>          # drop the Bluetooth link of the active phone
killall hfpd ARMAndroidAuto     # the supervisor relaunches them within ~1 s

This is not implemented and has never been run. There is no shell on the dongle in car mode (adbd is killed when the AOA handshake happens), and we don't know whether the car session survives, nor which phone ARMAndroidAuto picks after relaunch. It's documented as future work that would require a modified firmware, with the open questions written down.

11. A detour that didn't pan out: internet for passengers

We also tried to share the phone's mobile data with everyone in the car. Android lets a normal app neither switch the hotspot on nor set its name and password (that needs privileged permissions that only the shell user from adb has). We built a card with name, password, QR code and a notification button, realized the configuration was still manual, so it added nothing, and removed it. The open paths (Shizuku, a 4G router, or a firmware that makes the dongle a bridge) are written down so nobody repeats the experiment.

12. Shipping it

Stack: Kotlin, Jetpack Compose (Material 3) for the phone UI, AndroidX Car App Library 1.4, minSdk 26; roughly 3,000 lines of Kotlin in 16 files.
HTTP in clear text only to the dongle's own address (it doesn't support HTTPS); the network security config allows it for that single IP.
Never auto-update the dongle's firmware from the app. The downside (a bricked dongle) is much bigger than the upside.
CI: every push to main builds the app and publishes a GitHub release (v0.1.<run number>) with the APK, and an Android App Bundle for Google Play. Releases are signed with a release key kept in a self-hosted secrets manager; CI authenticates to it with GitHub OIDC, with no stored secret (I wrote about that setup in Stop Storing Secrets in GitHub Actions). One lesson: the first releases were signed with the debug key, whose signature changes between runs, so Android refuses to update in place. You had to uninstall first.

13. What the app does today

Multi-phone: any number of phones can share the dongle, with ACTIVE / AVAILABLE / SAVED states.
One-tap switching from the app, from the Android Auto screen, from a quick-settings tile or from an icon shortcut.
Request protocol with accept/reject and retry.
Visible countdown during the ~30 s reboot, with phases and a progress bar in the app, the car screen and notifications.
Dongle settings built dynamically from the keys your firmware reports, using the exact labels and help texts of the manufacturer's own interface (names, connection, audio and calls, video, WiFi channel, language). Firmwares differ, so the app only shows what the firmware exposes.
Live monitor with donut charts and an overheating warning.
Phone memory monitor.
Tools: custom logo, car data, log download, restore.
A guide for adding a new phone, with automatic detection when it registers.
Car emulation without a car through the DHU in direct AOA mode.

Known limits (all in docs/LIMITATIONS.md): switching reboots the dongle, "available" only works for phones that run the app with Bluetooth and permissions, BLE range is roughly 10 to 30 m (plenty inside a car), each firmware update can hide or rename settings, and distribution is by APK for now.

14. Try it, break it, contribute

If you own a Carlinkit/AutoKit dongle:

Try the app. Download the latest APK from the releases page and install it on every phone that shares the dongle.
Tell us your model and firmware if it differs from ours (CPC200-2Air, firmware 2025.12.29). Setting keys vary between firmwares, and the app is designed to adapt to that.
Contribute. Bug fixes with reproduction steps, support for other dongle models, UI improvements, new dongle settings (always with the label and help text exactly as the dongle's own interface shows them, and a citation), translations and screenshots. Read CONTRIBUTING.md first, and the project log docs/CONTEXT.md so we don't walk the same dead ends twice.

The docs are currently written in Spanish (the research notes, the architecture and the full project log). Translations are a very welcome kind of PR.

Everything is in the repo:

Project log, dead ends included: docs/CONTEXT.md
Architecture: docs/ARCHITECTURE.md
Dongle web API: docs/DONGLE_API.md
How the dongle works inside: docs/RESEARCH.md, docs/SOFT_SWITCH.md, docs/SERVER_CGI.md
Limitations: docs/LIMITATIONS.md

Repository: github.com/muvatec/switch-phone-aa, MIT license. Issues and PRs are welcome.

Self-Hosting Infisical on Coolify: A Production-Style Guide with Compose, TLS, Machine Identities and GitHub OIDC

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:22:53 +0000

Infisical is an open-source secrets manager. Coolify is a self-hosted PaaS that runs Docker workloads behind a Traefik reverse proxy with automatic TLS. This guide puts them together: a production-style Infisical on Coolify, with the real Compose file I ran, the Coolify-specific tricks that make it painless, the machine-identity options (and which one to pick), and the failure modes I hit.

Conventions. Every hostname, ID and secret below is a placeholder. secrets.example.com is your domain. Nothing here came from a real instance. Menu names reflect the Infisical and Coolify versions I used; both UIs change often, so verify against yours.

What you'll build

flowchart LR
    C["Client / CI"] -- HTTPS --> T["Traefik (Coolify proxy, Let's Encrypt)"]
    T --> I["infisical backend :8080 (API + UI)"]
    I --> P[("PostgreSQL: encrypted secrets, state")]
    I --> R[("Redis: queues, cache, rate limiting")]

Three containers on one Docker network. Only the Infisical container is routed through the proxy; Postgres and Redis publish no ports.

Prerequisites

A Coolify instance with at least one connected server. 2 GB of RAM is a comfortable floor for Infisical + Postgres + Redis. (I'll show a lean profile below that runs in much less, with limits you can tune.)
A DNS A record, e.g. secrets.example.com, pointing at that server before you deploy, so Let's Encrypt can issue the certificate.
openssl locally if you generate secrets yourself.
A password manager or offline vault for one particular key (next section).

1. Understand the three secrets (and the one you must not lose)

Variable	What it does	If you lose or change it
`ENCRYPTION_KEY`	Encrypts the instance's root key material. The documented way to generate it is `openssl rand -hex 16` (32 hex characters)	Every secret in the database becomes unreadable. A database backup alone doesn't help
`AUTH_SECRET`	Signs JWTs / sessions (`openssl rand -base64 32`)	Sessions break; users must sign in again
`POSTGRES_PASSWORD`	Database password (`openssl rand -hex 24`)	You can't connect to the database

Back up ENCRYPTION_KEY outside the server on day one. Also remember: anything printed in a chat, a ticket or a shared terminal should be treated as exposed. If it happens to a signing key or an encryption key, rotate it.

2. The Compose file

Two ways to provide those values: type them into Coolify's Environment Variables tab, or let Coolify generate them with magic variables. I'll show the second, because it removes copy-paste of secrets entirely, then the manual variant.

Option A: Coolify magic variables (what I deployed)

Coolify generates values for env names that follow a pattern (documented in its Docker Compose knowledge base):

Pattern	Generates
`SERVICE_URL_<ID>` / `SERVICE_FQDN_<ID>`	The service URL (with scheme) / the domain only
`SERVICE_USER_<ID>`	Random 16-character alphanumeric username
`SERVICE_PASSWORD_<ID>`	32-character password, no symbols (`..._64_<ID>` for 64)
`SERVICE_REALBASE64_<ID>` / `_64_` / `_128_`	Base64 of 32 / 64 / 128 random bytes
`SERVICE_HEX_32_<ID>`	32-character hex string

Reusing the same full name gives every service the same stored value. A numeric suffix on SERVICE_URL_* (for example SERVICE_URL_BACKEND_8080) tells Coolify which container port to route the generated domain to.

services:
  backend:
    image: 'infisical/infisical:v0.154.6'     # pin a release; see "Upgrades"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      - SERVICE_URL_BACKEND_8080                # Coolify: generate a domain and route to port 8080
      - NODE_ENV=production
      - 'SITE_URL=${SITE_URL:-${SERVICE_URL_BACKEND}}'
      - 'ENCRYPTION_KEY=${SERVICE_PASSWORD_ENCRYPTIONKEY}'
      - 'AUTH_SECRET=${SERVICE_REALBASE64_64_AUTHSECRET}'
      - 'DB_CONNECTION_URI=postgresql://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@db:5432/${POSTGRES_DB:-infisical}'
      - 'REDIS_URL=redis://redis:6379'
      - TELEMETRY_ENABLED=false
      - NODE_OPTIONS=--max-old-space-size=1024
    mem_limit: 1536m
    restart: unless-stopped

  redis:
    image: 'redis:7'
    command: redis-server --maxmemory 64mb --maxmemory-policy noeviction --save 300 10
    volumes:
      - 'redis-data:/data'
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 5s
      retries: 10
    mem_limit: 96m
    restart: unless-stopped

  db:
    image: 'postgres:14-alpine'
    command: postgres -c shared_buffers=64MB -c max_connections=30 -c work_mem=4MB -c effective_cache_size=256MB -c maintenance_work_mem=32MB
    environment:
      - 'POSTGRES_USER=${SERVICE_USER_POSTGRES}'
      - 'POSTGRES_PASSWORD=${SERVICE_PASSWORD_POSTGRES}'
      - 'POSTGRES_DB=${POSTGRES_DB:-infisical}'
    volumes:
      - 'pg-data:/var/lib/postgresql/data'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}']
      interval: 5s
      timeout: 5s
      retries: 10
    mem_limit: 256m
    restart: unless-stopped

volumes:
  redis-data:
  pg-data:

Details worth understanding rather than copying:

$${POSTGRES_USER} (double dollar) in the Postgres health check makes Compose pass a literal ${POSTGRES_USER} for the container's shell to expand, instead of interpolating it at parse time.
--maxmemory-policy noeviction on Redis matters. Infisical uses Redis for job queues; an eviction policy that drops keys under memory pressure can silently lose queued work. noeviction makes Redis return errors instead, which you can see and alert on. --save 300 10 snapshots to disk so queues survive a restart.
The memory limits and Postgres tuning are a *lean profile* for small VPSes: ~1.5 GB for the app (with Node's heap capped at 1 GB), ~96 MB for Redis and ~256 MB for Postgres with max_connections=30. Raise them as your usage grows. If you run out of memory, you want a container restart you can see in the logs, not the host's OOM killer picking a victim.
Keep depends_on with service_healthy: Infisical runs database migrations at startup, so starting it before Postgres is ready produces confusing first-boot errors.
Postgres major version: don't bump postgres:14-alpine to 16 on an existing volume; a major upgrade needs a dump/restore.
Telemetry: TELEMETRY_ENABLED=false turns off usage telemetry.

Option B: manual variables

If you don't want magic variables (or you're not on Coolify), set these as secrets in the Environment Variables tab and replace the ${SERVICE_*} references:

Variable	Value
`ENCRYPTION_KEY`	`openssl rand -hex 16`
`AUTH_SECRET`	`openssl rand -base64 32`
`POSTGRES_PASSWORD`	`openssl rand -hex 24`
`SITE_URL`	`https://secrets.example.com` (no trailing slash)

Mark them as secrets so Coolify hides them in the UI and in logs.

One observation from my own deployment: Coolify's SERVICE_PASSWORD_* (32 alphanumeric characters) was accepted by Infisical as ENCRYPTION_KEY. The documented generation is still openssl rand -hex 16; if you hit a key-format error at boot, switch to that.

3. Create the resource in Coolify

Projects → New project (e.g. platform), pick the production environment, + New resource.
Choose Docker Compose Empty and paste the file. (If your Coolify ships an Infisical one-click template, you can use it: the variables are the same.)
Open the service's Domains and set it to https://secrets.example.com. With the SERVICE_URL_BACKEND_8080 line, Coolify already knows the container port; in a manual setup, add :8080 to the domain so the proxy routes to the right port. Leave db and redis without a domain.
Make sure the server's proxy (Traefik) is running with the Let's Encrypt resolver. If you changed proxy settings, restart the proxy.
Deploy.

SITE_URL must equal the public HTTPS URL users hit. If you change the domain later, change SITE_URL too.

4. Verify

curl -s https://secrets.example.com/api/status

A healthy instance answers with a small JSON document ("message": "Ok", plus flags such as whether email is configured). If you get a 502/504:

Check	Why
Domain routes to port 8080	The most common mistake
`db` is healthy	The backend waits for it, and fails to migrate otherwise
Backend logs show migrations finishing	First boot runs many of them; give it a minute
The proxy is up and the certificate was issued	Look at the Traefik/proxy logs for ACME errors; DNS must already resolve

I didn't add a container health check to the backend. If you want one, test that wget or curl exists in the image before relying on it, or monitor /api/status from outside.

5. First login, then lock the door

Open the URL and sign up. The first account becomes the instance admin, so do this before announcing the URL to anybody.
Open the Server Console (top-right) and disable open sign-ups. Otherwise anyone who finds a public instance can register.
Enable MFA on the admin account.
(Optional) Configure SMTP (SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_ADDRESS, plus the TLS options your provider needs) for invites and password resets. Until you do, the UI shows an SMTP has not been configured for this instance banner and email flows don't work.

6. Projects and environments

Create a project (e.g. my-app). Infisical creates dev, staging and prod environments by default. Use the slug shown in the project settings (not the display name) in CI and CLI configurations; they're different things and mixing them up gives confusing "not found" errors.

7. Machine identities: don't use a human account for automation

A machine identity is the non-human principal for apps and CI. The flow in the UI:

Organization → Access Control → Machine Identities → Create Organization Machine Identity.
Give it a name and an organization role. Admin and Member are broad; No Access is the right choice for a CI identity that only needs to read secrets from one project.
Open it, and under Authentication add an auth method. The menu offers: Token Auth, Universal Auth, Kubernetes, GCP, Alibaba Cloud, AWS, Azure, OCI, OIDC, LDAP, TLS Certificate and JWT. Note: a newly created identity comes with Universal Auth already configured. If you plan to use something else, remove Universal Auth so there's only one way in.
Add the identity to the project (identity page → Projects → +) with the narrowest role that works. Project roles include Admin, Developer, Viewer and No Access; for "read the prod secrets", Viewer is enough.

Option 1: Universal Auth (client ID and client secret)

The simple one. You get a client ID and client secret. A few defaults are worth changing:

Setting	Default	Recommendation
Access token TTL / Max TTL	2,592,000 s (30 days)	Hours or less for CI
Access token max uses	0 (unlimited)	Set a bound if the job reads a known number of times
Client secret TTL	0 (never expires)	Set a TTL, and enable the expiry alert so your team is warned
Client secret max uses	0 (unlimited)	Low, if the secret is for a single pipeline
Trusted IPs	0.0.0.0/0	Restrict to your CI/server ranges; per Infisical's docs this restriction is a paid feature
Lockout	On (threshold 3)	Leave it on

The documentation itself shows two different default TTLs for the access token (30 days in the configuration section, 7200 s in a login example), so check the effective values on your own identity.

Use it from the CLI:

# domain flag for self-hosted instances (older CLI versions may expect the API URL with /api)
export INFISICAL_TOKEN=$(infisical login \
  --method=universal-auth \
  --client-id="$INFISICAL_CLIENT_ID" \
  --client-secret="$INFISICAL_CLIENT_SECRET" \
  --domain=https://secrets.example.com \
  --silent --plain)

# inject secrets as environment variables of one process; nothing is written to disk
infisical run --projectId="<project-id>" --env=prod --domain=https://secrets.example.com -- ./start-service

(Confirm flags with infisical login --help for your CLI version.) And from GitHub Actions. Note the method value for the action is universal, not universal-auth (that spelling is the CLI's):

- uses: Infisical/secrets-action@v1.0.9     # pin the version or, better, a commit SHA
  with:
    method: universal
    client-id: ${{ secrets.INFISICAL_CLIENT_ID }}
    client-secret: ${{ secrets.INFISICAL_CLIENT_SECRET }}
    domain: https://secrets.example.com
    project-slug: my-app
    env-slug: prod

Only the client ID and client secret live in GitHub; the rest is fetched at runtime and exported as environment variables. Rotating a secret in Infisical needs no repo change.

Option 2 (recommended for GitHub Actions): OIDC, no stored secret

Universal Auth still leaves a long-lived client secret in GitHub. With OIDC Auth, the workflow presents a short-lived token that GitHub signs, and Infisical checks its claims. Nothing to rotate, nothing to leak.

In the identity, add OIDC Auth:

Field	Value
OIDC Discovery URL	`https://token.actions.githubusercontent.com`
Issuer	`https://token.actions.githubusercontent.com`
Subject	pin the owner (and ideally the branch): `repo:<OWNER>/*:ref:refs/heads/main` (see the note below on GitHub's newer subject format)
Audiences	the action's default is `https://github.com/<OWNER>`; whatever you set must match exactly what the workflow requests

permissions:
  id-token: write      # required to request the OIDC token
  contents: read

steps:
  - uses: Infisical/secrets-action@v1.0.9
    with:
      method: oidc
      identity-id: ${{ vars.INFISICAL_IDENTITY_ID }}   # an identifier, not a secret
      domain: ${{ vars.INFISICAL_URL }}
      project-slug: my-app
      env-slug: prod

Two things bite people:

Never use * or repo:* as the Subject. The token issuer is shared by all of GitHub, so the Subject is the only thing separating your repos from everyone else's. Wildcards in Infisical's Subject also match : and /, so always put a / or @ right after the owner.
GitHub changed the default sub format for new, renamed and transferred repositories (and for organizations that opt in) to include immutable IDs: repo:<OWNER>@<OWNER_ID>/<REPO>@<REPO_ID>:ref:.... A policy written for the old name-only format stops matching. Print the real claims from a test job and compare them character by character before debugging anything else.

I covered the threat model in depth in Stop Storing Secrets in GitHub Actions. A side note for private repositories on GitHub's Free plan: organization variables are only available to public repositories, so put INFISICAL_IDENTITY_ID and INFISICAL_URL in repository variables.

8. Operations

Backups. Two independent things, stored separately:

# logical backup of the database (adjust the container name; run on the Docker host)
docker exec <db-container> pg_dump -U <user> -d infisical -Fc > infisical-$(date +%F).dump

Plus ENCRYPTION_KEY in an offline vault. If your Postgres is a Coolify-managed database resource, you can use Coolify's scheduled backups to S3-compatible storage instead. Either way, test a restore into a scratch instance with the same ENCRYPTION_KEY.

Upgrades. Pin the image tag, read the release notes, take a database snapshot, bump the tag, redeploy, and watch the migration logs. Never ride latest in production: Infisical migrates the schema on boot, so an unplanned image pull can change your database.

Rotation. Schedule rotation of client secrets (or move to OIDC and stop having them). Revoke any Coolify API tokens you created during setup once you're done with them.

Audit. The audit logs show which identity read which secret. Review them; a log nobody reads is decoration.

Network exposure. Serve TLS only. If the instance is for internal use, restrict the proxy to a VPN or a tunnel instead of the open internet, and keep sign-ups disabled either way.

Monitoring. Alert on /api/status, on container restarts, on Redis errors (remember noeviction), and on disk usage of the Postgres volume.

Common pitfalls

Symptom	Likely cause
502 right after deploy	Wrong container port in the domain (needs `8080`), or Postgres still starting
Certificate not issued	DNS not pointing at the server yet, or the proxy isn't running/was not restarted after changes
Boot error about `ENCRYPTION_KEY`	Wrong length or format; regenerate with `openssl rand -hex 16` (on a fresh database only)
Everyone signed out after a redeploy	`AUTH_SECRET` changed between deploys (with magic variables, don't recreate the variable)
Secrets unreadable after a restore	Restored the database with a different `ENCRYPTION_KEY`
No invite or reset emails	SMTP isn't configured
CI says the project isn't found	You used the project name instead of its slug
`403` on OIDC login	Subject/audience mismatch, or the identity wasn't added to the project
Backend killed repeatedly	Memory limit too low for your usage; raise `mem_limit` and the Node heap together

A note on automating this with AI agents

If you let an agent drive the setup, treat it like any other automation account: give it a scoped identity, never paste keystores or passwords into the conversation, pass secrets through files or stdin rather than printing them, and rotate anything that did end up in a transcript. The convenience is real, and so is the blast radius.

Checklist

[ ] DNS resolves, proxy running, certificate issued
[ ] Image tags pinned; Postgres major version consistent with the volume
[ ] ENCRYPTION_KEY backed up offline; database backup tested
[ ] First admin created, open sign-ups disabled, MFA on
[ ] SMTP configured (if you need invites)
[ ] CI uses OIDC (or Universal Auth with short TTLs and limited uses)
[ ] Identities have the narrowest role, one auth method each
[ ] Alerts on /api/status and container restarts

SSR and Hydration in a Small Framework: What Works, What Doesn't, and What's Next (Inside AngeLite, Part 7)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:10:34 +0000

Server-side rendering is where small frameworks usually get stuck: the runtime is full of document.createElement calls, so it can't run on a server without pretending to be a browser. AngeLite has an unusual head start, and an honest incomplete spot. This final post covers both.

What exists today: render in jsdom, no second implementation

tools/ssr.mjs renders your component in Node inside jsdom. That was a deliberate choice: there is no second renderer to keep in sync, so the server output is exactly what the browser would build, with the same URL sanitising and the same escaping.

It exports three functions:

renderToString(Comp, options): the markup of the mount element (default #app).
renderPage(Comp, { shell, url, state }): a page shell with  and  markers filled in.
serializeState(state): JSON that is safe inside a <script> tag. It escapes <, >, & and the Unicode line separators, which is the classic place for injection bugs in SSR.

Because jsdom provides the globals during a render, renders are queued: two requests at once don't step on each other. Components that load data asynchronously can be awaited with a ready option, and a setup hook runs before mount (for example to call provideRouter(routes, { mode: 'history' }) so the router reads the request URL).

Server and client, concretely

// server (Node)
import { renderPage, serializeState } from '@duvanjamid/angelite/tools/ssr.mjs';

const page = await renderPage(App, { shell, url: req.url, state });
// shell contains <!--app--> and <!--state-->; state is embedded via serializeState

// client
import { hydrate } from '@duvanjamid/angelite/hydrate';
hydrate(App, document.getElementById('app'));

hydrate() is a 15-line module (about 0.1 KB gzip). Read window.__STATE__ to start from the data the server used.

The honest incomplete part

hydrate() replaces the server HTML with the live app in the same task, so there's no flicker, but it does not adopt the existing nodes: the client renders again, and there is no streaming either. What you gain is visible content before the JavaScript arrives, and SEO. What you don't gain is the work saved by true hydration. The ROADMAP lists "hydration that adopts the server's existing nodes and streaming rendering" as the top Next item, and the comparison table is explicit that this is smaller and less complete than Angular's incremental hydration or what React and Vue offer.

Where the design could go: the blueprint is data

Recall from post 2 that a template compiles once into a blueprint: an HTML fragment plus a list of instructions ("this text node depends on this expression", "this element has this event"). The ahead-of-time (AOT) compiler already serialises that list per node position.

That's an unusually good base for the next version of SSR, and it's a direction, not a shipped feature:

On the server: evaluate the instructions without a DOM and emit text, removing the jsdom dependency and its serialised queue.
On the client: walk the existing DOM with the same instructions (numbering by position already exists) to adopt the server nodes instead of rendering again.

Few frameworks have that starting point, because their template output is code that creates elements rather than data describing them. The project's gap analysis flags it as the thing to exploit "before adding more features".

flowchart LR
    T[Template] --> C["Compiler (AOT)"]
    C --> B["Blueprint = HTML + instruction list (data)"]
    B --> K["Client today: clone + apply instructions"]
    B -. "today" .-> J["Server today: render in jsdom"]
    B -. "future" .-> S["Server: evaluate instructions, no DOM"]
    B -. "future" .-> H["Client: adopt existing nodes"]

Why SSR on a small framework is hard: global state

The gap analysis names the two design limits that SSR runs into:

Module-level global state. The pipe registry, the inject() service map, the router, the set of delegated events and the router hook are singletons. You can't render on a server without mixing requests unless you serialise renders (hence the queue), and you can't run two isolated apps on one page. The direction is a createApp() object that owns registries, injector and router.
Coupling to the global DOM. The runtime calls document directly, which rules out alternative renderers. The direction is to abstract the few DOM operations (create template, insert, move, remove).

Neither is a bug; both are the price of a core that's about 6 KB. They're also the clearest "next step" list for anyone who wants to contribute.

Tooling around it

Combine it with the Vite plugin (tools/vite.mjs, which reloads on template edits) and angelite-check (file:1: message output that reuses the AOT template checks) for a fast dev loop.

A caution that applies everywhere

SSR multiplies the importance of the security model from post 3. Three rules hold:

Never include user input in a template that gets compiled; precompile with the AOT tool.
Escape-by-default text and URL filtering apply on the server render too, so server HTML and client DOM agree.
Use serializeState rather than hand-rolled JSON.stringify inside a <script> tag.

Series wrap-up

Across seven posts the argument has been the same:

Small is a budget, not a goal. It stays small because CI refuses to let it grow silently (post 4), and because optional really means optional (post 5).
Fine-grained and boring. Signals, microtask batching and cloned blueprints do the work; there's no virtual DOM and no Zone.js (post 2).
Secure by default means tested against attacks. The first test run made the framework look worst of its peers, and that was the point (post 3).
Honest comparisons build trust. Publish the method, the noise, and the losses (post 6).
Write the debt down. Global state, DOM coupling and re-rendering hydration are in the open (this post).

If you want to try it or contribute, start at duvanjamid/angelite and the documentation. Issues, benchmark corrections and PRs are all welcome, and I'd love to hear from anyone who tries precompiled mode on a real app.

Benchmarking Honestly: Where My Framework Wins and Where It Loses (Inside AngeLite, Part 6)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:10:23 +0000

Framework benchmark posts have a credibility problem: the author's framework wins. So this post is built the other way around. It describes how AngeLite is benchmarked, what the numbers show, and, more importantly, where the project's own comparison says it loses.

Method first

The benchmark is a table app: table > tbody > tr with 3 cells, one click handler per row, and the selected row marked with a class. The data comes from the same deterministic generator in every implementation. Each framework is written idiomatically:

React 19 with memo + useCallback
Preact (core + hooks only, shouldComponentUpdate on the row)
Vue 3 with a compiled template and shallowRef
Angular 20 with signals, OnPush, @for ... track, and zoneless change detection
AngeLite with signals and @for ... track, in two modes: compiled in the browser, and precompiled

What's measured: performance.now() from triggering an operation until a DOM condition holds (for example "there are 1,000 rows") and style + layout has been forced. It does not include painting. Two warm-up iterations are discarded per operation, and rounds alternate framework order. Bundles are built with each framework's usual tool (esbuild, Vite, ng build).

Run on a shared container with no CPU throttling, so absolute numbers aren't comparable; positions within a run are. The project uses a "within 10% is a tie" rule because differences of a few milliseconds are noise.

cd benchmarks
npm install
npm run build   # builds the 5 apps
npm run bench   # runs the suite -> benchmarks/results.json

What it shows

	Precompiled AngeLite	Best of the others
App size (gzip)	6.1 KB (smallest)	Preact 6.2 KB
Startup	23.1 ms	Preact 21.3 ms (technical tie: overlapping interquartile ranges)
Memory, 10,000 rows	6.6 MB	Angular 11.8 MB
12 measurements in all	lowest median in 7; within 10% in 4; behind in `remove` (Preact, +16% in that run)	n/a

Overall score, as the geometric mean of time relative to the best per operation: 1.03x for precompiled AngeLite; React at 1.55x. Where AngeLite wins clearly: size, memory and list speed. And in "no build" mode it's the only one with a small option: about 10 KB gzip, versus Vue's 63.7 KB with its compiler, and with no eval.

Repeat-run honesty: swap and remove vary between runs. Two dedicated repetitions gave 4.70 ms vs Preact's 4.90, and another 4.75 vs 4.70. The project's own reading is "a tie with Preact and Angular", not a win.

What it doesn't measure

The page says it plainly: SSR, hydration, ecosystem, DevTools, accessibility, mobile performance and long-term memory behaviour aren't covered. "Angular and React offer much more than AngeLite; this compares only the rendering core."

The comparison: where it loses

Alongside the benchmark there's a feature-by-feature comparison table with a source for each cell:

V: verified by running the code or reading the installed package (React 19.3.1, Preact 10.29.8, Vue 3.5.44, Angular 20.3).
D: from official documentation.
G: general knowledge that wasn't checked, flagged for review before quoting.

Of the table's rows, 16 are V, 2 are D and 19 are G, and the security rows are almost all V. Scoring features on a simple scale, AngeLite lands at 19.5 against 24.5 (Preact), 27 (Vue), 28.5 (React) and 33 (Angular). The document is explicit: "It is not a ranking, but the gap is real."

Where it loses is everything around the core:

Missing or immature	Who has it
Compile-time optimisations (hoisted static subtrees, folded constants, per-node flags)	Vue, React Compiler, Angular AOT
Concurrent rendering and transitions	React (and the recommendation here is not to copy it: the complexity is enormous for a lightweight framework)
Incremental hydration and adopting server nodes	React, Vue, Angular
Editor language service / template autocompletion	Angular, Vue
Browser DevTools extension, async validators, `FormBuilder`	Angular and others
Years of security review and a community	All of them
Types and template checking	Today the `.d.ts` is checked, but templates are checked for elements, pipes and names, not types

Limits of its own design (verified in the code)

One effect per view, not per binding. In a component with hundreds of bindings and a hot signal this can cost; Vue and Solid are finer.
Immutable lists. Identity is compared; mutate-in-place-and-reassign-the-same-array doesn't update.
Measurement noise. Shared container, no painting; differences under 10% aren't conclusive.

Why publish this?

Three reasons:

It makes the wins believable. If a document says "we lose here, and here, and here", the claim "we're smallest" gets read as measured, not marketed.
It prevents the wrong adoption. The best outcome of an honest comparison is someone deciding React or Angular is the right call for them.
It's a roadmap. The gap table is the backlog, ordered by value (see the project's ROADMAP: hydration that adopts existing nodes and streaming rendering, route and list animations, FormBuilder and async validators, editor autocompletion, i18n message extraction, template type-checking).

Reproduce it, and argue

Everything is in the repo: the apps, the harness, the raw JSON results and the security probe (npm run probe:security in benchmarks/). If a number is wrong, or an idiomatic implementation of your favourite framework is unfair, a PR is more useful than an argument.

Takeaways

State the method, the noise and the non-goals before the table.
Use a tie rule (here, 10%) and say when a result flips between runs.
Label every claim by how it was verified.
Put the losses in the same document as the wins.

Next: the one feature that stresses all of this at once, server-side rendering, and why "the blueprint is data" makes it a natural next step.

Optional by Design: What Every Core Feature Costs in Bytes (Inside AngeLite, Part 5)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:10:12 +0000

"Optional modules" is easy to say and hard to make true. Most libraries that claim it still end up with a core that drags everything along: a registry that imports the router, a compiler that knows about animations, a component model that assumes forms. This post is about how AngeLite keeps "you only pay for what you import" literally true, and what each piece of the core costs in bytes.

The registry trick: `ops`

A template compiles to a list of instructions (see post 2). Some instructions are core: text bindings, property bindings, events. Others are specialised: portals, @defer, template refs, animations. If the runtime's main loop knew about all of them, every app would ship all of them.

Instead, the runtime exposes a registry:

/**
 * Registry for optional template instructions (portals, @defer, template refs...).
 * A module adds its handler with `ops.portal = (op, node, view, scope, ctx) => {...}`
 * when imported, so apps that never use it do not ship it.
 */
export const ops = {};

A module like portal.js is 16 lines. Importing it registers its handler; not importing it means the handler never exists in your bundle. The runtime's dispatch for unknown ops is the only core cost (about 55 B), and it's what lets portals, @defer, refs and animations weigh nothing in an app that doesn't use them.

flowchart LR
    T["Template instructions"] --> R["runtime.js (core)"]
    R -- "ops.portal?" --> P["portal.js (only if imported)"]
    R -- "ops.defer?" --> D["defer.js (only if imported)"]
    R -- "ops.ref?" --> F["refs.js (only if imported)"]
    R -- "detach hook" --> A["animate.js (only if imported)"]

The module map

Import	For
`@duvanjamid/angelite`	signals, templates (`@if`, `@for`, `@defer`), components, DI, pipes, router
`.../runtime`	the runtime only, for precompiled templates
`.../forms`	reactive forms
`.../http`	HTTP client, interceptors and `resource()`
`.../i18n`	languages, plurals and formats
`.../ui`	library of 33 accessible components
`.../testing`	testing utilities
`.../devtools`	component and signal inspector
`.../hydrate`	hydration of server-rendered HTML
`.../tools/aot.mjs`, `ssr.mjs`, `vite.mjs`	build-time compiler, server rendering, Vite plugin

Each add-on is measured and budgeted (minified, gzip): forms about 0.9 KB, HTTP 1.3 KB, i18n 0.7 KB, DevTools 0.9 KB, hydrate 0.1 KB, testing 0.7 KB. The UI library is marked pure per component, so a bundler keeps only the ones you import: an app that imports a single Button is about 7 KB gzip smaller than one that imports the whole library (the full UI bundle is about 11.8 KB gzip).

What the core actually pays for

The precompiled table app went from 5,968 B to 6,223 B gzip across two waves of features that added a router with guards and lazy loading, DI with scopes, error boundaries, portals, named slots, @defer, refs, forms, HTTP, i18n, animations, SSR, DevTools and testing utilities. That's +255 B, about 4%. Where those bytes live:

Piece	Approx.	Why it's in the core
Component context + `reportError` (error boundaries)	~110 B	errors, scoped DI and slots share it
The `ops` registry and its dispatch	~55 B	lets portals, `@defer`, refs, animations weigh nothing if unused
Named slots	~40 B	changes how content is projected
`detach` (animated exit) and `host.$c` (DevTools)	~28 B	minimal hook for two optional modules

Everything else doesn't show up in that app at all.

Error boundaries, cheaply

An example of a feature small enough for the core. Errors go to the nearest component (or the one wrapping the projected content) that defines ngOnError(error, where):

export function reportError(e, what, ctx) {
  for (; ctx; ctx = ctx.up) {
    const target = ctx.guard || ctx.self;
    if (target && target.ngOnError) {
      try { target.ngOnError(e, what); } catch (err) { logError(err, 'ngOnError'); }
      return;
    }
  }
  logError(e, what);
}

It walks the component context chain and falls back to console.error. The same context carries scoped DI providers and slots, which is why the cost is shared. (An honest limit from the docs: boundaries don't catch errors thrown in the constructor or ngOnInit.)

Dev warnings from the outside

enableDevWarnings() doesn't live in the core: it installs warnings by wrapping internals (A.prop, A.state, ops) from the outside. The production build contains none of those bytes. This is the same principle as the ops registry: if something is only for development, it must be impossible to ship by accident.

Lazy loading, two different things

@defer delays rendering of a block until a trigger fires (on idle, on viewport, on interaction, on hover, on timer(2s), on immediate, or when expr), and you can combine triggers with ;. It does not split code. To split the code of a whole screen into another file, use load: () => import('./screen.js') in a route. Conflating the two is a common source of "why didn't my bundle shrink?".

The architectural debt, written down

The project's gap analysis lists real weaknesses of the current design, which is a good test of whether "optional modules" are being honest:

Module-level global state (pipe registry, DI map, router, delegated events). You can't run two isolated apps on one page or render on a server without care. Direction: a createApp() object holding registries, injector and router.
Coupling to the global DOM. The runtime calls document directly, which constrains other renderers. Direction: abstract the few DOM operations.
Scope by prototype chain and text keys. Fast and compact, but not statically analysable (no template type-checking), and $event / $index can collide with user fields.
Events delegated on document. Great for memory, but doesn't work inside Shadow DOM or iframes and event.currentTarget isn't the element. Direction: delegate on each app's root.
Properties added to elements ($s, $click) can collide with other libraries.
No stable-API contract or full types for templates yet. That slows adoption more than any benchmark.

Takeaways

A tiny registry (ops) is what turns "optional" from marketing into bytes.
Put development-only code outside the core so it can't ship by accident.
Publish the cost of every core feature, and publish the known design debt next to it.

Next: how to benchmark and compare honestly, including where AngeLite loses.

How a CI Performance Budget Keeps a 6 KB Framework From Growing (Inside AngeLite, Part 4)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:10:00 +0000

Every framework starts fast and gets slower. Features accumulate, each justified on its own, and one day the "lightweight" library isn't. AngeLite's defence is a rule: no feature lands if it makes the core slower, bigger or hungrier for memory, and the rule is enforced by CI, not by good intentions.

This post explains the four layers of that enforcement and why they're arranged from cheapest and exact to expensive and noisy.

The problem with measuring time in CI

The obvious approach is "run the benchmark on every PR and fail if it got slower". It doesn't work. On a shared CI runner, time varies 10-20% from run to run, so a threshold tight enough to catch regressions is loose enough to flake constantly.

What is exact: how much work the code does (DOM calls, effect runs) and how many bytes it ships. So the budget leans on exact measurements first and uses noisy ones only as a backstop.

The four layers

Layer	What it measures	Where it runs	Noise
1. Size	gzip bytes of every bundle, and of what a user really downloads (the table app built with esbuild)	CI, every PR	none
2. Work	DOM calls and effect runs per scenario (1,000 rows) against a stored budget	CI (`npm test`), every PR	none: deterministic
3. Relative time	AngeLite vs Preact in the same run; ratio compared with a baseline	on demand, weekly, and PRs touching the core; doesn't block	medium
4. Full benchmark	five frameworks, 12 measurements, memory and startup	by hand before publishing	high

flowchart TB
    PR[Pull request] --> L1["Layer 1: bundle size (exact)"]
    PR --> L2["Layer 2: work budget (exact)"]
    L1 --> Gate{"Within budget?"}
    L2 --> Gate
    Gate -- no --> Fail["CI fails and names the figure"]
    Gate -- yes --> Merge[Mergeable]
    PR -. "touches core" .-> L3["Layer 3: relative time vs Preact (noisy, non-blocking)"]
    Release[Before publishing] --> L4["Layer 4: full 5-framework benchmark (by hand)"]

Layer 2 in detail: count the work, not the time

tests/perf-budget.test.mjs mounts the table app with every optional module loaded (portal, @defer, animations...) and counts, per scenario, calls to createElement, cloneNode, appendChild, insertBefore, remove, setAttribute, classList.toggle, textContent =, addEventListener and so on, plus Effect.run executions. It also asserts that the in-browser compiler and the precompiled template do exactly the same work. Today, for 1,000 rows:

Scenario	DOM calls	Effects
create 1,000	5,002	1,001
replace 1,000	5,004	1,001
update every 10th	100	101
select a row	1	1,000
swap 2 rows	2	1
remove a row	1	1
append 1,000	5,000	1,001
clear	4	1

If a change raises any figure, the test fails and says which one. If it's intentional, you explain it in the PR and run UPDATE_PERF=1 npm test, which rewrites the budget in the same commit, so the change is visible in review. And if a figure drops, the test says so too, so the improvement gets locked in.

This catches things time can't: a feature that adds one DOM call per row won't move a noisy millisecond number, but it changes a count of 5,002 to 6,002 and fails immediately.

Layer 3: relative time, because absolute time lies

Comparing AngeLite against Preact within the same run cancels most machine noise. A single operation fails if its ratio gets worse by more than 35%, or the geometric mean of all operations by more than 10%. It doesn't block merges because it's still statistical, but it catches what the exact layers miss, such as a new property access in a hot loop.

Design rules that keep the budget achievable

Optional module by default. A feature not every app needs goes in its own file and hooks in through the ops registry or a module imported only when used. Apps that don't import it don't pay in bytes or in time.
Don't touch the hot paths without measuring. They are instantiate, runView, ForState.reconcile and removeView. A new property on every row gets multiplied by thousands.
Pay per component or template, not per row. Compile-time work in the AOT is nearly free; per-row work isn't.
Mind object shapes. Adding fields to View, to the context or to elements changes their shape and can slow everything that touches them. Optional fields are created only when used (DI providers do this: the map is created on the first inject).
Dev warnings don't live in the core. enableDevWarnings() wraps internals from the outside; the production build includes none of it.
Every byte of the core is debated. Size budgets live in scripts and only go up in a commit that explains why.

What a budget buys you: an audit trail

Because budgets are data in the repo, the cost of every core feature is public. Before the "wave 1" feature work the precompiled table app was 5,968 bytes gzip; today it's 6,223 (+255 B, +4%). Post 5 breaks down where those bytes went.

Pending improvements, with data

The budget also acts as a to-do list, ordered by what the numbers already show:

Selecting a row runs 1,000 effects (every row reads selected() and is re-evaluated to change a class on two rows). About 1.3 ms and tied with Preact and Angular, but it's the best candidate for per-binding effects.
create1k does 5 DOM calls per row, two of which (a text write of the initial value and a classList.toggle to false) can be skipped.
remove/swap hover around a tie with Preact. A Chromium trace profile is still missing to separate noise from real cost before touching anything.

Takeaways

Measure exact things (bytes, DOM calls, effect runs) on every PR; use noisy time only as a ratio and only as a backstop.
Make budgets data in the repo, with an explicit update command, so every change is reviewed.
A performance rule you can't break by accident is worth ten you remember to follow.

Next: the module system that makes "optional" real, and what each core feature costs.

My Framework Ranked Last in the Security Tests. Here Are the 6 Holes I Fixed (Inside AngeLite, Part 3)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:09:49 +0000

When I ran an attack-payload test suite against my own framework and against Preact, Vue, React and Angular, AngeLite came out as the worst of the group. That was the useful moment: the security model had been assumed, not tested.

This post is about the six gaps that test found, how each one was closed, and what AngeLite still does not protect you from. If you build a UI framework, or use one, the threat model is probably the most reusable part.

The trust model

Templates are code you wrote. The data you render is untrusted.

AngeLite is designed so untrusted data can't become markup, script, or a dangerous URL by accident. Everything below follows from that sentence.

What was verified

The project ships benchmarks/security-probe.mjs, which runs the same hostile inputs against AngeLite, Preact, Vue and React (the Angular column comes from its documentation and the project's checks). A few of the probes and the results at the time of the audit, before and after the fixes:

Test	AngeLite (before)	AngeLite (after)	Preact	Vue	React	Angular
Escaped text by default	yes	yes	yes	yes	yes	yes
`href` with `javascript:`	let it through	`unsafe:` + warning	lets it through	lets it through	neutralises it	sanitises it
`onclick` as text	created the attribute	compile error	does not create it	creates the attribute	does not create it	forbids it
HTML in `innerHTML`	unsanitised	only with `trustHtml()`	unsanitised	unsanitised	unsanitised	sanitises
Expressions reach `window`	yes, via `$el`	no, by no path	n/a (JSX)	no	n/a (JSX)	no
Works without `eval`	yes	yes	yes	runtime-only build only	yes	AOT only
Trusted Types	no	yes (`angelite` policy)	no	one reference	no	built in

The six gaps, and the fixes

1. javascript: URLs. [href] and href="{{ }}" accepted them. Fix: an allow-list of schemes (http, https, mailto, tel, sms, ftp, relative) on href, src, action, formaction, data and xlink:href. It also ignores characters browsers drop inside a scheme (java\tscript:). Everything else becomes unsafe:<url> with a warning, and trustUrl() is the explicit escape hatch. Test: a matrix of 12 dangerous and 13 safe URLs across 7 contexts.

2. Event handler attributes from data. [attr.onclick] could create a handler. Fix: a compile-time error for [on*], [attr.on*] and on*="{{ }}", in both the browser compiler and the AOT compiler, case-insensitively.

3. Unsanitised [innerHTML]. Fix: it only renders markup wrapped in trustHtml(); any other value is inserted as text and logs a warning. Sanitise first (for example with DOMPurify), then wrap.

4. [srcdoc] and [outerHTML]. Fix: compile error.

5. Reaching window from an expression. This was the sneaky one. A template could do $el.ownerDocument.defaultView.fn(). Fix: filter by value, not by name. The global object and documents are never returned to a template, however they were reached ($el.ownerDocument, $event.view, getRootNode(), composedPath()[n], a component field). DOM methods that turn text into markup or attributes (insertAdjacentHTML, setAttribute, write) are also blocked by name. Test: 8 attack paths plus events.

6. Styles under a strict CSP. The UI package injected <style> without a nonce. Fix: constructable stylesheets (adoptedStyleSheets) need no nonce; where unavailable, it falls back to a <style> carrying the nonce from <meta name="csp-nonce">.

Also added: compile errors for bindings and interpolation on <script>, <style>, <base>, <link> and <meta>; a single Trusted Types policy named angelite for templates and trustHtml(); a SECURITY.md documenting the trust model and how to report issues; CodeQL with extended queries, Dependabot and npm audit in CI.

flowchart LR
    D[Untrusted data] --> T{"Binding type"}
    T -- "{{ }} text" --> X[Inserted as text]
    T -- "href / src / ..." --> U{"Scheme allow-list"}
    U -- "allowed" --> OK[Applied]
    U -- "other" --> UN["unsafe:... + warning"]
    T -- "[innerHTML]" --> H{"trustHtml()?"}
    H -- "yes" --> OK
    H -- "no" --> X
    T -- "on* / srcdoc" --> CE[Compile error]

Content-Security-Policy recipe

Because nothing uses eval or new Function (not the browser build, not the precompiled runtime), AngeLite works with a strict policy:

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self';
  require-trusted-types-for 'script'; trusted-types angelite

What it does NOT protect you from

This section matters more than the table above.

The expression sandbox is not a security boundary. A template can still call methods of its own component and of DOM elements it can reach. It's defence in depth. Never compile a template that includes user input, which is the same advice Vue gives about its runtime compiler. In production, precompile with tools/aot.mjs so nothing is compiled in the browser.
There's no built-in HTML sanitiser. Angular has one; AngeLite requires trustHtml() and recommends DOMPurify before wrapping. Writing a sanitiser of your own costs several KB and is easy to get wrong.
Escape hatches are yours. trustHtml() and trustUrl() are explicit, like Angular's bypassSecurityTrust*. Don't wrap user input.
No external audit, no track record. The others have years of review and disclosure processes. This one has tests, CodeQL and a policy.

Lessons I'd reuse on any project

Test against attack payloads, not intent. The first run made the framework look worst in its peer group, which is exactly what you want to learn from a test.
Prefer compile-time errors to runtime sanitisation when a construct has no legitimate use (on* bindings, srcdoc).
Filter by value, not by path, when the dangerous object can be reached many ways.
Document the non-goals. A security policy that says what it doesn't cover is more trustworthy than one that claims everything.
Make the safe thing the default and the unsafe thing greppable: trustHtml( is easy to search for in review.

Takeaways

Treat templates as code and data as hostile; build everything from that.
Six concrete holes were found by testing and closed with tests of their own.
The remaining risk (untrusted templates, no sanitiser, no audit) is documented, not hidden.

Next: how a performance budget in CI keeps all of this from making the framework slower.

No Zone.js, No Virtual DOM: How Signals and a Microtask Update Only What Changed (Inside AngeLite, Part 2)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:09:36 +0000

In part 1 I claimed AngeLite updates "only what changes" without Zone.js or a virtual DOM. This post shows the mechanism, using the actual source: a signals module of about 136 lines and a runtime of about 750.

The reactive core: three primitives

Function	What it is	Usage
`signal(value)`	a value you can change	`s()` reads, `s.set(x)` writes, `s.update(v => ...)` transforms, `s.peek()` reads without subscribing
`computed(fn)`	a derived value, recalculated only when something it reads changes	`total()`
`effect(fn)`	code that runs now and whenever the signals it reads change	returns a stop function

Here is the heart of it, trimmed from signals.js:

export function signal(value) {
  let subs = null;                       // allocated lazily, only if someone reads
  const read = () => {
    if (active) track(subs || (subs = new Set()));
    return value;
  };
  read.set = next => {
    if (Object.is(next, value)) return;  // no change, no notification
    value = next;
    if (subs) subs.forEach(n => n.notify());
  };
  read.update = fn => read.set(fn(value));
  read.peek = () => value;
  return read;
}

Three details are doing a lot of work:

active is a module-level pointer to the effect currently running. Reading a signal while an effect is active subscribes that effect. That's the whole dependency-tracking trick.
Subscriber sets are allocated lazily, so a signal nobody reads costs almost nothing.
Object.is short-circuits writes of the same value.

Batching in a microtask

An Effect re-runs not immediately but through a queue flushed in a microtask:

notify() {
  if (this.queued) return;
  this.queued = true;
  queue.push(this);
  if (!pending) {
    pending = true;
    queueMicrotask(flush);
  }
}

So three set() calls in a row cause one re-run and one repaint. The flip side is documented behaviour you should know: right after a set() the DOM doesn't reflect the change yet. await Promise.resolve() (or flush() in tests) is enough to wait.

sequenceDiagram
    participant U as Your code
    participant S as signal
    participant Q as microtask queue
    participant E as view effect
    participant D as DOM
    U->>S: count.set(1)
    S->>Q: notify(effect) (queued once)
    U->>S: count.set(2)
    S->>Q: already queued, skip
    Note over U,Q: current task ends
    Q->>E: flush()
    E->>S: read count() (re-subscribes)
    E->>D: write only values that changed

Templates compile to instructions, not to a virtual tree

A template is HTML with a few extensions:

Syntax	What it does
`{{ expr }}`	interpolation, always text
`[prop]="expr"`	binds a DOM property, or an `input()` for components
`[class.x]="cond"`, `[style.width.px]="n"`, `[attr.x]="v"`	class, style, attribute (null/false removes)
`(event)="statement"`	listens to an event
`[(ngModel)]="sig"`	two-way binding with a writable signal
`{{ x \	pipe:arg }}`

The compiler turns each template once into a blueprint: an HTML fragment plus a list of instructions ("this text node depends on this expression", "this element has this event"). Creating a view is then:

clone the blueprint's fragment,
walk it once applying the instructions,
attach one lean effect per view that re-evaluates the view's bindings and writes to the DOM only when a value changed.

No virtual tree is built or diffed. Expressions are evaluated by a small interpreter of our own (no eval, no new Function): literals, arithmetic, comparison and logical operators, ternary, ??, ./?./[ ], arrays, and calls to component methods.

Events are delegated

Handlers don't create a listener and closure per element. Events are delegated to document and stored as properties on the elements, so a table of 10,000 rows carries no per-row listeners. That's a big part of why memory stays low (about 6.6 MB for 10,000 rows in the project's benchmark versus 11.8 MB for the next lowest).

Control flow and keyed lists

@if, @else if, @else, @for and @empty use the Angular 17+ syntax:

@for (t of todos(); track t.id) {
  <li [class.done]="t.done" (click)="toggle(t)">{{ t.title }}</li>
} @empty {
  <li>Nothing to do</li>
}

@for reuses DOM nodes according to the track key, so reordering or updating a list moves existing elements instead of recreating them. When a list keeps the same keys in the same order, a fast path skips reconciliation (that optimisation took the "update every 10th row" scenario from about 9.8 ms to 7.9 ms in one benchmark run). Inside @for you get $index, $count, $first, $last, $even and $odd. Always give a stable key: without track, the key is the item itself, which is fine for strings and numbers but not for objects you recreate.

Rules that follow from the model

Plain properties don't repaint. this.name = 'Ada' notifies nobody. State you want reflected must be a signal: name = signal('Ada').
Treat lists and objects as immutable. Identity is compared, so mutate-in-place-and-reassign-the-same-array does nothing. Write items.update(l => [...l, next]).
Logic goes in the class. Expressions don't support arrow functions, object literals, assignments or new. If an expression needs more than one operator, give it a name (a method or a computed).

A limit worth knowing

There is one effect per view, not per binding. When a signal a view reads changes, every binding in that view is re-evaluated (but only written to the DOM if its value changed). For rows with few bindings that's the cheapest approach. For a component with hundreds of bindings and a signal that changes many times per second, finer-grained systems like Solid or Vue can win. The project's gap analysis lists this explicitly, along with its best-known cost: selecting a row re-runs 1,000 effects (about 1.3 ms, tied with Preact and Angular in the benchmark) and is the top candidate for a per-binding refinement.

Takeaways

Signals plus an active pointer give automatic dependency tracking in about 130 lines.
Microtask batching makes writes cheap and cleanup simple, at the cost of async DOM visibility.
Blueprints and delegated events replace the virtual DOM and per-element closures.
One effect per view is a conscious trade-off, and it's documented with its costs.

Next: the security model, and the six holes I found in my own framework.

A 6 KB Framework With Angular Syntax? Meet AngeLite (Inside AngeLite, Part 1)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:09:25 +0000

If you've written modern Angular, you probably miss a few things when you step outside it: the @if / @for control-flow syntax, templates with [prop] and (event), components with inputs and outputs, dependency injection, a router. If you've written React or Preact, you may miss something else: not shipping a framework's worth of bytes to render a button.

AngeLite is my attempt to have both. It's a signals framework with Angular-style templates, a core of about 6 KB gzip when templates are precompiled, no Zone.js, no virtual DOM, and a security model that assumes your data is hostile. This post is the "why"; the rest of the series is the "how".

Repository: duvanjamid/angelite · Docs (English and Spanish): duvanjamid.github.io/angelite-docs

The 30-second version

import { signal, component, mount } from '@duvanjamid/angelite';

class Counter {
  count = signal(0);
  inc() { this.count.update(n => n + 1); }
}

component(Counter, {
  selector: 'app-counter',
  template: `<button (click)="inc()">Clicks: {{ count() }}</button>`
});

mount(Counter, document.body);

No build step required either: include a <script> tag and templates compile in the browser (about 10 KB gzip including the compiler). When the app grows, precompile templates and ship only the runtime (about 6 KB). The component code doesn't change.

What it's built from

Three ideas:

Signals (signal, computed, effect). State lives in reactive values; when one changes, only what depends on it updates. There is no global change detection.
Angular-style templates. HTML with {{ }}, [prop], (event), @if and @for, compiled once into a list of instructions. There is no virtual DOM: creating a view is cloning the HTML and applying the instructions.
Optional modules. The core is small; the router, forms, HTTP client, i18n, animations, SSR, DevTools and a 33-component accessible UI library are separate imports you pay for only if you use them.

Why not just use X?

An honest answer, because the project's comparison page is honest about it too:

If you need the ecosystem, hiring pool and a decade of battle-testing, use React, Vue or Angular. AngeLite has no track record, no external security audit and a very small community.
If you want Preact-sized output but Angular-shaped templates and signals, that's the gap AngeLite aims at.
If you want a small, secure-by-default UI layer for widgets, dashboards or embedded apps, where bundle size and strict CSP matter more than ecosystem, that's the sweet spot.

The four commitments

Small

An app with precompiled templates weighs as much as the lightest framework in the project's benchmark: about 6.1 KB gzip for the table app versus Preact's 6.2 KB. What you don't import isn't downloaded: forms add about 0.9 KB, HTTP 1.3 KB, i18n 0.7 KB, and so on, each only for those who import them.

Fast without tricks

Fine-grained signals, delegated events and keyed list reconciliation. Crucially, a performance budget runs in CI, so a new feature can't quietly make the core slower (post 4).

Secure by default

Interpolation is always text. URLs are filtered. [innerHTML] requires an explicit trustHtml(). Expressions can never reach window. There's no eval or new Function anywhere, so it works under a strict CSP and Trusted Types (post 3).

Familiar

If you've written Angular 17+, you already know the syntax: @if, @for, [prop], (event), [(ngModel)], pipes, inputs and outputs. What changes is state: you write to signals instead of mutating properties.

A short history (and a rewrite)

AngeLite started as an earlier, larger iteration (decorators, directives, its own forms and router). The version described in this series is a deliberate rewrite around a small signals core. The old, unhardened code was removed from the tree (it stays in git history) and the new one was built under a rule: no feature lands if it breaks the performance budget, and the security model is tested against real attack payloads rather than assumed.

What this series covers

Why AngeLite (this post)
Signals, templates and fine-grained updates, with no Zone.js and no virtual DOM
Secure by default: six gaps I found in my own framework
A performance budget that runs in CI
Optional by design: the module system and what each core feature costs
Honest benchmarks and an honest comparison
SSR, hydration and "the blueprint is data"

Try it

npm install @duvanjamid/angelite

Or drop in the script bundle from the docs and open an HTML file. The documentation has runnable examples, a component library page with live controls, the benchmark, and a feature-by-feature comparison (including what's missing).

Next post: how a signal, a template and a microtask turn into DOM updates in about 750 lines of runtime.

Production-Hardening a Java Framework: Resilience, JWT/JWKS, Native Image and an MCP Server (Building Ligero, Part 7)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:09:00 +0000

A framework core can stay tiny only if the things real services need live somewhere else. In Ligero that "somewhere else" is a set of small, optional, mostly dependency-free modules. This last post of the series tours the production-hardening ones: resilience, scheduling, events, authentication, native image, and a couple of newer experiments (an HTTP QUERY method and an MCP server).

As with the rest of the series: Ligero is pre-1.0. Check the changelog for what's released versus unreleased.

Resilience: `ligero-resilience`

Outbound calls fail. The module gives you three primitives with no dependencies:

Retry with fixed or exponential backoff,
Timeout, which runs the call on a virtual thread and abandons overruns,
CircuitBreaker with the usual closed, open, half-open states.

The virtual-thread timeout is a nice example of Java 21 paying off: you can run the work on a cheap thread, wait with a deadline, and walk away from a hung call without a bespoke thread-pool strategy.

stateDiagram-v2
    [*] --> Closed
    Closed --> Open: failures exceed threshold
    Open --> HalfOpen: after cool-down
    HalfOpen --> Closed: probe succeeds
    HalfOpen --> Open: probe fails

Scheduling and events

ligero-scheduler is a small scheduler for background work: fixedRate, fixedDelay, once and dailyAt. Timing runs on a small daemon pool, but each task runs on its own virtual thread, so a slow or throwing job never stalls the timer or cancels its own schedule.

In ligero-core, an in-process Events bus provides typed publish/subscribe (with supertype delivery and isolated handler failures), and Ligero.onStart(...) / onStop(...) hooks run when the server starts and stops. There's also a Cache<K,V> SPI with load-through helpers and TTLs, an in-process InMemoryCache, and a distributed RedisCache in ligero-redis.

Authentication and authorization: `ligero-auth`

JWT support is implemented with the JDK's own crypto (javax.crypto / java.security), so there are no external dependencies. Properties worth calling out:

alg=none and algorithm-confusion tokens are rejected;
signature comparison is constant-time;
exp and nbf are enforced;
RS256 and ES256 (sign and verify) sit alongside HS256, and Jwks.parse(json, mapper) turns an OIDC provider's JWKS into JDK public keys by kid, so a service can validate tokens issued by an external identity provider. The verifier pins the algorithm, which defends against alg-confusion.

Jwt jwt = Jwt.hs256(secret, new JacksonBodyMapper());   // secret >= 32 bytes
String token = jwt.sign(Map.of("sub", "ada", "roles", List.of("admin")), Duration.ofHours(1));

app.use("/api", JwtAuthMiddleware.of(jwt));
app.get("/api/admin/stats", ctx -> {
    JwtAuthMiddleware.requireRole(ctx, "admin");        // 403 without the role
    String user = ctx.attribute(JwtAuthMiddleware.USER_ATTRIBUTE);
    ...
});

The module also covers stateless double-submit CSRF (XSRF-TOKEN cookie echoed in X-XSRF-TOKEN), HMAC-signed-cookie sessions with a pluggable SessionStore, and Basic auth. Scale-out is a module away: ligero-redis provides Redis-backed rate-limit and session stores shared across instances.

Data, your way

Three independent modules so you take only what you want: ligero-jdbc (SQL to records, transactions, no ORM, with optional HikariCP pooling via DataSources.pooled(...)), ligero-jpa (a thin Hibernate helper, bring your own provider), and ligero-migrations (Flyway at startup). Request validation is annotation-based (ligero-validation) and turns violations into automatic 400s.

Native image

GraalVM native-image does a closed-world analysis: anything reached by reflection, dynamic proxies or unregistered resources must be declared in metadata. Ligero's earlier design decisions pay off here:

Reflection-free core: routing, the middleware pipeline and Beans use no runtime reflection (an architecture test in the repo enforces this), so there is nothing to register.
Compile-time DI option: ligero-processor generates the bind(...) wiring at compile time.
ServiceLoader over scanning: engines, body mappers and template engines are discovered via META-INF/services, which ligero-core already registers for native.

Modules that are native-ready by construction include ligero-core, ligero-server-jdk, ligero-scheduler, ligero-resilience, ligero-auth and ligero-jdbc. The reflective adapters (Jackson, Hibernate) bring their own metadata needs, and the design note documents those boundaries rather than pretending they don't exist. The CLI itself ships as a native binary.

Two experiments worth watching

HTTP QUERY. app.query(path, handler) registers handlers for the IETF QUERY method: a safe, idempotent method like GET that carries a request body, for queries too large or structured for a URL. You read the body with ctx.body(...) as for POST. It's an early standard, so treat it as an experiment.

MCP servers: ligero-mcp. The Model Context Protocol lets an LLM call tools exposed by your app over JSON-RPC 2.0 (Streamable HTTP). With Ligero (illustrative sketch; see the docs for the exact schema type):

McpServer mcp = McpServer.create("orders", "1.0.0")
    .tool("find_order", "Look up an order by id", schema, args -> lookup(args));

app.use(mcp.http("/mcp"));

It implements the initialize handshake, ping, tools/list and tools/call, surfaces tool failures as MCP error results, and, like the rest of the framework, is dependency-free and reflection-free. If you were going to expose existing service capabilities to an AI agent anyway, doing it in the same process as your authenticated, observable HTTP stack is a pragmatic place to start.

OpenAPI

ligero-openapi generates an OpenAPI 3 document from your routes, with an opt-in Swagger UI. OpenApi.model(Class) generates components/schemas from your record types (scalars, enums, temporals, collections and nested records), using reflection only at document-build time, never on the request path.

The shape of the whole

flowchart TB
    core["ligero-core (router, middleware, Beans, SPIs)"]
    core --> eng["engine: jdk | jetty"]
    core --> obs["observability: otel, micrometer"]
    core --> sec["auth, validation, redis"]
    core --> data["jdbc, jpa, migrations"]
    core --> ops["resilience, scheduler, cache, events"]
    core --> dev["devtools, openapi, mcp"]

Everything hangs off a small core through SPIs and middleware. That's the series in one picture.

What I'd say after building it

Small core, sharp edges removed. The things that hurt in production (startup, hidden wiring, missing defaults) are the ones the core addresses directly.
Honesty is a feature. Docs state boundaries (what's native-ready, what needs metadata, what the JDK engine can't do), and the benchmark harness is public.
It's an open project. If you want to try it, break it, or contribute, start at the repo, the docs and the examples.

Thanks for reading the series. If there's a part you want to see go deeper, tell me in the comments.

Observability in a Lightweight Java Framework: Health, Metrics, Traces and OpenTelemetry (Building Ligero, Part 6)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:08:49 +0000

Devtools (previous post) is for development. In production you need something different: signals you can alert on, correlate across services and export to whatever backend your team already runs.

Ligero's approach to observability is shaped by one rule: the framework defines vocabulary and SPIs; the client chooses the backend. This post walks through the four pillars (health, metrics, logs, traces) and the design decisions behind each.

1. Health checks

app.use(HealthMiddleware.builder()
    .path("/health")
    .check("db", () -> dataSource.getConnection().isValid(1))
    .build());

GET /health returns 200 {"status":"UP","checks":{"db":"UP"}}, or 503 with the failing checks marked DOWN. Named checks matter operationally: the response tells the on-call engineer which dependency is down, and a 503 drives readiness in orchestrators.

2. Metrics: label by route pattern, not by path

MetricsMiddleware records method, matched route pattern, status and duration through the MetricsCollector SPI.

The key word is pattern: /users/{id}, not /users/48213. This is the single most important decision in HTTP metrics. Using raw paths as a label creates one time series per user id, which is unbounded cardinality, which is how you take down a metrics backend. The router already knows which pattern matched, so the middleware gets a bounded label for free.

// dependency-free; expose however you like
InMemoryMetricsCollector metrics = new InMemoryMetricsCollector();
app.use(new MetricsMiddleware(metrics));
app.get("/metrics", ctx -> ctx.json(metrics.snapshot()));

// or Micrometer (ligero-metrics-micrometer) for Prometheus/Datadog/...
MeterRegistry registry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
app.use(new MetricsMiddleware(new MicrometerMetricsCollector(registry)));

Two adapters, one SPI: the dependency-free in-memory collector for small services and tests, Micrometer for everything else.

3. Logs: structured, and joined to traces

app.use(new RequestLoggingMiddleware());     // GET /users -> 200 (431 µs)
app.use(RequestLoggingMiddleware.json());    // {"method":"GET","path":"/users","status":200,...}

The JSON form includes the request id when RequestIdMiddleware runs first. Logs are only useful in an incident if you can pivot from a log line to the trace and back, so the next piece matters.

4. Traces: W3C context and a vendor-neutral SPI

RequestIdMiddleware handles X-Request-Id passthrough/generation and parses the W3C traceparent header. Even with no tracing backend installed, it exposes the traceId as a context attribute, so your logs are correlatable across services.

For real tracing, the core defines a Tracer SPI and a TracingMiddleware; the first adapter is ligero-otel (OpenTelemetry). Datadog, New Relic, Jaeger and friends work through the OTel SDK or agent exporters, or you can implement the SPI directly.

// With the OTel Java agent (or SDK autoconfigure), ServiceLoader finds the tracer:
app.use(TracingMiddleware.fromServiceLoader());

// Or wire an explicit SDK:
app.use(new TracingMiddleware(new OtelTracer(openTelemetrySdk)));

Per request you get a SERVER span that:

joins the incoming W3C traceparent, so traces continue across services;
is named by the matched route pattern (GET /users/{id}), again bounded cardinality;
carries http.request.method, url.path, http.route and http.response.status_code;
records exceptions and marks the span ERROR on failures;
exposes its trace id as the traceId context attribute for log correlation.

flowchart LR
    A[Service A] -- traceparent --> L[Ligero service]
    L -- "SERVER span per route pattern" --> O[OTel SDK / agent]
    O --> V[(Backend of your choice)]
    L -- JSON access log + traceId --> G[(Log pipeline)]
    L -- route-pattern metrics --> P[(Metrics backend)]

Why SPIs instead of picking a vendor

Three reasons, all about who pays the cost of change:

Teams already have a stack. Hard-wiring one vendor means every adopter either accepts it or forks.
OpenTelemetry is the lingua franca. One adapter covers most backends, and the SPI covers the rest.
The core stays dependency-free. ligero-core depends only on slf4j-api; tracing and metrics libraries arrive only if you add the module.

A practical checklist

If you operate services like this, a few habits pay off regardless of framework:

Bound every label. Route patterns, not raw paths; status classes if you need to reduce further.
Propagate context everywhere. traceparent in, traceparent out on every outbound call.
Log the trace id. Make "log line to trace" one click.
Separate liveness from readiness. A /health that checks the database tells an orchestrator to stop sending traffic, which is not always the same as restart me.
Alert on symptoms. Latency and error rate per route pattern beat host-level resource graphs.

Takeaways

Health, metrics, logs and traces are built into the middleware pipeline, not bolted on.
Route-pattern labels give bounded cardinality for both metrics and span names.
The framework owns the vocabulary (SPIs); you own the backend (OTel, Micrometer or your own).

Next: what "production-ready" means beyond observability, covering resilience, auth, scheduling, native image and an MCP server.

I Built a Dashboard That Lights Up Your Java Beans in Real Time (Building Ligero, Part 5)

Duvan Jamid Vargas — Mon, 26 Oct 2026 02:08:38 +0000

Layered architectures have a visibility problem. You draw clean boxes on a whiteboard (controller, service, repository), but at runtime all you have is logs and a debugger. Which beans did this request touch? What went into the service layer, and what came out? How long did each layer take?

Ligero ships a development-time answer: ligero-devtools, a dashboard served at /ligero/dev where you run a request, watch it flow through your beans, and inspect the JSON going in and out of every layer, without a debugger, log statements, or Postman.

Think of it as "Swagger's try-it-out", plus a live dependency graph, plus a per-request tracer, in one self-contained page (no CDN assets) shipped inside your jar.

What you get

Without devtools	With devtools
Fire requests from curl or Postman in another window	Run any route straight from the dashboard
Read logs to guess which beans ran	See the exact path light up in the graph
Add `System.out.println` to see a layer's args/result	Click a node: arguments and return value shown as JSON
Wonder how long each layer took	Every call carries its timing
Keep a mental model of your wiring	The dependency graph is drawn for you, coloured by stereotype

Setup

// development only
implementation 'com.ligeroframework:ligero-devtools:<version>'

Devtools devtools = Devtools.create();

Beans beans = Beans.builder()
    .bind(NameRepo.class,     b -> new JdbcNameRepo(b.get(DataSource.class)))
    .bind(GreetService.class, b -> new DefaultGreetService(b.get(NameRepo.class)))
    .instrument(devtools.recorder())   // spies interface-typed beans
    .start();

Ligero app = Ligero.create();
app.beans(beans);
devtools.install(app, beans);          // mounts /ligero/dev

Open http://localhost:8080/ligero/dev, pick a route, fill in path params, query and a JSON body, and send it.

How the spying works (no agents, no bytecode)

This is the part I like, because it's built on the design decisions from the previous posts rather than on tricks.

The container exposes an instrumentation hook: Beans.Builder.instrument(BeanDecorator) can wrap every bean as it's created.
devtools.recorder() is such a decorator. Beans bound as interfaces get wrapped in a JDK dynamic proxy: no bytecode generation, no Java agent.
Beans bound as concrete classes can't be proxied by the JDK. They pass through untouched and the dashboard marks them "not traceable". Bind by interface if you want them traced (which is the architecture Ligero promotes anyway).
A middleware opens one trace per request, recording the matched route, request inputs and response body, and keeps the last 100 traces.
The dashboard's own endpoints are never traced.

sequenceDiagram
    participant B as Browser (dashboard)
    participant M as TraceMiddleware
    participant C as Controller (proxy)
    participant S as Service (proxy)
    participant R as Repository (proxy)
    B->>M: POST /api/orders (X-Ligero-Dev: trace-id)
    M->>C: handle
    C->>S: placeOrder(args)
    S->>R: save(args)
    R-->>S: result + timing
    S-->>C: result + timing
    C-->>M: response
    M-->>B: response + trace (SSE)

Each proxy records arguments, return value and elapsed time. A small, dependency-free reflective serializer (JsonValue) renders any layer's arguments and results as real JSON (records, beans, collections, maps) with depth and size caps and cycle guards.

Request correlation

When the dashboard fires a request it stamps an X-Ligero-Dev header. The trace middleware uses it as the trace id, so the browser can match the trace it receives over the live SSE stream to the request it sent. Outside the dashboard, the middleware reuses the request id when the request-id middleware is on. It's a good example of keeping a feature useful without adding a new protocol.

The graph is the real graph

The dependency graph isn't inferred from annotations or file layout. beans.graph() returns nodes tagged by stereotype and edges captured from the real resolution order at startup. Selecting a request highlights the transitive closure of beans it can reach (its dependency graph), and sending it overlays the actual execution path in the HTTP method's colour. Branches a run didn't take stay visible as dependencies but aren't part of the execution. Clicking a node shows each invocation with arguments, return value and timing.

The commerce-devtools example is a good stress test: an e-commerce backend with three modules (catalog, customers, orders) and around 15 beans with cross-module dependencies. Run it, pick POST /api/orders, and watch about 21 calls light up the path across services and repositories.

Endpoints

Endpoint	What
`GET /ligero/dev`	the dashboard (self-contained HTML)
`GET /ligero/dev/api/routes`	registered routes
`GET /ligero/dev/api/graph`	bean graph JSON (nodes, edges, unspied list)
`GET /ligero/dev/api/requests`	last 100 traces, most recent first
`GET /ligero/dev/api/stream`	SSE stream of completed traces

Never in production

Devtools exposes the arguments and return values of your beans. Two switches keep it out of production:

Classpath (recommended): keep the dependency out of production builds. Zero overhead, because nothing is there. The CLI can scaffold a project without it (--devtools false).
Environment: LIGERO_DEVTOOLS=false turns install() into a no-op without a code change.

Why this was cheap to build

Notice what devtools did not need: a classpath scanner, an agent, or annotation processing. Because wiring is explicit (post 3) and layers talk through interfaces (post 1), the framework already had the two things a tracer needs: a place to wrap objects and a graph of who depends on whom. Good architecture makes tooling cheap.

Takeaways

Instrumentation hooks in the container plus interface-typed beans let you trace every layer with plain JDK proxies.
Draw the real dependency graph from real resolution order, not from conventions.
Make dev tooling impossible to ship by accident: keep it off the production classpath.

Next: observability for production, where we trade the dashboard for health checks, route-pattern metrics, trace context and OpenTelemetry.

DEV Community: Duvan Jamid Vargas

Two Phones, One Dongle, One Car: Building a Phone Switcher for Android Auto (and Knowing When to Stop Reverse Engineering)

1. The problem

2. First dead end: speaking the "Carlinkit protocol"

3. The first big hit: the dongle is an Android accessory

4. The second big hit: the dongle's web API

5. What the dongle knows, and what it doesn't

6. Presence over Bluetooth Low Energy

The request / accept protocol

The security trade-off we chose

7. Drawing our own screen in the car

The honest failure: it didn't show up in a real car

8. Bugs that taught us something

9. The wall: server.cgi

Where we deliberately stopped

10. What the plain-text scripts told us

11. A detour that didn't pan out: internet for passengers

12. Shipping it

13. What the app does today

14. Try it, break it, contribute

Self-Hosting Infisical on Coolify: A Production-Style Guide with Compose, TLS, Machine Identities and GitHub OIDC

What you'll build

Prerequisites

1. Understand the three secrets (and the one you must not lose)

2. The Compose file

Option A: Coolify magic variables (what I deployed)

Option B: manual variables

3. Create the resource in Coolify

4. Verify

5. First login, then lock the door

6. Projects and environments

7. Machine identities: don't use a human account for automation

Option 1: Universal Auth (client ID and client secret)

Option 2 (recommended for GitHub Actions): OIDC, no stored secret

8. Operations

Common pitfalls

A note on automating this with AI agents

Checklist

SSR and Hydration in a Small Framework: What Works, What Doesn't, and What's Next (Inside AngeLite, Part 7)

What exists today: render in jsdom, no second implementation

Server and client, concretely

The honest incomplete part

Where the design could go: the blueprint is data

Why SSR on a small framework is hard: global state

Tooling around it

A caution that applies everywhere

Series wrap-up

Benchmarking Honestly: Where My Framework Wins and Where It Loses (Inside AngeLite, Part 6)

Method first

What it shows

What it doesn't measure

The comparison: where it loses

Limits of its own design (verified in the code)

Why publish this?

Reproduce it, and argue

Takeaways

Optional by Design: What Every Core Feature Costs in Bytes (Inside AngeLite, Part 5)

The registry trick: ops

The module map

What the core actually pays for

Error boundaries, cheaply

Dev warnings from the outside

Lazy loading, two different things

The architectural debt, written down

Takeaways

How a CI Performance Budget Keeps a 6 KB Framework From Growing (Inside AngeLite, Part 4)

The problem with measuring time in CI

The four layers

Layer 2 in detail: count the work, not the time

Layer 3: relative time, because absolute time lies

Design rules that keep the budget achievable

What a budget buys you: an audit trail

Pending improvements, with data

Takeaways

My Framework Ranked Last in the Security Tests. Here Are the 6 Holes I Fixed (Inside AngeLite, Part 3)

The trust model

What was verified

The six gaps, and the fixes

Content-Security-Policy recipe

What it does NOT protect you from

9. The wall: `server.cgi`

The registry trick: `ops`

Resilience: `ligero-resilience`

Authentication and authorization: `ligero-auth`