# How a 3 kB npm package installs a 330 MB terminal app

> Source: <https://dev.to/masihmoafi/how-a-3-kb-npm-package-installs-a-330-mb-terminal-app-21a2>
> Published: 2026-11-12 06:07:13+00:00

Elpis is an agent harness for Linux, built on OpenAI's Codex. Until today it installed with a shell script. Now it also installs with npm:

```
npm install -g elpis-cli
elpis
```

This post explains one decision: the npm package holds no binary.

The Elpis terminal app is a Rust binary of about 330 MB, with a code-mode host and a sandbox helper beside it. There are two common ways to put such a program on npm.

The first way puts the binary in the package, one package for each platform, and lets npm choose. Codex and esbuild do this. It works without a network after the install, but every release uploads hundreds of megabytes to npm for each platform.

The second way publishes a launcher. The launcher is a small script that downloads the binary when it first runs. I chose this one. Elpis already publishes its binaries on a GitHub release with a SHA-256 file beside each of them, and the install script already reads them from there. The npm package now uses the same three files, so there is one place where a release lives.

A launcher has two costs. The first run needs a network, and you must trust what it downloads.

For trust, the launcher checks each file against the SHA-256 published beside it. A file that does not match is deleted and is never run. The launcher downloads each file beside its final place and renames it only after the check. A stopped download cannot leave a half file that runs later.

For the network, the launcher uses curl when curl is present. curl follows your proxy settings, and a cut connection carries on from where it stopped. I added that after my own first try: the connection was cut at 32 MB of the largest file. The next run finished the same file.

Three tests run on every push against a stand-in release server. A first run downloads the files, checks them, runs the app, and passes its arguments and exit status through. A second run downloads nothing. A file with a wrong checksum is refused.

I also packed the package, installed the packed file into an empty folder, and ran it against the real release. It downloaded 0.5.1 and printed `elpis 0.5.1`.

The package runs on Linux x86_64 only, because Elpis publishes a binary for that platform only. It installs the terminal app; the desktop app still installs with the script in the README. Elpis is alpha.

The code is in `packaging/npm` of [https://github.com/MasihMoafi/Elpis](https://github.com/MasihMoafi/Elpis).
