# Install

> One line for Linux, macOS and Windows. What it prints, what it needs, where files land, and the mistakes people make.

Source: https://nodecode.ai/docs/install
Updated: 2026-10-07

## One line

**Linux:**

Linux x86_64. glibc 2.38 or newer.

**macOS:**

Apple Silicon, macOS 15 or newer, with Homebrew `openssl@3` and `zstd`.

**Windows:**

Windows x86_64, in PowerShell.

**Linux, macOS:**

```sh
curl -fsSL https://nodecode.ai/install.sh | sh
```

It asks the channel which release is current, downloads it, checks its sha256, lays it out beside any older version, points `current` at it, links the command and runs it once.

**Windows:**

```powershell
irm https://nodecode.ai/install.ps1 | iex
```

It downloads the release, checks its sha256, unpacks it beside any older version, puts it on your user PATH and runs it once.

**Linux:**

```text
nodecode: reading https://preview.nodecode.ai/dl/stable-x86_64-linux
nodecode: release 8490b4803
nodecode: downloading https://preview.nodecode.ai/dl/nodecode-8490b4803-x86_64-linux.tar.gz
nodecode: sha256 verified
nodecode: laid out 8490b4803 at /home/you/.local/share/nodecode/8490b4803
nodecode: current is 8490b4803
nodecode: linked /home/you/.local/bin/nodecode
nodecode: the executable runs
nodecode: open a new shell, then run 'nodecode' to start; the first launch opens the setup wizard
```

**macOS:**

```text
nodecode: reading https://preview.nodecode.ai/dl/stable-arm64-darwin
nodecode: release dc14c36f5
nodecode: downloading https://preview.nodecode.ai/dl/nodecode-dc14c36f5-arm64-darwin.tar.gz
nodecode: sha256 verified
nodecode: laid out dc14c36f5 at /Users/you/.local/share/nodecode/dc14c36f5
nodecode: current is dc14c36f5
nodecode: linked /Users/you/.local/bin/nodecode
nodecode: the executable runs
nodecode: add /Users/you/.local/bin to your PATH:
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> /Users/you/.zprofile
then open a new shell and run 'nodecode' to start; the first launch opens the setup wizard
```

**Windows:**

```text
nodecode: downloading https://preview.nodecode.ai/dl/nodecode-8490b4803-x86_64-windows.zip
nodecode: sha256 verified
nodecode: installed 8490b4803 at C:\Users\you\AppData\Local\Programs\nodecode\8490b4803
nodecode: added C:\Users\you\AppData\Local\Programs\nodecode\current to your user PATH; open a new terminal to pick it up
nodecode: the executable runs
```

Open a new (Linux, macOS: shell) (Windows: terminal). Then:

```sh
nodecode --version
```

**Linux, Windows:**

```text
nodecode 0.0.1+8490b4803
```

**macOS:**

```text
nodecode 0.0.1+dc14c36f5
```

Run `nodecode` to start. Next: [Quickstart](https://nodecode.ai/docs/quickstart).

Mistakes to avoid:

- (Linux, macOS) Passing a flag straight to `sh`. `sh` takes it as its own option and stops: `sh: 0: Illegal option --`. Nothing installs. Instead: Hand it to the installer: `curl -fsSL https://nodecode.ai/install.sh | sh -s -- --no-modify-path`
- (Linux, macOS) Setting a variable in front of `curl`. It reaches `curl`, not the installer. The run still reads the channel. Instead: Put it in front of `sh`: `curl -fsSL https://nodecode.ai/install.sh | NODECODE_VERSION=8490b4803 sh`
- (Linux) Running it with `sudo`. It installs into root's home, `/root/.local/share/nodecode`. Your own shell says `nodecode: command not found`. Instead: Run it as yourself. It needs no root.
- (Linux, macOS) Installing again after `nodecode: command not found`. The shell you installed from keeps the PATH it started with. A second install changes nothing. Instead: Open a new shell. If the run ended with `add … to your PATH`, run the `echo` line it printed first.
- (Windows) Pasting the line into Command Prompt. `irm` and `iex` are PowerShell. cmd answers `'irm' is not recognized as an internal or external command`. Instead: Open PowerShell and paste it there.
- (Windows) Running `nodecode` in a terminal opened before the install. The installer adds it to your user PATH. A terminal that was already open keeps the old one. Instead: Open a new terminal.

## Requirements

**Linux:**

| Needs | Without it | It prints |
| --- | --- | --- |
| x86_64 | Stops | `no Linux build for aarch64 yet` |
| glibc 2.38 or newer | Stops | `glibc 2.35 is too old` |
| `curl` or `wget` | Stops | `need curl or wget to download` |
| `tar` | Stops | `need tar to unpack` |
| `libsqlite3.so.0`, `libssl.so.3`, `libcrypto.so.3` | Warns | `WARNING: not found: libsqlite3.so.0` |
| A CA bundle | Warns | `WARNING: no CA bundle found` |
| `git` | Warns | `WARNING: git is not installed` |

**macOS:**

| Needs | Without it | It prints |
| --- | --- | --- |
| Apple Silicon | Stops | `no macOS build for Intel yet` |
| macOS 15 or newer | Stops | `nodecode needs 15 (Sequoia) or newer` |
| Homebrew `openssl@3` and `zstd` | Stops | `nodecode needs Homebrew's openssl@3 zstd` |
| `curl` or `wget`, and `tar` | Stops | `need curl or wget to download` |
| A CA bundle at `/opt/homebrew/etc/openssl@3/cert.pem` | Warns | `WARNING: no CA bundle at …` |
| `git` | Warns | `WARNING: git is not installed` |

**Windows:**

| Needs | Without it | It prints |
| --- | --- | --- |
| 64-bit Windows | Stops | `nodecode needs 64-bit Windows` |
| An AMD64 processor | Stops | `nodecode ships for x86-64 Windows only today` |
| Git for Windows | Warns | `git is not on PATH` |

No flag changes a stop. A warning lets the install go on.

Mistakes to avoid:

- (Linux) Hunting for a flag past `glibc 2.35 is too old`. Ubuntu 22.04 and Debian 12 fail. No flag changes this. Instead: Move to Ubuntu 24.04+, Debian 13+, Fedora 39+ or Arch.
- (Linux) Going on past `WARNING: not found: libsqlite3.so.0`. The install links the new build, then the build fails its own check: `the executable did not answer`. `nodecode` now points at a build that cannot start. Instead: Install sqlite3 and OpenSSL 3 (`sudo apt install libsqlite3-0` on Ubuntu), then run the installer again.
- (Linux) Going on past `WARNING: no CA bundle found`. Setup's provider list comes up empty. No error shows. Instead: Install `ca-certificates`, then run `nodecode` again.
- (macOS) Installing `openssl@3` alone. The build also opens Homebrew's `zstd` at every start. Without it, it does not answer at all. Instead: `brew install openssl@3 zstd`, then run the installer again.
- (macOS) Going on past `WARNING: no CA bundle at …`. Setup's provider list comes up empty. No error shows. Instead: `brew reinstall ca-certificates`.
- (Windows) Skipping Git for Windows. Shell commands run through its `sh.exe`. Without it they fail with `git is not on PATH`. Instead: `winget install --id Git.Git -e --source winget`, then open a new terminal.
- (Linux, macOS) Going on past the git warning. Nodecode runs, but the layer, memory and checkpoint history are not committed. Instead: Install git. (macOS: `xcode-select --install` puts it on a Mac.)

## Where files land

**Linux:**

`~/`
- `.local/share/nodecode/`
  The versions.
  - `8490b4803/`: The executable and `src/`. They stay together.
  - `current`: A symlink to `8490b4803/`, the version in use.
  - `base-url`: The release host. Written only when `NODECODE_BASE_URL` was set at install.
- `.local/bin/nodecode`: A symlink to `current/nodecode`.
- `.nodecode/`: Your home: sessions, cells, keys. An install never touches it.

**macOS:**

`~/`
- `.local/share/nodecode/`
  The versions.
  - `dc14c36f5/`: The executable and `src/`. They stay together.
  - `current`: A symlink to `dc14c36f5/`, the version in use.
  - `base-url`: The release host. Written only when `NODECODE_BASE_URL` was set at install.
- `.local/bin/nodecode`: A symlink to `current/nodecode`.
- `.nodecode/`: Your home: sessions, cells, keys. An install never touches it.

**Windows:**

`%LOCALAPPDATA%\Programs\nodecode\`
- `8490b4803\`: The executable, its DLLs and `src\`.
- `current`: A junction to `8490b4803\`, the version in use. Your user PATH holds `current`.
- `base-url`: The release host. Written only when `NODECODE_BASE_URL` was set at install.

Your data lives in the home, (Linux, macOS: `~/.nodecode/`) (Windows: `%USERPROFILE%\.nodecode\`). See [Files](https://nodecode.ai/docs/files).

Mistakes to avoid:

- (Linux, macOS) Waiting for the installer to edit your profile. It never writes to (Linux: `~/.profile`) (macOS: `~/.zprofile`). It prints the line to add and stops there. Instead: Run the `echo` line it printed, then open a new shell.
- (Linux, macOS) Keeping an older `nodecode` first on PATH. You keep running the old build. The installer warns: `'nodecode' on your PATH is NOT the build just installed`. Instead: Remove the other one, or put `~/.local/bin` ahead of it in PATH.
- (Linux, macOS) Copying the executable somewhere else. It reads its own `src/` beside it. The two stay together. Instead: Link it instead, as the installer does: `ln -s ~/.local/share/nodecode/current/nodecode ~/bin/nodecode`
- (Linux, macOS) Exporting `NODECODE_HOME` for Nodecode, then installing. `install.sh` reads the same name as its install folder. The versions land inside your home. Instead: Leave it out of the install line: `curl -fsSL https://nodecode.ai/install.sh | env -u NODECODE_HOME sh`
- (Windows) Deleting an old version folder while Nodecode runs. A running Nodecode runs from the folder it started in. Instead: Close it first. `current` already points at the new one.

## Flags and variables

**Linux, macOS:**

Flags go after `sh -s --`. Variables go in front of `sh`, not `curl`.

```sh
curl -fsSL https://nodecode.ai/install.sh | NODECODE_CHANNEL=stable sh -s -- --stage
```

| Flag | Does |
| --- | --- |
| `--no-modify-path` | No link in `~/.local/bin`. It prints the path to run. |
| `--stage` | Lays the version out and probes it. `current` stays. Nothing restarts. |
| `--link` | Points `current` at a version laid out earlier. No download. Needs `NODECODE_VERSION`. |
| `-h`, `--help` | Prints help. |

**Windows:**

With `irm … | iex`, set variables first. Parameters only reach the script when it runs as a file.

```powershell
$env:NODECODE_VERSION = '8490b4803'; irm https://nodecode.ai/install.ps1 | iex
```

| Parameter | Does |
| --- | --- |
| `-Version LABEL` | Installs that release. |
| `-FromZip PATH` | Installs a local release zip. No download. |
| `-NoModifyPath` | Leaves the user PATH alone. It prints the folder to add. |

| Variable | Default | Does |
| --- | --- | --- |
| `NODECODE_VERSION` | the channel's release | Installs this version. |
| `NODECODE_CHANNEL` | `stable` | Names the channel pointer to read. |
| `NODECODE_BASE_URL` | `https://preview.nodecode.ai/dl` | Fetches from this host. Later updates read the same host. |
| `NODECODE_STAGE` | `full` | `full`, `stage` or `link`. Same as `--stage` and `--link`. |
| `NODECODE_HOME` | `~/.local/share/nodecode` | Install folder, for `install.sh`. |
| `NODECODE_INSTALL_DIR` | `%LOCALAPPDATA%\Programs\nodecode` | Install folder, for `install.ps1`. |
| `NODECODE_NO_MODIFY_PATH` | unset | Same as `-NoModifyPath`, for `install.ps1`. |

Mistakes to avoid:

- (Linux, macOS) Using `--link` without a version. It stops: `--link needs the version to point at: set NODECODE_VERSION`. Instead: `curl -fsSL https://nodecode.ai/install.sh | NODECODE_VERSION=8490b4803 sh -s -- --link`
- (Linux, macOS) Adding a flag from another installer. Anything else exits with code 2: `install.sh: unknown argument --yes`. Instead: The flags are `--no-modify-path`, `--stage`, `--link` and `-h`.
- (Windows) Adding `-Version` after `iex`. `iex` runs the script but takes no parameters for it. PowerShell refuses the line. Instead: Set the variable first, as above.

## Upgrade

```sh
nodecode update
```

Installed builds also update themselves by default. A gateway running in the background moves to the new build. See [Updates](https://nodecode.ai/docs/updates).

## From source

Needs SBCL and `just`.

```sh
just build      # compile the system
just test       # run the core suite
just release    # dump ./nodecode
./nodecode
```

`just check` runs lint, build and test.

Mistakes to avoid:

- Waiting for a source build to update itself. Automatic updates are off in a source build. Instead: Pull and run `just release` again. Or install a release with the line at the top.