binpod

Standalone binary packager for Node.js using the official SEA (Self-Extracting Archive) system. Zero dependencies. Cross-host Linux builds. Predictable, future-proof output.

Overview

binpod creates compact, executable binaries from JavaScript/TypeScript projects using the built-in Node.js SEA system. Unlike tools such as pkg or nexe, binpod does not patch Node, embed a virtual filesystem, or rely on custom loaders. Output binaries are normal Node runtimes with a SEA blob injected according to the stable public mechanism maintained by the Node.js project.

binpod automatically:

• downloads the correct Node release for the requested target
• bundles your project via esbuild
• generates a SEA blob
• injects it into the proper Node runtime
• outputs a final standalone executable

Linux binaries can be produced from any host OS, including macOS. macOS binaries must be produced on macOS due to codesign requirements.

Installation

npm install -g binpod

Requires Node 18+ (SEA introduced in Node 20; binpod downloads its own runtimes).

Usage

binpod <entry.js> [options]

Example

binpod index.js

Produces:

./build

A runnable Linux executable by default.

Options

-t, --target <linux|macos> Sets the build target operating system. If not specified, the target defaults to linux.

-r, --release <N> Selects the Node.js major release to bundle (for example 20 or 22). If omitted, the default release is 22.

Example: Build macOS binary

binpod app.js --target macos

Example: Build Linux binary from macOS

binpod server.js --target linux

Example: Specify Node release

binpod api.js --release 20

What binpod does

1. Bundles your project with esbuild into a single CJS file (build.js).

2. Generates an SEA config (build.json).

3. Downloads the correct Node runtime for the target:

   • Linux (x64)
   • macOS (x64)

4. Runs:

   node --experimental-sea-config build.json

   Producing build.blob.

5. Injects the blob into the downloaded Node binary using postject.

6. Strips signatures on macOS and resigns the final binary.

7. Produces final executable build.

System Requirements

Linux

No special tools required. curl and tar are used automatically.

macOS

Required:

• Xcode command-line tools (xcode-select --install)
• codesign available in system (included with macOS)

macOS can produce:

• Linux binaries
• macOS binaries

Linux can produce:

• Linux binaries only (cannot run codesign)

Use Cases

1. Standalone CLI tools

binpod produces a single binary that runs without Node installed.

2. Portable microservices

Bundle Node + your service into one file. Deploy on any Linux system without dependencies.

3. Distribution in containers

Ideal for scratch or distroless images:

FROM scratch
COPY build /usr/bin/app

4. Embedding Node logic inside system installers or native apps

SEA is deterministic and safe for low-level distribution.

How binpod differs from pkg and nexe

pkg

• Embeds V8 snapshots and a virtual filesystem.
• Patches Node internals.
• Sensitive to version changes.
• Heavier startup overhead.
• Breaks on Node updates frequently.

nexe

• Compiles a custom Node binary from source.
• Slow builds.
• Requires full toolchain (Python, C++, Ninja).
• Highly sensitive to OS differences.

binpod

• Uses official Node binaries (no patching).
• Uses SEA (first-class mechanism in Node).
• Produces binaries identical to running node <file> except self-contained.
• Cross-host Linux builds.
• No reliance on deprecated or unstable internals.

binpod focuses on:

• stability
• minimalism
• future-proof behavior
• reproducible results

Limitations

1. SEA entry must be CommonJS

The SEA environment does not currently support ESM directly. binpod uses esbuild to guarantee a single CJS output.

2. Dynamic filesystem resolution requires care

Since everything is bundled, dynamic require() using non-static paths will not resolve.

3. macOS binaries must be built on macOS

macOS signing cannot be performed on Linux.

4. Only x64 binaries are produced currently

SEA works with x64 Node binaries; ARM support depends on future SEA extensions and Node releases.

5. No .node native extensions

SEA cannot load native add-ons unless manually distributed externally.

Performance

• Startup identical to normal Node (no pkg overhead)
• Execution performance identical to Node
• Binary size: Node runtime (~40–60MB) + SEA blob

No virtualization layer, no snapshot loader.

Why binpod is future-proof

• Relies only on public, stable Node SEA mechanisms
• No patched runtimes
• No deprecated snapshots
• No forked V8 behavior
• Maintained alignment with official Node releases

Directory Structure Produced

build.js        → bundled entry file
build.json      → SEA config
build.blob      → SEA data
build           → final binary

License

ISC

Acknowledgements

Created by Tekki AS