Overview
Configure and operate Nexus local daemon and client IPC.
@nexus-js/node-ipc connects local daemon and client processes through filesystem Unix domain sockets. Use it when one long-lived local process exposes Nexus services and one or more local clients call those services.
This section covers the adapter-specific behavior. For authorization hooks shared by all adapters, read Authorization and policy.
Start Here
- New setup: Quick start
- Mental model: Concepts
- Socket path rules: Addressing
- Adapter pre-auth: Authentication
- Daemon restart and errors: Lifecycle and errors
- Node and Bun runtime notes: Runtime compatibility
- Test guidance: Testing
Package Routing
- Foundation runtime:
@nexus-js/core - Local IPC adapter:
@nexus-js/node-ipc
Install both in daemon and client packages:
pnpm add @nexus-js/core @nexus-js/node-ipcWhen To Use It
Use node-ipc when your application has:
- one local daemon process that owns services
- one or more local clients, such as CLIs or helper processes
- same-machine communication only
- a Unix socket path that can represent the daemon instance
Do not use it for browser contexts, cross-machine networking, or long-lived handles that must survive daemon restarts without being recreated.
What The Adapter Provides
- daemon and client factory helpers
- default socket address resolution
- custom address resolvers
- filesystem Unix socket server and client endpoints
- binary packet framing over socket streams
- optional shared-secret pre-auth
- runtime directory and stale socket safety checks
- node-ipc endpoint and connection metadata, exact targets, and address helpers
What Core Still Owns
The adapter does not replace core Nexus behavior.
Core still owns:
- tokens and service contracts
- service exposure
- proxy creation
- target resolution
- logical connection handshake
policy.canConnectandpolicy.canCall- resource reference lifecycle
- session-bound proxy semantics
Runtime Scope
The current verification boundary is Node on Linux and Unix-like systems using filesystem Unix domain sockets. Bun has no verified repository CI coverage; this documentation makes no support or non-support claim. See Runtime compatibility for the boundary.
Testing Boundary
Use @nexus-js/testing and createMockNexus() for unit tests of application code that consumes daemon services through a NexusInstance.
Do not use the mock to validate node-ipc adapter behavior. It does not exercise Unix socket addressing, filesystem permissions, packet framing, shared-secret pre-auth, stale socket cleanup, daemon close/recreate behavior, or real disconnect timing.
Use Testing for adapter and real socket integration testing guidance.
Transport Limits
Node IPC uses binary packets. Daemon and client helpers accept a transport
option for frame, message, and aggregate framework-buffer limits; defaults are
64 KiB, 16 MiB, and 64 MiB:
usingNodeIpcDaemon({
appId: "example-app",
transport: {
maxFrameBytes: 64 * 1024,
maxMessageBytes: 16 * 1024 * 1024,
maxBufferedBytes: 64 * 1024 * 1024,
},
});The configured frame limit cannot exceed the IPC framing packet limit.
Related Pages
- Product docs landing: Nexus Documentation
- Package map: Packages
- Platform selection: Platforms
- Testing application code: Testing
- Shared authorization policy: Authorization and policy