Installing jcode on nix/NixOS: A Practical Unofficial Guide
jcode is an open-source AI coding agent<br>that runs as a local server and drives your editor. It's distributed as a<br>single self-contained executable, which sounds simple, until you try to run it<br>in a pure Nix environment: no system package manager, no Nix channels, no<br>/usr/bin/env. This post walks through installing the official Nix build from<br>GitHub releases, the surprising gotchas you will hit, and how to fix them.<br>the beauty of jcode harness is that it can spawn an AI agents army with very little RAM overheadWhat you need<br>A machine where the Nix store is present and mounted: a bwrap-nix sandbox,<br>NixOS, or any host with nix installed. The jcode binary is dynamically<br>linked against the glibc shipped in the store, so the store must be there at<br>runtime.<br>curl and sha256sum for downloading and verifying the release.<br>A writable ~/.local/bin (or any directory on your PATH).<br>Step 1: Find the release<br>jcode publishes Nix builds as GitHub releases tagged nix-vX.Y.Z, for example<br>nix-v0.66.0. Each release carries one asset per platform:<br>jcode-nix-linux-x86_64<br>The release page shows the exact sha256 digest for every asset, so you can<br>verify your download:<br>curl -s https://api.github.com/repos/grigio/jcode/releases/tags/nix-v0.66.0 \<br>| jq -r '.assets[] | .name + " " + .digest'<br>Step 2: Download and verify<br>mkdir -p ~/jcode-install && cd ~/jcode-install<br>curl -sSL -o jcode-nix-linux-x86_64 \<br>https://github.com/grigio/jcode/releases/download/nix-v0.66.0/jcode-nix-linux-x86_64<br>sha256sum jcode-nix-linux-x86_64<br>Compare the output against the digest published on the release page. For<br>v0.66.0 it is:<br>2faea9dc9f560e6f9a73da360d57b3c1d32f4ccfa90bbea2352237ba43472bb3 jcode-nix-linux-x86_64<br>A checksum mismatch means a corrupted download or a tampered asset. Stop and<br>re-download.<br>Step 3: Confirm it is a real executable<br>The Nix build is a genuine ELF binary, not a script. file should show a<br>dynamically linked PIE with a Nix store interpreter:<br>file jcode-nix-linux-x86_64<br># ELF 64-bit LSB pie executable, x86-64, dynamically linked,<br># interpreter /nix/store/-glibc-/lib/ld-linux-x86-64.so.2<br>Then check the version:<br>chmod +x jcode-nix-linux-x86_64<br>./jcode-nix-linux-x86_64 --version<br># jcode v0.66.0 (nix-build)<br>Step 4: Install<br>Put the binary on your PATH:<br>mkdir -p ~/.local/bin<br>cp jcode-nix-linux-x86_64 ~/.local/bin/jcode<br>chmod +x ~/.local/bin/jcode<br>~/.local/bin/jcode --version<br>Replacing a running jcode: "Text file busy"<br>If you are upgrading and a jcode server is currently running from that path, a<br>plain cp fails with Text file busy. Linux refuses to truncate an executable<br>that is mapped by a live process. Copy to a temporary name and atomically<br>rename it instead:<br>cp jcode-nix-linux-x86_64 ~/.local/bin/jcode.new<br>chmod +x ~/.local/bin/jcode.new<br>mv -f ~/.local/bin/jcode.new ~/.local/bin/jcode<br>The old server keeps running from its in-memory image; the new version is used<br>by the next server start.<br>Step 5: Understand jcode's layout<br>jcode manages its own builds under ~/.jcode/builds/:<br>~/.jcode/builds/<br>shared-server/jcode # what the server actually launches<br>stable/jcode # the stable build<br>versions// # per-version builds from self-update<br>shared-server-version # version marker<br>stable-version # version marker<br>After a manual Nix install, point the shared-server and stable symlinks at<br>the real ELF in ~/.local/bin/jcode:<br>ln -sfn "$HOME/.local/bin/jcode" "$HOME/.jcode/builds/shared-server/jcode"<br>ln -sfn "$HOME/.local/bin/jcode" "$HOME/.jcode/builds/stable/jcode"<br>and keep the version markers in sync:<br>echo 0.66.0 > ~/.jcode/builds/shared-server-version<br>echo 0.66.0 > ~/.jcode/builds/stable-version<br>The Nix gotcha: self-update breaks the sandbox<br>jcode self-updates by downloading a new build into<br>~/.jcode/builds/versions//jcode and pointing shared-server/jcode<br>at it. That downloaded file is not the binary. It is a wrapper shell script<br>whose first line is:<br>#!/usr/bin/env sh<br>In a Nix-only environment /usr/bin/env does not exist (the env binary lives<br>in the store under coreutils), so execve(2) fails with ENOENT and the<br>server never starts. Verified with strace:<br>execve(".../.jcode/builds/shared-server/jcode",<br>["...", "--provider", "auto", "serve"], ...) = -1 ENOENT<br>Two equivalent fixes. Do one of them.<br>Option A (recommended): point shared-server at the real binary<br>ln -sfn "$HOME/.local/bin/jcode" "$HOME/.jcode/builds/shared-server/jcode"<br>No wrapper, no interpreter, no breakage. This also pins the server to the<br>binary you installed instead of an untested self-update.<br>Option B: provide /usr/bin/env<br>Give the shebang what it wants by symlinking the store env into /usr/bin<br>(only possible when /usr/bin is writable):<br>ln -sf "$(dirname "$(readlink -f "$HOME/.local/bin/env")")/env" /usr/bin/env<br># e.g. /nix/store/-coreutils-9.10/bin/env<br>Run the server<br>~/.jcode/builds/shared-server/jcode --provider auto serve<br>or directly:<br>~/.local/bin/jcode --provider auto serve<br>Notes:<br>Only one server instance may run per runtime dir. A...