> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nerdit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install, upgrade, and remove Nerdit

> Install the signed Engine bundle and manage its service and data safely.

## Requirements

| Platform                      | Supported installation                                                              |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| Linux x86\_64 or arm64        | systemd; a glibc-based distribution compatible with Ubuntu 22.04 or newer.          |
| macOS Apple Silicon           | User installation; Docker Desktop, OrbStack, or another working Docker environment. |
| Windows                       | Run the Linux Engine and CLI inside WSL2 with systemd enabled.                      |
| Intel macOS or native Windows | No released binary artifact.                                                        |

Install and start Docker first. The Engine's service user must be able to access its socket. The installer checks Docker but does not install it.

```bash theme={null}
docker info
```

The installer also requires `curl`, `tar`, and `openssl`. Git deployment and the template store require `git` on the Engine machine. Released bundles contain the CLI, Engine, and pinned Caddy binary; **Python is not required**.

GPUs are optional. CPU applications, databases, external AI bindings, and CPU Ollama serving work without one. NVIDIA inference requires a working driver and NVIDIA Container Toolkit on Linux or WSL2. macOS containers do not receive NVIDIA GPU access. AMD support is experimental and opt-in.

## Install

<Tabs>
  <Tab title="Linux system">
    ```bash theme={null}
    curl -fsSL https://get.nerdit.ai | sudo sh
    ```

    The installer uses `/opt/nerdit`, registers `nerdit.service`, and runs the Engine as the user who invoked `sudo`. Run subsequent CLI commands as that user.
  </Tab>

  <Tab title="Linux user">
    ```bash theme={null}
    curl -fsSL https://get.nerdit.ai | NERDIT_INSTALL_MODE=user sh
    ```

    This uses a systemd user service and installs under `~/.nerdit`. To keep it running after logout, follow the installer's `loginctl enable-linger` instruction for the service user's account. Low network ports need additional configuration; see [HTTPS](/engine/networking).
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    curl -fsSL https://get.nerdit.ai | sh
    ```

    This installs under `~/.nerdit` and registers the `ai.nerdit.daemon` LaunchAgent. Current macOS binaries are not notarized; the supported installation route is the command above. Browser-downloaded archives may be blocked by Gatekeeper quarantine.
  </Tab>
</Tabs>

If the installer asks you to add `~/.nerdit/bin` to `PATH`, follow that instruction and open a new shell. The service starts automatically:

```bash theme={null}
nerdit --version
nerdit doctor
```

The local dashboard is at `http://127.0.0.1:9321/`. The proxy is initially disabled.

<Warning>
  Run `nerdit` as the recorded service user. `sudo nerdit doctor` generally reads root's configuration and may return 401. The Linux system install only needs `sudo` for installation, service management, upgrades, and removal.
</Warning>

## Connect to the App

The installer currently served by `get.nerdit.ai` installs and starts the Engine, then asks you to link separately. A local Engine works without an account link. To connect your [App account](/app/), run as the Engine's service user:

```bash theme={null}
nerdit link --device
```

Approve the displayed request in your browser and follow the CLI's restart instruction. A successful installation alone does not prove that the account link exists.

For unattended linking after installation, read a pre-auth key from a file created through the App and restricted to the intended service user:

```bash theme={null}
nerdit link --key-stdin < /path/to/nerdit-key
```

The key reaches the CLI through stdin, not a command argument. Do not print it, put it in shell history, or use tracing around credential handling. The public installer does not currently accept enrollment flags such as `--key-file` or `--no-link`; use the separate CLI linking step.

## Files and service management

| Layout       | Code and executable                                                         | Service                                         |
| ------------ | --------------------------------------------------------------------------- | ----------------------------------------------- |
| Linux system | `/opt/nerdit/<version>`, `/opt/nerdit/current`, `/usr/local/bin/nerdit`     | `/etc/systemd/system/nerdit.service`            |
| Linux user   | `~/.nerdit/versions/<version>`, `~/.nerdit/current`, `~/.nerdit/bin/nerdit` | `~/.config/systemd/user/nerdit.service`         |
| macOS        | Same user code layout                                                       | `~/Library/LaunchAgents/ai.nerdit.daemon.plist` |

State normally lives in the service user's `~/.nerdit`, separately from versioned code. Configuration may select another data directory. Preserve the existing service user and data directory when upgrading or recovering.

<Tabs>
  <Tab title="Linux system">
    ```bash theme={null}
    sudo systemctl status nerdit.service
    sudo systemctl restart nerdit.service
    sudo systemctl stop nerdit.service
    sudo systemctl start nerdit.service
    ```
  </Tab>

  <Tab title="Linux user">
    ```bash theme={null}
    systemctl --user status nerdit.service
    systemctl --user restart nerdit.service
    systemctl --user stop nerdit.service
    systemctl --user start nerdit.service
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    launchctl print gui/$(id -u)/ai.nerdit.daemon
    launchctl kickstart -k gui/$(id -u)/ai.nerdit.daemon
    launchctl bootout gui/$(id -u)/ai.nerdit.daemon
    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.nerdit.daemon.plist
    ```
  </Tab>
</Tabs>

## Verify and upgrade a release

The installer verifies an ECDSA P-256 signature over `SHA256SUMS` using its embedded release key, then checks the selected archive's checksum before extraction. Review published release notes and checksums when pinning a release. A checksum and key downloaded from the same untrusted location do not independently establish trust.

```bash theme={null}
nerdit update
nerdit --version
nerdit doctor
```

Use `sudo nerdit update` for a Linux system installation; run the verification commands afterward as the service user. Upgrades preserve configuration and state. Application containers keep running while the Engine restarts and reconciles them. There is no automatic updater.

To select the verified published release explicitly:

```bash theme={null}
nerdit update --version 0.5.5
```

The same command can downgrade code. Take a [backup](/engine/backup-recovery) first and check state/schema compatibility; an older executable is not a data rollback. An unpinned update refuses a lower release version. A fresh pinned Linux system installation uses `sudo NERDIT_VERSION=0.5.5 sh` on the installer side of the pipe.

## Remove Nerdit

<Warning>
  Default uninstall removes the Engine's data, secrets, logs, managed containers, application images, and locally saved trust files. Back up data and keys before proceeding. `--keep-data` preserves Engine state but still removes managed containers and installed code.
</Warning>

```bash theme={null}
nerdit uninstall --dry-run
nerdit uninstall --keep-data
```

Use `sudo` for both commands on a Linux system installation. Inspect the dry-run's resolved data directory. Without `--keep-data`, uninstall is destructive. `--yes` skips confirmation; `--purge-images` also removes base images pulled for models, databases, and runtimes.

Uninstall stops the Engine and verifies that its data lock is free before removal. If it cannot establish that the Engine stopped, it aborts rather than remove state beneath a live process.

Uninstall does **not** remove the CA from the operating system's trust store automatically. Run `nerdit untrust` before removing the package, or follow the manual trust-removal commands printed by uninstall. Remove that CA from other client machines too when retiring it.

Continue with the [quickstart](/engine/quickstart), or use [development setup](/engine/development) when working from source. Do not run `nerdit init` over an installer-managed configuration.