AELDER · 17 Nov
How-to · 3 min read
How to ship a JavaScript AI agent as one executable
You wrote a small AI agent or MCP server in TypeScript, it works on your laptop, and now you need to hand it to a teammate, a customer or a Raspberry Pi. On your machine it leans on Node, a big node_modules folder and maybe a vector database running in the background. Asking someone else to install all of that just to try your tool feels like too much. You want one file they can download and run.
- Published
- 17 Nov 2026
- Delivery
- No. 12
- Topic
- AI and agents
- Evidence
- 9 claims quoted from sofuu.xyz
01
Why it's hard
The usual JavaScript packagers can wrap a script, but they ship a whole JavaScript runtime with it, and anything that needs a separate daemon, like a model server or a vector store, still has to be installed next to it. Python tools have the same problem with even bigger bundles. Each extra process is one more thing to start, configure and debug on a machine you do not control. So a ten line agent ends up with a setup guide longer than the code. And every extra install step is a place where the person you sent it to gives up.
This part describes the usual way. It makes no claims about Sofuu, so nothing is quoted here.
02
How Sofuu does it
Sofuu is a native runtime for AI apps and agents built on Rust, QuickJS and libuv, and it ships a built-in compiler. Running sofuu compile turns a supported TypeScript or JavaScript program into a single native executable, with the QuickJS bytecode and an optional .qtsq vector memory file bundled inside. Because vector memory, MCP and the agent loop live in the runtime itself, the compiled file does not need a separate database or daemon for those parts. The compiler guide covers micro and lean profiles for agents and MCP servers.
Turn any TypeScript/JavaScript agent into a single, self-contained native executable.Quoted from sofuu.xyz
Compile agents and MCP servers into single-file binaries with micro and lean profiles.Quoted from sofuu.xyz
sofuu compile packages supported programs into single native executables. OS libraries and selected model or service dependencies may still be needed.Quoted from sofuu.xyz
03
Step by step
- 1Install Sofuu with the one line install script or through npm.
- 2Run sofuu doctor to confirm the install and the vector memory linkage.
- 3Test your agent with sofuu run on your own machine until it behaves the way you expect.
- 4Compile it with sofuu compile, giving the output file a name.
- 5Copy the single executable to the target machine and run it there.
- 6Check whether that machine still needs OS libraries, model files or a remote provider.
04
Tips
Build for the platforms that have official binaries. Today those are macOS on Apple Silicon and Linux on x86_64 and arm64, so plan another route if your users are on Windows. Each release binary comes with a SHA-256 checksum you can verify.
No Windows CI today: macOS arm64 and Linux x86_64 / arm64 are the supported binary targetsQuoted from sofuu.xyz
Check your dependencies before you commit. Sofuu has shims for common Node and web APIs, but npm coverage is partial and there are no N-API native addons or worker threads, so an agent that leans on sharp or better-sqlite3 will not compile as is.
No V8 parity: no N-API, no worker_threads, no WebSocket client, partial npm coverage, and slower long-running pure JavaScript.Quoted from sofuu.xyz
Decide where the model lives. A compiled agent can carry its memory and tools, but model-backed features still need a supported local model and backend or a remote provider, and remote providers need network access. The built-in inference engine is marked experimental, and the docs point production work to the llamacpp provider.
Model-backed agents need a supported local model and backend or a remote provider; remote services require network access.Quoted from sofuu.xyz
Remember it is beta software. Run the compiled file on a clean machine before you send it to anyone, and report anything odd to the team. Some features and runtime behaviours may not work the same in every environment yet.
Sofuu is currently in beta (v0.3.0-beta) and actively evolving.Quoted from sofuu.xyz
05
Questions
Can I compile an MCP server as well as an agent?
Yes. The compiler guide covers both agents and MCP servers, built into single file binaries.
Compile agents and MCP servers into single-file binaries with micro and lean profiles.Quoted from sofuu.xyz
Is the vector memory inside the compiled file encrypted?
Yes, by default. Local vector memory is encrypted unless you choose the explicit plaintext mode.
Local vector memory encrypted by default, with an explicit plaintext mode.Quoted from sofuu.xyz
Can I run it inside a phone app?
Yes, through the embed SDK. iOS and Android apps embed the runtime via libsofuu, and an Android APK is also published.
Embed SDK for iOS & Android.Quoted from sofuu.xyz
More on AI and agents
Sofuu has one answer so far, so these come from its topic
OkAiHub · 17 Nov
How to get a new AI tool seen by early adopters
Semlith · 17 Nov