DEV Community: 木头人

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!

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

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

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!