DEV Community: 木头人

Ditch Electron: Zero-Build Server-Driven UI with HTMX & Robyn

木头人 — Sun, 14 Jun 2026 00:57:40 +0000

Part 5 of the ERTH Architecture Series: Eliminating complex Javascript bundlers by rendering HTML fragments directly from Python inside a native WebView.

In the fourth part of this series, we integrated Turso and SQLModel into our Python sidecar, establishing a local-first persistent data channel with offline capabilities and cloud sync.

Now, we have a secure backend running on a dynamic port, protected by a watchdog and backed by database replication.

The last remaining step is to build the user interface.

Traditionally, this means setting up Node.js, running npm install, configuring Vite or Webpack, choosing React or Vue, setting up state management (Redux/Zustand), and writing boilerplate JSON API endpoints just to pass data back and forth. This frontend tax slows down development and inflates app bundle sizes.

What if we could skip the build pipeline entirely? What if our Python backend could return HTML fragments directly to the WebView, updating the interface instantly without full page reloads?

In this final post, we will integrate HTMX into our ERTH Stack (ElectroBun + Robyn + Turso + HTMX) to achieve a Zero-Build, Server-Driven UI.

The Hypermedia Exchange

Rather than fetching JSON and parsing it on the client, HTMX allows us to make AJAX requests directly from HTML attributes. The server processes the request, renders an HTML fragment, and returns it. HTMX then swaps this fragment directly into the DOM.

Here is the hypermedia lifecycle:

Let's build this.

Step 1: Writing Server-Driven UI in Python

In our Robyn backend, we implement a routing structure that supports Dual-Mode Responses. If a request comes from HTMX (indicated by the hx-request header), we render HTML. If it is a standard request, we return JSON (perfect for CLI testing and APIs).

Here is the task toggle route in Python:

# backend/app.py
from robyn import Robyn, Request, Response
from db import toggle_todo_status

app = Robyn(__file__)

def render_todo_item(todo: dict) -> str:
    """Renders a single todo list item as an HTML fragment"""
    completed_class = "completed" if todo["is_completed"] else ""
    checked_attr = "checked" if todo["is_completed"] else ""

    return f"""
    <div class="todo-item {completed_class}" id="todo-{todo['id']}">
        <input type="checkbox" 
               {checked_attr} 
               hx-put="/api/v1/todos/{todo['id']}/toggle"
               hx-target="#todo-{todo['id']}"
               hx-swap="outerHTML">
        <span>{todo['title']}</span>
    </div>
    """

@app.put("/api/v1/todos/:id/toggle")
async def toggle_todo(request: Request):
    todo_id = request.path_params.get("id")
    updated_todo = await toggle_todo_status(todo_id)

    if not updated_todo:
        return Response(status_code=404, description="Todo not found")

    is_htmx = request.headers.get("hx-request") == "true"
    if is_htmx:
        # Return pure HTML fragment for HTMX to swap in the DOM
        return Response(
            status_code=200,
            headers={"Content-Type": "text/html; charset=utf-8"},
            description=render_todo_item(updated_todo)
        )
    else:
        # Standard REST response
        import json
        return Response(
            status_code=200,
            headers={"Content-Type": "application/json"},
            description=json.dumps(updated_todo)
        )

Step 2: Designing the Zero-Build Frontend

On the frontend side inside our ElectroBun container, our index.html is extremely simple. We link directly to the local htmx.min.js file. There are no build tools, loaders, or packagers.

<!-- views/main/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>ERTH Assistant</title>
    <script src="js/htmx.min.js"></script>
    <style>
        .todo-item { display: flex; align-items: center; gap: 10px; padding: 8px; }
        .todo-item.completed span { text-decoration: line-through; color: #888; }
    </style>
</head>
<body>
    <h1>Tasks</h1>

    <!-- Loaded dynamically when the watchdog negotiates the dynamic port -->
    <div id="todo-list" hx-get="/api/v1/todos" hx-trigger="backend-ready from:body">
        <p>Connecting to backend engine...</p>
    </div>

    <script>
      // Automatically configure HTMX requests to inject security tokens and redirect to dynamic port
      document.addEventListener('htmx:configRequest', (evt) => {
        if (window.__ENV__ && window.__ENV__.BACKEND_PORT) {
          const port = window.__ENV__.BACKEND_PORT;
          if (evt.detail.path.startsWith('/')) {
            evt.detail.path = `http://127.0.0.1:${port}${evt.detail.path}`;
          }
        }
        if (window.__ENV__ && window.__ENV__.TOKEN) {
          evt.detail.headers['Authorization'] = `Bearer ${window.__ENV__.TOKEN}`;
        }
      });
    </script>
</body>
</html>

When the Bun process dispatches the backend-ready event, HTMX instantly triggers a GET request to retrieve the tasks, rendering them in place. When a user clicks a checkbox, HTMX sends a PUT request carrying the Opaque Token, and swaps the returned task layout in milliseconds—without re-rendering the entire page.

Recap of the ERTH Desktop Architecture

Across these five posts, we have constructed a new desktop architecture that challenges the monopoly of Electron and Tauri:

E - ElectroBun: Provides our lightweight frontend shell. It replaces Electron's bloated Chromium engine with native system WebViews (WebKit), cutting base memory usage to just 15MB.
R - Robyn: Launches an async Python sidecar on a dynamic Port 0. It runs Actix-web under the hood, running heavy business logic and enabling seamless integration with local AI toolkits (Ollama, PyTorch).
T - Turso (libSQL): Serves as our Local-First synchronization database. Combined with SQLModel, UUIDv7 indexing, and Tombstone deletion flags, it replicates data seamlessly between local SQLite and remote edge nodes.
H - HTMX: Bypasses complex JavaScript build chains. It fetches HTML fragments directly from our Robyn backend, simplifying client state management.

The Complete Architecture Handbook

If you want to build this system yourself, containing all 16 chapters of step-by-step guides, system startup logs, and packaging guides (compiling to a single 128MB .app / .exe bundle), check out our handbook:

📖 ERTH Assistant: Local-First + AI Sidecar Desktop Architecture on Leanpub (Includes a free 5-chapter preview edition!)

The full source code is completely open-sourced on GitHub:

👉 bnpysse/erth_assistant on GitHub

Thank you for following this series, and happy hacking!

Ditch Electron: Building a Local-First Sync Engine with Turso & SQLModel

木头人 — Sun, 14 Jun 2026 00:54:43 +0000

Part 4 of the ERTH Architecture Series: Implementing offline-first database schemas, UUIDv7 indexing, and cloud-edge SQLite replication.

In the third part of this series, we established a Zero-Trust shield around our Python backend (Robyn) using in-memory Opaque Tokens.

Our application is responsive, self-healing, and secure. But it is still stateless. If the user closes the application, all data disappears.

To turn our assistant into a true personal database, we need persistence. But we don't want a heavy database engine like PostgreSQL running on the user's laptop, nor do we want a simple offline SQLite file that isolates data on a single machine.

We want a Local-First Sync Engine:

0.1ms latency: All reads and writes must happen instantly on local disk.
Offline-first: The app must work fully on an airplane or subway without internet.
Seamless Cloud Sync: When network is restored, data must replicate bidirectionally to the cloud.
Multi-device roaming: Sync across laptops, tablets, and phones without data conflicts.

In this fourth post, we will build this layer using Turso (libSQL) and SQLModel, leveraging UUIDv7 and Tombstone deletion patterns to handle offline concurrency.

The Synchronization Architecture

Our Local-First database architecture relies on Turso's embedded replica synchronization:

To ensure this works smoothly without database corruption, we must redesign our schemas using two core concepts: UUIDv7 and Tombstones.

Concept 1: Ditch Autoincrement IDs, Use UUIDv7

In single-machine apps, INTEGER PRIMARY KEY AUTOINCREMENT is standard. But in local-first apps, you may write data on your phone and laptop concurrently while offline. If both assign ID=5, they will collide and corrupt the synchronization channel when you reconnect.

To prevent collisions, we must generate decentralized, unique primary keys. We select UUIDv7 (RFC 9562):

Why not UUIDv4? UUIDv4 is completely random. In database engines like SQLite, inserting random strings forces index B-Trees to split continuously, slowing down I/O performance.
Why UUIDv7? UUIDv7 combines a millisecond timestamp with random bytes. This means it is globally unique (no collisions) but monotonically increasing over time. SQLite B-Tree indexes can insert new keys sequentially, preserving high-speed write performance.

Concept 2: The Tombstone Deletion Pattern

If client A deletes a record physically (DELETE FROM todos WHERE id=5) while offline, client B doesn't know it was deleted. During sync, the cloud sees that client B has task 5 but client A does not, and it will "resurrect" the deleted task.

To avoid these "ghost records," we must never physically delete data. Instead, we use Tombstones:

We add an is_deleted integer flag.
Deletions update is_deleted=1 and update the updated_at timestamp.
The sync engine propagates this update. When reading lists, we query WHERE is_deleted=0.

Step 1: Implementing the SQLModel Layer in Python

We install SQLModel, which combines SQLAlchemy's database mapping with Pydantic's data validation. Here is our complete database initialization and operations layer in Python:

# backend/db.py
import os
import time
import uuid
from sqlmodel import Field, SQLModel, create_engine, Session, select

# Configuration Eviction: Pull database connection string from environment
DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///local_edge.db")

connect_args = {}
if DATABASE_URL.startswith("sqlite"):
    connect_args = {"check_same_thread": False}

engine = create_engine(DATABASE_URL, connect_args=connect_args)

class Todo(SQLModel, table=True):
    """Data contract model for tasks"""
    __tablename__ = "todos"

    id: str = Field(primary_key=True)
    title: str
    is_completed: int = Field(default=0)
    is_deleted: int = Field(default=0)  # Tombstone flag
    created_at: int
    updated_at: int

def generate_uuidv7() -> str:
    """Generate an RFC 9562 compatible UUIDv7 string"""
    timestamp_ms = int(time.time() * 1000)
    timestamp_bytes = timestamp_ms.to_bytes(6, byteorder='big')
    rand_bytes = bytearray(os.urandom(10))

    # Structure version (7)
    rand_a = int.from_bytes(rand_bytes[0:2], byteorder='big') & 0x0FFF
    time_hi_and_version = (7 << 12) | rand_a

    # Structure variant (2)
    rand_b = int.from_bytes(rand_bytes[2:4], byteorder='big') & 0x3FFF
    clk_seq_and_variant = 0x8000 | rand_b
    node = rand_bytes[4:10]

    val = uuid.UUID(fields=(
        int.from_bytes(timestamp_bytes[0:4], byteorder='big'),
        int.from_bytes(timestamp_bytes[4:6], byteorder='big'),
        time_hi_and_version,
        clk_seq_and_variant >> 8,
        clk_seq_and_variant & 0xFF,
        int.from_bytes(node, byteorder='big')
    ))
    return str(val)

async def init_db():
    """Verify local schema and apply updates at startup"""
    SQLModel.metadata.create_all(engine)

async def get_active_todos() -> list:
    """Fetch active todos sorted by creation time"""
    with Session(engine) as session:
        statement = select(Todo).where(Todo.is_deleted == 0).order_by(Todo.created_at.desc())
        return [todo.model_dump() for todo in session.exec(statement).all()]

async def add_todo(title: str) -> dict:
    """Persist a new todo item"""
    todo_id = generate_uuidv7()
    now = int(time.time() * 1000)
    todo = Todo(
        id=todo_id, title=title, is_completed=0, is_deleted=0, created_at=now, updated_at=now
    )
    with Session(engine) as session:
        session.add(todo)
        session.commit()
        session.refresh(todo)
        return todo.model_dump()

async def soft_delete_todo(todo_id: str) -> bool:
    """Soft delete using a tombstone flag"""
    with Session(engine) as session:
        todo = session.get(Todo, todo_id)
        if not todo or todo.is_deleted == 1:
            return False
        todo.is_deleted = 1
        todo.updated_at = int(time.time() * 1000)
        session.add(todo)
        session.commit()
        return True

Step 2: Handoff from Local-Only to Cloud Sync

Because we decoupled the database path using Configuration Eviction (reading DATABASE_URL from environment variables), our database can transition instantly from local SQLite to a remote Turso cloud database without changing any Python source code.

For local development and offline use, the system defaults to a local file database:

# Falls back to sqlite:///local_edge.db
uv run python app.py

When the user logs in and establishes a network sync connection to their Turso edge cluster, we spin up the backend by injecting the LibSQL connection credentials:

# Format: sqlite+libsql://<remote_URL>?auth_token=<YOUR_TOKEN>
env DATABASE_URL="sqlite+libsql://erth-assistant-username.turso.io?auth_token=eyJhbGci..." uv run python app.py

Under the hood, SQLModel automatically recognizes the sqlite+libsql driver, connects to the cloud via WebSockets (Hrana protocol), and synchronization begins silently in the background. If the network drops, it falls back to the local replica, preserving 0.1ms query performance.

What’s Next?

Our desktop app now handles persistence, self-healing, and secure cloud synchronization. Now it's time to build the frontend.

But we want to avoid Node.js build complexity. We don't want Webpack, Vite, or React/Vue configurations to slow down frontend-backend iteration.

In our final post (Part 5), we will use HTMX over Robyn to achieve Zero-Build server-driven UI rendering directly inside our ElectroBun desktop window.

📖 Read the Full Book on Leanpub (Includes a free 5-chapter preview edition!)

👉 Explore the open-source code on GitHub

Stay tuned for Part 5!

Ditch Electron: Securing Local Socket Communications using Opaque Tokens

木头人 — Sun, 14 Jun 2026 00:46:31 +0000

Part 3 of the ERTH Architecture Series: Preventing port-scanning attacks and local socket hijacking in multi-process desktop apps.

In the second part of this series, we built a self-healing Watchdog daemon in Bun to monitor and resurrect our Python sidecar backend (Robyn).

Now, our desktop app is extremely stable. But it is also extremely insecure.

You might think: "This is a desktop app running entirely on 127.0.0.1 (localhost). People from the internet can't access it, so why do I need security?"

This is a classic cognitive blind spot in desktop app development. In reality, your local loopback interface is shared globally by the operating system. Any script running in the user’s web browser (e.g., a malicious website they happen to visit) can aggressively scan local ports (from 10000 to 65535). Once it hits your Robyn sidecar's dynamic port, it can send unauthenticated POST requests to delete databases, read private files, or trigger system actions.

To prevent this, we must build a Zero-Trust Shield using Opaque Tokens to lock down all communication between the frontend WebView and the Python sidecar.

The Zero-Trust Security Model

To block unauthorized local traffic, the frontend and backend must share a cryptographically secure, short-lived token. Any request lacking this token will be instantly rejected by Robyn with a 403 Forbidden response.

Here is how the defense line functions:

Let's implement this architecture step-by-step.

Step 1: Generating the Ephemeral Token in Bun

Rather than saving credentials to a local config file (which could be read by malware on the system), we generate a random UUIDv4 in Bun’s process memory at startup. This token exists only during the application's runtime.

// src-app/frontend/src/bun/index.ts
// Generate a cryptographically secure, one-time Opaque Token in memory
const agentSecretToken = crypto.randomUUID();

Next, we inject this token into the child process's environment variables when we spawn the Python sidecar:

// Spawn the Robyn child process, injecting the token silently
backendProcess = spawn({
  cmd: ["uv", "run", "python", "app.py"],
  cwd: backendPath,
  env: {
    ...process.env,
    AGENT_SECRET_TOKEN: agentSecretToken, // Cross-process memory delivery
    PYTHONUNBUFFERED: "1"
  },
  stdout: "pipe",
  stderr: "pipe",
});

Step 2: Implementing Python Interception Middleware

On the Python side, Robyn reads this secret token at startup. We implement a global @app.before_request() decorator that intercepts all incoming requests and verifies the Authorization header.

# backend/app.py
import os
import json
from robyn import Robyn, Request, Response, ALLOW_CORS

app = Robyn(__file__)

# Load the secret token injected by the Bun main process
AGENT_SECRET_TOKEN = os.environ.get("AGENT_SECRET_TOKEN")

@app.before_request()
def auth_middleware(request: Request):
    # CRITICAL: Always bypass CORS preflight OPTIONS requests!
    if request.method == "OPTIONS":
        return request

    auth_header = request.headers.get("Authorization") or request.headers.get("authorization")
    expected_token = f"Bearer {AGENT_SECRET_TOKEN}"

    # Check authorization header
    if auth_header == expected_token:
        return request

    # Block unauthorized request
    return Response(
        status_code=403,
        headers={"Content-Type": "application/json"},
        description=json.dumps({"error": "Forbidden: Invalid or Missing Opaque Token"})
    )

Step 3: Resolving the OPTIONS Preflight Trap

If you add custom headers like Authorization to cross-origin requests, the browser WebView will trigger an OPTIONS preflight request before sending the actual request (e.g. a POST or PUT).

If your authentication middleware immediately checks for the Authorization header and rejects the request, the OPTIONS preflight will fail with a 403 Forbidden. The browser will then block the subsequent real request, causing your frontend to hang.

This is why we do two things:

Pass OPTIONS through: The first line in our Python middleware returns the request immediately if method == "OPTIONS".
CORS configuration: We explicitly configure CORS in Robyn to whitelist our custom headers:

# Configure CORS to accept custom headers and HTMX signatures
ALLOW_CORS(app, origins=["*"], headers=[
    "Authorization", "Content-Type", 
    "hx-target", "hx-current-url", "hx-request", "hx-trigger"
])

Step 4: Injecting the Token into the WebView

When the WebView DOM is ready, the Bun process injects both the dynamic port and the secret token into the WebView’s window object:

win.webview.on("dom-ready", () => {
  if (portFound && backendPort > 0) {
    win.webview.executeJavascript(`
      window.__ENV__ = {
        BACKEND_PORT: ${backendPort},
        TOKEN: "${agentSecretToken}"
      };
      window.dispatchEvent(new CustomEvent('backend-ready', { 
        detail: { port: ${backendPort}, token: "${agentSecretToken}" } 
      }));
    `);
  }
});

Now, we hook into HTMX's configuration interceptor in our HTML frontend to automatically append the token to every outgoing AJAX request:

<script>
  document.addEventListener('htmx:configRequest', (evt) => {
    // Append the dynamic dynamic port to local URLs
    if (window.__ENV__ && window.__ENV__.BACKEND_PORT) {
      const port = window.__ENV__.BACKEND_PORT;
      if (evt.detail.path.startsWith('/')) {
        evt.detail.path = `http://127.0.0.1:${port}${evt.detail.path}`;
      }
    }

    // Inject the Opaque Token into the request headers
    if (window.__ENV__ && window.__ENV__.TOKEN) {
      evt.detail.headers['Authorization'] = `Bearer ${window.__ENV__.TOKEN}`;
    }
  });
</script>

Penetration Testing the Shield

To verify this, we run a local penetration test using curl.

If we send an unauthenticated request to the sidecar:

curl -i http://127.0.0.1:54321/api/v1/health

Robyn instantly intercepts and returns:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error": "Forbidden: Invalid or Missing Opaque Token"}

But when we pass the correct token:

curl -i -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:54321/api/v1/health

It returns:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "healthy"}

Our loopback interface is now fully locked down.

What’s Next?

Our dual-core engine is responsive, self-healing, and secure. But our application is still stateless. If the user restarts their computer, all data is lost. We need a persistence layer.

But we don't want a heavy local database daemon, and we also want our app to work offline on the subway and sync to the cloud when network becomes available.

In Part 4, we will introduce the Local-First Philosophy using Turso (libSQL) for seamless, zero-latency cloud-edge data sync.

📖 Read the Full Book on Leanpub (Includes a free 5-chapter preview edition!)

👉 Explore the open-source code on GitHub

Stay tuned for Part 4!

Ditch Electron: Implementing Watchdog Heartbeat & Auto-Healing for Multi-Process Desktop Apps

木头人 — Sat, 13 Jun 2026 01:22:40 +0000

Part 2 of the ERTH Architecture Series: How to build a Bun watchdog daemon to detect, kill, and resurrect crashed Python sidecar processes with dynamic port negotiation.

In the first part of this series, we established the core foundation of our ERTH Stack (ElectroBun + Robyn + Turso + HTMX) desktop application. We successfully spawned a high-performance Python backend (Robyn) as a child process from a Bun master process, using Port 0 to dynamically allocate a port and avoid port collisions.

But in real-world desktop environments, things are rarely that simple.

What happens if the Python process enters an asynchronous deadlock? What if it crashes due to a C-level memory access violation? Or what if the operating system aggressively reclaims memory and terminates your sidecar backend while the frontend shell remains open?

If you do not have a robust recovery strategy, your application will hang indefinitely, leaving your user staring at a frozen, unresponsive screen.

In this second post, we will build a production-grade Watchdog Heartbeat & Auto-Healing Pipeline that turns our dual-core architecture into a self-healing, crash-resilient application.

The Self-Healing Architecture

In a distributed local desktop architecture, the frontend (Bun) acts like a sonar, periodically pinging the sidecar backend (Robyn) via a lightweight, dedicated health probe. If the backend fails to respond within a specific timeout, the master process assumes the sidecar is dead or hung, terminates it surgically, and restarts it on a fresh dynamic port.

Here is the lifecycle of our watchdog in action:

Let's build this step-by-step.

Step 1: Implementing the Heartbeat Endpoint in Python

We start by exposing an extremely lightweight, high-priority /ping route in our Python Robyn backend. This route bypasses heavy database checks or business logic to minimize resource overhead.

# backend/app.py
from robyn import Robyn, Request, Response
import json

app = Robyn(__file__)

@app.get("/ping")
def ping(request: Request):
    """Low-overhead watchdog heartbeat probe"""
    return Response(
        status_code=200,
        headers={"Content-Type": "application/json"},
        description=json.dumps({"status": "pong"})
    )

if __name__ == "__main__":
    app.start(host="127.0.0.1", port=0)

This ensures the main process has a clean endpoint to evaluate whether the Python interpreter runtime is responsive and executing requests.

Step 2: Coding the Bun Watchdog Daemon

On the Bun frontend control layer, we refactor our process lifecycle management. Instead of starting the backend once and forgetting it, we encapsulate startup in a reusable startBackend() function and run an asynchronous heartbeat check every 3 seconds.

Here is the implementation:

// src-app/frontend/src/bun/index.ts
import { spawn } from "bun";
import { resolve } from "path";

let backendProcess: any = null;
let portFound = false;
let backendPort = 0;
let watchdogInterval: any = null;
let failCount = 0;

const PORT_CAPTURE_REGEX = /listening on: [^:]+:(\d+)|http:\/\/127\.0\.0\.1:(\d+)/;

// Spawns the Robyn process and listens to stdout for dynamic port allocation
const startBackend = () => {
  portFound = false;
  backendPort = 0;

  console.log(`🚀 [ElectroBun] Starting Robyn backend process...`);

  backendProcess = spawn({
    cmd: ["uv", "run", "python", "app.py"],
    cwd: resolve(__dirname, "../../../backend"),
    stdout: "pipe",
    stderr: "pipe",
  });

  // Intercept stdout to parse the dynamically negotiated port
  (async () => {
    const reader = backendProcess.stdout.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split("\n");
      buffer = lines.pop() || "";

      for (const line of lines) {
        process.stdout.write(`[Robyn STDOUT] ${line}\n`);

        if (!portFound) {
          const match = line.match(PORT_CAPTURE_REGEX);
          if (match) {
            const rawPort = match[1] || match[2];
            backendPort = parseInt(rawPort, 10);
            portFound = true;
            console.log(`⚡ [ElectroBun] Captured backend port: ${backendPort}`);
            startWatchdog(); // Begin active polling
            break;
          }
        }
      }
    }
  })();
};

// Polling daemon that hits the /ping endpoint
const startWatchdog = () => {
  if (watchdogInterval) clearInterval(watchdogInterval);
  failCount = 0;

  console.log(`📡 [Watchdog] Heartbeat scanning activated on port :${backendPort}`);

  watchdogInterval = setInterval(async () => {
    if (!portFound || backendPort === 0) return;

    try {
      // Set a strict 1-second timeout for the ping probe
      const res = await fetch(`http://127.0.0.1:${backendPort}/ping`, {
        signal: AbortSignal.timeout(1000)
      });

      if (res.ok) {
        const data = await res.json();
        if (data.status === "pong") {
          failCount = 0; // Reset counter on success
          return;
        }
      }
      failCount++;
    } catch (e) {
      failCount++;
    }

    // Auto-heal if the sidecar fails 3 consecutive times
    if (failCount >= 3) {
      console.log(`🚨 [Watchdog] 3 consecutive heartbeats lost. Backend hung!`);
      console.log(`🚨 [Watchdog] Triggering auto-healing and restarting backend...`);

      killBackend(true); // Kill current sidecar and auto-restart
    }
  }, 3000);
};

// Surgically recycle the backend child process
const killBackend = (autoRestart = false) => {
  if (backendProcess && !backendProcess.killed) {
    console.log("🛑 [ElectroBun] Terminating Robyn backend process...");
    backendProcess.kill("SIGTERM");
  }
  if (watchdogInterval) {
    clearInterval(watchdogInterval);
  }

  if (autoRestart) {
    startBackend();
  }
};

// Register cleanup listeners to prevent leaving zombie processes on exit
process.on("SIGINT", () => killBackend(false));
process.on("SIGTERM", () => killBackend(false));
process.on("exit", () => killBackend(false));

startBackend();

The Engineering Details: Why a 3-Second Probe?

When designing a heartbeat loop, you face a trade-off between responsiveness and battery/CPU consumption:

If you ping every 100 milliseconds, you recover instantly, but you waste CPU cycles and drain the laptop battery.
If you ping every 30 seconds, your application remains frozen for half a minute before recovering, causing a terrible user experience.

Pinging every 3 seconds with a 3-miss tolerance strikes the perfect balance. It guarantees that a crashed or hung backend will be resurrected within 9 to 12 seconds, while consuming virtually 0% CPU overhead.

Live Disaster Recovery Test

When we run this pipeline, the watchdog works silently. If we simulate a sudden backend failure by running kill -9 $(lsof -t -i :<PORT> -sTCP:LISTEN) in another terminal window, the output demonstrates the instant self-healing loop:

📡 [Watchdog] Heartbeat scanning activated on port :54337
[Robyn STDOUT] INFO:actix_server.server:starting service...
... (Backend runs normally) ...

🚨 [Watchdog] 3 consecutive heartbeats lost. Backend hung!
🚨 [Watchdog] Triggering auto-healing and restarting backend...
🛑 [ElectroBun] Terminating Robyn backend process...
🚀 [ElectroBun] Starting Robyn backend process...
⚡ [ElectroBun] Captured backend port: 54518
📡 [Watchdog] Heartbeat scanning activated on port :54518

The app detects the crash, kills the dead process handle, spins up a new instance, negotiates a new port (54518), and injects it back into the WebView. The user experiences nothing more than a brief loading spinner.

What’s Next?

Our dual-core engine now heals itself from crashes. But opening local network ports exposes a massive security risk. Any browser script running on a malicious website in the user's browser could scan local ports, find our Robyn port, and hijack our backend to steal data.

In Part 3, we will secure our local communications using Opaque Tokens and custom request interceptors, establishing an absolute Zero-Trust shield.

📖 Read the Full Book on Leanpub (Includes a free 5-chapter preview edition!)

👉 Explore the open-source code on GitHub

Stay tuned for Part 3!

Ditch Electron: Spawning a Rust-Powered Python Sidecar from Bun

木头人 — Fri, 12 Jun 2026 15:51:24 +0000

Part 1 of the ERTH Architecture Series: Launching local backends on Port 0, dynamic port negotiation, and establishing the dual-core desktop backbone.

If you are building a modern desktop application, you are probably tired of the same old options.

On one hand, you have Electron. It’s the industry standard, but it forces you to bundle a full Chromium browser and a Node.js runtime with every app. Even a simple "Hello World" takes up 200MB+ of disk space and eats hundreds of megabytes of RAM. For background utility utilities or AI assistants that need to be nimble, this is a massive tax.

On the other hand, you have Tauri. It solves the bundle size issue by binding to OS-native WebViews and using Rust for the backend. But unless you are already a Rust expert, you will find yourself fighting the compiler's borrow checker and async lifecycles, slowing down your development velocity.

But what if you want to use Python for its rich AI ecosystem (Ollama, SQLModel, PyTorch), but still keep the UI lightweight, fast-loading, and responsive?

Welcome to the ERTH Stack (ElectroBun + Robyn + Turso + HTMX). In this first post of our 5-part series, we will break down how to launch a high-performance Python sidecar backend directly from a Bun-based desktop shell, bypassing the bloated Electron environment entirely.

The Concept: Heterogeneous Dual-Core

In the ERTH architecture, the desktop app is split into two physical processes:

The Main Process (Bun): Responsible for native OS window management, IPC (Inter-Process Communication), and hosting the HTML/CSS view. We use ElectroBun—a next-generation, ultra-lightweight wrapper that binds directly to the OS-native WebKit engine (no Chromium bloat!).
The Sidecar Process (Python/Robyn): Responsible for heavy computations, database access, and local LLM orchestration. We use Robyn, an incredibly fast, Rust-based async Python web framework.

Here is how the lifecycle and process boundaries interact:

Step 1: Spawning the Robyn Sidecar from Bun

Under the hood of the Bun master process, we don't want to rely on static ports. If your app is hardcoded to run on port 8080, and the user already has a service running on that port, your application will crash instantly.

To avoid this, we start the Robyn backend on Port 0. In computer networking, binding to port 0 tells the operating system to automatically allocate a random, currently unused high-range port.

Here is the production-grade TypeScript code in Bun to spawn the Robyn child process and dynamically intercept the allocated port:

// src-app/frontend/src/bun/index.ts
import { join } from 'path';

let backendPort = 0;
let portFound = false;

// Resolve the path to the packaged Python binary or local script
const pythonAppPath = join(import.meta.dir, '..', '..', '..', 'backend', 'app.py');

const backendProcess = Bun.spawn(["uv", "run", "python", pythonAppPath], {
  stdout: "pipe", // We need to read the stdout log stream
  stderr: "inherit",
  env: {
    ...process.env,
    ROBYN_PORT: "0", // Force Robyn to bind to a dynamic port
  }
});

// Create a reader to parse stdout line by line
const reader = backendProcess.stdout.getReader();
const decoder = new TextDecoder();
let buffer = "";

(async () => {
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() || ""; // keep the last partial line in buffer

    for (const line of lines) {
      console.log(`[Backend Log] ${line}`);

      // Look for Actix/Robyn startup signature: "listening on: 127.0.0.1:XXXXX"
      const match = line.match(/listening on:\s+127\.0\.0\.1:(\d+)/);
      if (match) {
        backendPort = parseInt(match[1], 10);
        portFound = true;
        console.log(`🚀 Watchdog intercepted backend port: ${backendPort}`);

        // Notify the WebView window that the communication channel is ready
        initializeWebView(backendPort);
        break;
      }
    }
    if (portFound) break;
  }
})();

Step 2: Setting up Robyn on Port 0

On the Python side, Robyn is incredibly simple to configure. By reading the ROBYN_PORT environment variable or defaulting to 0, we boot up a multi-threaded Rust Actix-web server underneath Python:

# src-app/backend/app.py
import os
from robyn import Robyn, Request, Response

app = Robyn(__file__)

@app.get("/api/v1/health")
async def health_check(request: Request):
    return Response(
        status_code=200,
        headers={"Content-Type": "application/json"},
        description='{"status": "healthy", "database": "connected"}'
    )

if __name__ == "__main__":
    # Get port from environment or fallback to 0
    port = int(os.environ.get("ROBYN_PORT", 0))
    app.start(host="127.0.0.1", port=port)

Real-World Output

When you run this architecture, the terminal logs show the magic of dynamic negotiation in action:

Robyn outputs: Starting server at http://127.0.0.1:0
The OS intercepts and binds it to 127.0.0.1:57220.
Bun catches the 57220 port from the log stream, mounts the WebView, and binds all future HTMX requests to http://127.0.0.1:57220.

No port collision crashes. No manual user configuration. It just works.

What’s Next?

We now have a Bun frontend shell connected to a Python sidecar. But running multiple processes introduces new architectural failure points:

What happens if the Python process crashes or is killed by the system?
How do we prevent other local programs from scanning ports and hijacking our Python API?

In the next post, we will cover the Watchdog Heartbeat Pipeline and Opaque Token Security Interceptors to make this dual-core setup industrial-grade and secure.

If you want to skip ahead and read the full blueprint immediately, check out the companion book:

📖 ERTH Assistant: Local-First + AI Sidecar Desktop Architecture on Leanpub (Includes a free 5-chapter preview edition!)

The full source code is also open-sourced on GitHub:

👉 bnpysse/erth_assistant on GitHub

Stay tuned for Part 2!

Ditch Electron: Why I Abandoned Electron & SPAs to Build a 128MB Local-First Desktop AI Agent

木头人 — Fri, 12 Jun 2026 15:51:04 +0000

If you are building a modern desktop application, you are probably tired...

How the ERTH Architecture (ElectroBun + Robyn + Turso + HTMX) breaks the obesity of modern desktop app development.

If you’ve tried to build a cross-platform desktop application recently, you’ve likely faced the classic developer’s dilemma:

Electron makes developer velocity fast, but at the cost of dragging a bloated Chromium kernel and Node.js runtime into every build. A simple "Hello World" easily eats up 200MB+ of disk space and hundreds of megabytes of RAM.
Tauri solves the footprint issue by using OS-native WebViews and Rust, but forces you onto Rust’s steep learning curve, sacrificing the agility of rapid prototyping.
The Python Distribution Hell: With the rise of local LLMs and Edge AI, Python is the de facto language for AI orchestration. Yet, packaging Python, its heavy dependencies, and databases into a double-click-to-run package for non-technical users remains a nightmare.

Faced with these shackles, I decided to take a step back and rewrite the physical laws of desktop development.

Today, I’m introducing the ERTH Stack (ElectroBun + Robyn + Turso + HTMX)—a heterogeneous, local-first, zero-JS desktop application architecture designed for independent full-stack creators.

And yes, the entire bundle—including a browser shell, a high-performance Python sidecar, a local database, and local AI agent execution—packages into a single 128MB standalone binary.

Our open-source implementation is live on GitHub:

👉 GitHub Repository: bnpysse/erth_assistant

The Core Pillars of the ERTH Architecture

To achieve a minimalist footprint without sacrificing developer velocity, we structured the architecture into four core layers:

              ERTH ARCHITECTURE
  [E]lectroBun (UI Shell) ───[HTMX]───► [H]TMX (Zero-JS Frontend)
        │                                    ▲
      (IPC)                               (HTTP)
        ▼                                    │
  [R]obyn (Python Sidecar) ───────────► [T]urso / libSQL (Local-First DB)

1. [E]lectroBun: The Lightweight Shell

Instead of Electron’s heavy Chromium, ElectroBun binds directly to the OS-native WebKit engine (Cocoa WebKit on macOS, WebView2 on Windows). The main process runs on Bun, launching in milliseconds and keeping idle memory consumption incredibly low.

2. [R]obyn: The Rust-Powered Python Sidecar

Python handles the heavy lifting—AI logic, local LLM mounting, and database orchestration. We use Robyn, a high-performance, async Python web framework built on a Rust runtime. It runs as a background sidecar process, dynamically spawned by the Bun main process on Port 0 to avoid port collision conflicts.

3. [T]urso: Local-First with Cloud-Edge Sync

We use libSQL (Turso). The database is a physical file residing locally (local_edge.db), executing CRUD operations at a blinding 0.1ms latency. Meanwhile, a silent background thread replicates incremental changes to the Turso cloud database, providing seamless offline immunity.

4. [H]TMX: Hypermedia-Driven UI

We threw client-side SPAs (React/Vue) and Webpack/Vite pipelines out of the window. By introducing HTMX, our frontend behaves as a lightweight hypermedia receiver. The Robyn Python backend renders HTML fragments directly, and HTMX swaps them into the DOM out-of-band (OOB Swap). Zero client-side JS business logic, zero state-sync headaches.

Surviving the Deep-Water Debugging Zone

Building a heterogeneous cross-language desktop app is not without its traps. During development, we had to solve three major technical challenges:

Watchdog Self-Healing Pipeline: Since the app runs a Bun main process and a Python sidecar, what happens if the Python backend crashes? We built a watchdog monitoring pipeline that probes the backend every 3 seconds. If the backend dies, the watchdog executes a silent SIGTERM restart and re-negotiates a new dynamic port seamlessly.
CORS & OPTIONS Preflight Trap: Since HTMX sends cross-origin requests with custom headers (hx-request, hx-target), browsers trigger automatic OPTIONS preflight checks. In Robyn’s Rust-based core, we had to ensure preflight requests bypass the auth middleware to prevent socket deadlocks.
Opaque Token Interception: To prevent other local programs from scanning ports and hijacking our Python backend, communication is locked down with UUIDv7 short-lived tokens (Opaque Tokens) injected during startup.

Read the Full Engineering Blueprint

I have documented the entire process—from setting up the dual-core ignition, building the self-healing watchdog, writing Cocoa NSPanel window float hooks, to building cross-platform GitHub Actions pipelines—in my new book:

📖 "ERTH Assistant: Local-First + AI Sidecar Desktop Architecture"

If you want to build high-performance, secure desktop AI assistants, you can get the book on Leanpub.

I have also made a Free 5-Chapter Preview Edition available for download directly on the landing page!

Let me know what you think of the ERTH stack in the comments. Let's reclaim local computing sovereignty together!