Wrangler-compatible · Rust + gnosis-uring · local-first

x-ranger

The local Wrangler-compatible substrate for the Forkjoin/Aeon worker stack.

A Wrangler-shaped CLI and programmatic API for running and testing local workers — Rust + gnosis-uring ingress, a polyglot fetch handler that answers over HTTP, TCP Aeon Flow, and UDP Aeon Flow, and a formally-verified port-authenticated mesh policy backed by ten zero-sorry Lean modules.

$ pnpm add @a0n/x-ranger

Get started Browse the source

wrangler compatible runtime rust + gnosis-uring transports HTTP + TCP + UDP mesh 10 zero-sorry Lean modules license MPL-2.0

Features

Everything you need. Nothing you don't own.

Wrangler-shaped CLI

init, dev, secret, versions, deploy, browser, whoami — the local worker lifecycle and state commands you expect, plus a wrangler bin alias so it drops into toolchains that expect the command name. Cloudflare-account families it does not yet own stay honest explicit placeholders.

Programmatic dev API

unstable_dev(), unstable_startWorker(), and getPlatformProxy() for local worker testing. x-ranger imports the worker module and calls fetch(request, env, ctx) directly — no isolate, no sandbox, no runtime emulation.

Multi-lane transport

One worker fetch handler, three transports. The same fetch export answers over HTTP (always on), TCP Aeon Flow, and UDP Aeon Flow — all sharing one mesh policy, one platform proxy, and one execution context. The wire envelope is pure JSON over base64, dependency-free.

Formally-verified mesh policy

A per-path port-authenticated mesh: default-deny transitions, an explicit port whitelist, ICE overlays, honey-pit traps, and linked-mesh composition — backed by ten zero-sorry Lean modules and a TypeScript SSOT in @a0n/gnosis/mesh-policy.

Local binding emulation

Local worker loading and fetch simulation with binding emulation for vars, KV, R2, D1, and service bindings — plus local d1 execute and d1 migrations create/list/apply backed by persisted D1 files, secret/version/deployment state, and rollback history.

Rust + gnosis-uring ingress

Built in Rust to minimize CLI overhead, with gnosis-uring fronting the local runtime for the fast ingress path. Native execution keeps local developer workflows and automated toolchains fast as the monorepo grows.

Quickstart

Drive a local worker

# scaffold and run a local worker
x-ranger init
x-ranger dev --config wrangler.toml

# local state surfaces
x-ranger secret put API_KEY --value swordfish
x-ranger deploy --json

import { unstable_dev, getPlatformProxy } from '@a0n/x-ranger';

const worker = await unstable_dev('src/index.ts', {
  config: 'wrangler.toml',
});
const response = await worker.fetch();
console.log(await response.text());
await worker.stop();

# compile the policy to a deploy-invisible binary artifact
x-ranger mesh compile \
  --config wrangler.toml \
  --out src/generated/mesh-policy-loader.ts \
  --bw-out dist/mesh-policy.bw

# content-addressed fingerprint for idempotent deploys
x-ranger mesh fingerprint --json

Comparison

x-ranger vs. Wrangler dev

Capability

x-ranger

Wrangler

Local worker lifecycle (dev, secret, deploy)

✓

Runs the worker without a V8 isolate sandbox

✓

–

TCP + UDP transport lanes for fetch

✓

–

Formally-verified port-authenticated mesh policy

✓

–

Full workerd / Miniflare runtime parity

✓

Cloudflare-account-facing command families

✓

FAQ

Common questions

For local worker workflows, largely yes — it ships a Wrangler-shaped CLI and a wrangler bin alias, plus the unstable_dev / unstable_startWorker / getPlatformProxy programmatic APIs. It does not claim full workerd parity: Durable Object emulation is intentionally bounded and local, and Cloudflare-managed families such as queues, r2 account ops, vectorize, vpc, and workflows are surfaced as explicit placeholders until x-ranger has a real local contract for them.

Wrangler dev runs workers inside Miniflare / workerd — a full V8 isolate sandbox with Cloudflare runtime emulation. x-ranger just imports the worker module and calls fetch(request, env, ctx) directly: no isolate, no sandbox, no emulation. That is the honest path for local dev, CI, and edge-on-a-box.

Optional transports for the same worker fetch handler. Set XRANGER_FLOW_TCP_PORT or XRANGER_FLOW_UDP_PORT to bind them. Clients send a JSON tunnel envelope ({method, path, headers, body}); the runtime calls the worker's fetch and serializes the Response back. The lanes share the same mesh policy, platform proxy, and execution context as HTTP.

Ten zero-sorry Lean modules in gnosis (PortAuthenticatedMesh, AntiDomainOverlay, HoneyPit, LinkedMeshComposition, MeshPolicyCompileCorrectness, and more). The TypeScript runtime mirrors them, and each exported function carries a doc comment citing its theorem name. Compiled .bw bundles are deterministic and content-addressed via compileFingerprintIsContentAddressed.