Introduction

Buntime is a modular runtime for Bun with an isolated worker pool, a plugin system (core + external), and a micro-frontend shell. It covers a whole monorepo of moving parts — apps/, plugins/, packages/, and Helm charts/ — but the idea at the center is small.

The one-sentence model

A single Bun process accepts every request and decides where it goes, but it never executes your application code. Your code runs in isolated workers; cross-cutting concerns run in plugins.

That separation is the whole point. The main thread stays a thin, resilient orchestrator. Application code — which may crash, leak memory, or hang — is quarantined in workers that can be recycled without touching the runtime.

What problem does it solve?

Running many small apps on one box usually forces a choice: give every app its own process (heavy, slow to start, wasteful) or run them in one shared process (one bad app takes down the rest). Buntime takes a third path built on Bun’s fast Worker isolates:

Density without coupling

Many apps share one runtime, yet each runs in an isolated worker with its own heap and modules. No shared global state, no cross-app leaks.

Two execution profiles

A worker can be persistent (kept warm, reused across requests — ideal for DB connections or SSE) or ephemeral (ttl: 0, spun up per request and discarded — serverless-style, pay only when called).

Extend without forking

Auth, rate limiting, storage, proxying, logging, metrics — all live in plugins loaded from a directory. Add capabilities without modifying the core.

UIs as micro-frontends

Any app or plugin that ships an index.html becomes an iframe in a shared shell, regardless of the framework it was built with.

The pieces

Piece	What it is
Runtime	The Bun + Hono main process: startup, request pipeline, multi-layer routing, graceful shutdown.
Worker pool	An LRU cache of Bun workers with lifecycle, sliding TTL, ephemeral concurrency limits, and metrics.
Plugin system	Auto-discovery, persistent vs serverless modes, a manifest schema, lifecycle hooks, and a service registry.
Micro-frontend	The shell that hosts apps and plugin UIs as iframes via @zomme/frame.
Packages	@buntime/shared (types, errors, utilities — published to JSR) and @buntime/keyval.
Platform	A reference multi-tenant SaaS built on the runtime.

How a request flows

Request
  → CSRF check (/api/* only)
  → onRequest hooks       (auth, rate limit, metrics — may short-circuit)
  → runtime API           (/api/* or /_/api/*)
  → plugin.server.fetch    (direct plugin handlers)
  → plugin.routes          (Hono apps mounted at the plugin base)
  → plugin apps            (worker pool — z-frame iframes)
  → worker apps            (/:app/* resolved from worker dirs)
  → homepage fallback / 404
  → onResponse hooks
Response

More specific routes (plugins) always win over generic ones (workers). The full priority table lives in Runtime → Routing.

Scope

Buntime is purely technical infrastructure — there are no built-in business rules. Products that run on the runtime define their own domain logic in their own workers and plugins.

Where to next

• New here? Start with the philosophy to understand the design principles, then get started.
• Building an app to run on Buntime? Read the worker pool.
• Extending the runtime? Read writing a plugin.