Nexus OS Docs

Appearance

Network Membrane ​

Operational

The Network Membrane is the userland network stack. It runs the grafted LwIP (Lightweight IP) stack inside a sandboxed fiber, providing TCP/IP connectivity to applications through a POSIX-compatible shim.

What Is the Membrane? ​

The Membrane (libnexus.a) is a compatibility adapter — a "biosuit" that wraps POSIX system calls and routes them through Nexus's sovereign abstractions. For networking, this means:

  • socket() creates a Membrane-managed endpoint
  • connect() sends a connection request through the LwIP stack
  • send()/recv() transfer data through ION Rings
  • bind()/listen()/accept() work as expected

Applications compiled against POSIX (curl, wget, ssh) work through the Membrane without modification. They never touch the kernel's network code directly.

Architecture ​

┌─────────────────────────┐
│  Application Process    │
│  (calls socket/send)    │
├─────────────────────────┤
│  Membrane POSIX Shim    │  libnexus.a
│  (translates to ION)    │
├─────────────────────────┤
│  LwIP TCP/IP Stack      │  Grafted, runs as fiber
│  (DHCP, TCP, UDP, ICMP) │
├─────────────────────────┤
│  ION Ring (proc_rx/tx)  │  Zero-copy to kernel
├─────────────────────────┤
│  NetSwitch (Kernel)     │  L2 demux
└─────────────────────────┘

LwIP — The Grafted Stack ​

LwIP is an open-source lightweight TCP/IP stack designed for embedded systems. Nexus grafts it by:

  1. Stripping all OS-specific code (no pthreads, no file I/O)
  2. Replacing the platform layer with ION Ring integration
  3. Running it as a Rumpk fiber with restricted capabilities
  4. Applying pledge constraints (INET only — no filesystem access, no process spawning)

The result is a TCP/IP stack that provides full connectivity but cannot escape its sandbox.

DHCP and Network Configuration ​

The Membrane fiber runs DHCP client logic at boot:

  1. NetSwitch routes incoming DHCP responses to the Membrane fiber's ION Ring
  2. LwIP processes the DHCP offer and configures the interface
  3. The assigned IP address is registered in /Bus/net/
  4. Applications can now connect to the network

Why Not a Kernel Network Stack? ​

Three reasons:

  1. Crash isolation: A bug in TCP processing kills only the Membrane fiber. The kernel restarts it. Applications reconnect.

  2. Attack surface reduction: The kernel's trusted computing base does not include a TCP/IP stack. You cannot exploit a buffer overflow in packet parsing to gain kernel privileges.

  3. Replaceability: The Membrane is a service, not a kernel feature. You can swap LwIP for a different stack, run multiple stacks simultaneously, or remove networking entirely — without recompiling the kernel.

Chimera POSIX Bridge ​

For full POSIX compatibility, the Membrane includes the Chimera bridge (SPEC-073) — a more complete adaptation layer that handles edge cases:

  • Non-blocking I/O (O_NONBLOCK)
  • Socket options (setsockopt)
  • Signal-driven I/O (SIGIO)
  • Unix domain sockets (mapped to local ION Rings)

This bridge makes it possible to graft complex network applications (nginx, PostgreSQL, Node.js) with minimal or no source modifications.