Install a local LLM on Windows, Linux or Docker

Before you start

• A 64-bit Windows or Linux computer, with internet access and a web browser.
• 16 GB of memory (RAM) and 10 GB of free disk space for a small first model. Bigger models need more.
• A graphics card helps a lot. Without one, models run on the processor, more slowly.
• On Windows, permission to approve an administrator prompt. On Linux, your normal account.

You do not need to install Python, Node.js, Git or llama.cpp yourself. Eugene asks before it installs anything else or downloads a model.

1. Install on Windows

Open PowerShell from the Start menu. Paste this command, press Enter, and approve the administrator prompt when it appears.

irm https://eugeneplexus.com/releases/v0.5.0/install.ps1 | iex

What you will see

1. Windows asks whether to allow the app to make changes. Choose Yes.
2. The window may sit quietly for a few minutes while Eugene installs in the background.
3. It finishes with a line ending in done. and the path to a log file.
4. Open http://127.0.0.1:8079/ on this computer. You should see Choose a passphrase.

Nothing opens, or you see a red error? Check If something goes wrong.

The default install lives in C:\ProgramData\EugenePlexus and runs as a Windows service, so it starts with the computer. If PowerShell was already running as administrator, the last line says Eugene Plexus is running instead.

If an older per-user install is on this computer, the installer explains the move before it changes anything. Keep your passphrase at hand.

1. Install on Linux

Open a terminal as your normal user. Paste this command and press Enter. Do not run it with sudo.

curl -fsSL https://eugeneplexus.com/releases/v0.5.0/install.sh | sh

What you will see

1. Lines starting with ==> scroll past while Eugene installs. This can take a few minutes.
2. It finishes with Eugene Plexus is running and an address.
3. Open http://127.0.0.1:8079/. You should see Choose a passphrase.

If it prints a different address or a command to start Eugene yourself, follow what it prints.

The installer asks for your password once, through sudo. Eugene installs in /var/lib/eugene-plexus and runs as a system service under its own account, eugene-plexus, so it starts with the computer and programs you run cannot read its keys. It reaches your models folder through your group.

To install under your own account instead, add -s -- --user after sh: Eugene then lives in ~/.local/share/eugene-plexus as a systemd user service that starts when you sign in, or before sign-in if you follow the installer's optional loginctl enable-linger instruction. WSL needs systemd for either; otherwise use the manual command it prints and keep that terminal open.

1. Install with Docker / NAS

This runs the console, control root, gateway and model library on your NAS or Linux server. The container can also run models itself, on its processor or on a passed-through NVIDIA card, which you turn on. The container's GPU path has not been checked on physical hardware yet; the tested way to run models on a GPU is to join a Windows or Linux worker, below.

Use this example for a new install. If Eugene already runs on your NAS, follow Update and keep its existing storage and ports.

Prepare persistent storage

Create a project folder on your server. Inside it, create a models folder for your model files and downloads. The container runs as UID/GID 10001:10001; give that account read and write access to the models folder through your NAS permissions settings. On an ordinary Linux host, from the new project folder:

mkdir models && sudo chown 10001:10001 models

For an existing model collection, change source: ./models below to its absolute host path and grant access to that folder. Keep your existing ownership and sharing setup. The Unraid guide covers NAS-specific settings; if using its template, set the image to ghcr.io/eugene-plexus/control-plane:v0.5.0 before starting.

Save and start the Compose project

Save this as compose.yaml in the project folder, or paste it into your NAS's Compose editor with an absolute model-folder path. The plexus-data volume preserves configuration, enrollment, keys and logs; the model folder stays on your host.

name: eugene-plexus

services:
  control-plane:
    image: ghcr.io/eugene-plexus/control-plane:v0.5.0
    hostname: eugene-plexus
    init: true
    restart: unless-stopped
    stop_grace_period: 60s
    ports:
      - "8279:8079" # Browser console
      - "8280:8080" # Application API
      - "8283:8083" # Worker enrollment
    volumes:
      - plexus-data:/data
      - type: bind
        source: ./models
        target: /models
        bind:
          create_host_path: false

volumes:
  plexus-data:

From that folder, run:

docker compose pull
docker compose up -d

These ports are reachable on the host's network interfaces. Keep them on a trusted LAN or VPN, and complete first-run setup immediately: the first person to open the console chooses the install's passphrase. No router port forwarding is needed.

Open the console and set its address

Replace NAS-IP with your server's LAN address. These addresses use the published host ports from the example:

Browser console

http://NAS-IP:8279/

Application API base URL

http://NAS-IP:8280/v1

Control root for worker enrollment

http://NAS-IP:8283

Open the console, choose and save your passphrase, and use /models as the model folder inside the container. In Settings → Access & security, set the NAS machine's Advertise address to http://NAS-IP:8279 so other nodes can reach it. If you change the left side of a port mapping, use that new port in the matching address above.

Join the computer that will run models

1. In the NAS console, open Machines → Add a node. Leave the optional node name blank, set Control root URL the other machine can reach to http://NAS-IP:8283, and choose Make a join token.
2. Copy the command the page prints for the worker's system and run it there; it installs this release and joins in one step. If you prefer the commands below, replace NAS-IP and JOIN-TOKEN with the address and the token value after -Token or --token. Tokens expire and work once, so mint a new one for each worker.
3. If Eugene is already on the worker, from any version or half-finished attempt, the join moves it aside first. Nothing is deleted, and if the join fails the machine is put back as it was, with a message that says why.

& ([scriptblock]::Create((irm https://eugeneplexus.com/releases/v0.5.0/install.ps1))) -Join 'http://NAS-IP:8283' -Token 'JOIN-TOKEN'

curl -fsSL https://eugeneplexus.com/releases/v0.5.0/install.sh | sh -s -- --join 'http://NAS-IP:8283' --token 'JOIN-TOKEN'

On Windows, approve the administrator prompt. On Linux, run as your normal user. Check that Machines reports the worker as reachable. The worker must reach the NAS ports above, and the NAS must reach the worker's agent, normally port 8079.

Share the host model folder over SMB or NFS and make it readable on the worker. Under Settings → Model storage on each machine, map /models on that worker to its path to the same files. A Windows service needs its own file-server login there too; a mapped desktop drive is not enough.

In Library, select the worker as the launch target, choose or download a model, and start it there. When it is ready, try Playground using Through this agent. For a direct connection or another app, use http://NAS-IP:8280/v1 and an application key from Use it from your apps on the Home page. The container's internal port 8080 is not the published API port in this example.

Workbench on the NAS: install it under Apps on the container's machine. To reach it and the console through one HTTPS port with their own names, follow Serve the container on one HTTPS port; the three ports above keep working.

After a container restart: sign in to the NAS console to unlock the control root; if your browser is already signed in, sign out and back in. A healthy container can still be locked. See unattended unlock for optional startup with a mounted passphrase file.

Mac testing

The installer also has a macOS path, but physical Mac verification remains outstanding for this release. If you want to help test it, run the Linux/Mac command in Terminal as your normal user. It installs a launchd agent for your login. MLX and llama.cpp on Metal have run on GitHub's macOS runners, not yet on a physical Mac.

curl -fsSL https://eugeneplexus.com/releases/v0.5.0/install.sh | sh

2. Get your first reply

For a Windows or Linux standalone install, continue below. For Docker / NAS, finish the worker and model-folder setup in the Docker instructions first and launch models on that worker.

1. Choose a passphrase. Save it somewhere you can find again. It protects your install; there is no passphrase recovery.
2. Choose where models live. Accept the proposed folder to start fresh, or choose a folder containing models you already own.
3. On the Home page, choose Download and run. Eugene proposes a model for this machine. Check the download size and approve the engine installation when asked. If a model is already on disk, choose Run.
4. Wait for the model to be ready, then send a message. Downloads and loading appear in Tasks. The first download can be several gigabytes.

To connect another app, use Use it from your apps on the Home page. Make a client key, then copy the address, model name and key into your app. Keep the key private. The console writes the setup for each app; see Connect Codex or Claude Code.

For a chat app of your own, install Workbench from Apps.

To try your phone, turn on the switch in Reach it from other devices on the Home page, and use the address it shows. Keep both devices on a trusted LAN or VPN; 127.0.0.1 always means the device you are currently using. Finish setup before enabling access from other devices.

Update or repair an install

From v0.1.0, update from the console: the control root first, then every other machine. A machine left on v0.1 will not work with a v0.2 root. The update guide has the steps, and what to do after. Machines → Versions shows what each machine runs and whether a newer version is out, and updates any machine from whichever console you have open. Eugene checks GitHub for a newer version a minute after it starts and every six hours, and installs only when you press Update. Settings → Updates turns the check off or changes the channel.

From v0.2.0 to v0.2.3: update the control root first, then every standby root, before anything else; machines on mixed versions refuse Workbench model requests until they match. Workbench moves its data to a new format and keeps a copy of the old store. Open Machines → Versions → Update all to update the remaining machines and their installed catalogue apps, including Workbench, in one operation. Each machine follows its selected update channel. Progress survives closing the page or restarting the console. Containers still update through Docker or their NAS controls; if the root needs a manual update, the other machines wait. Offline machines and failures are listed individually.

From an alpha, move to v0.1.0 first: run v0.1.0's install command on each machine (irm https://eugeneplexus.com/releases/v0.1.0/install.ps1 | iex on Windows, curl -fsSL https://eugeneplexus.com/releases/v0.1.0/install.sh | sh on Linux), then update. An alpha's console would skip v0.1.0. Alpha.2 or earlier needs a fresh install; see the alpha.3 release notes.

Read the backup and recovery guide before updating. Create and rehearse a checkpoint once your install is set up.

These versioned commands stay on v0.5.0; they do not silently follow development changes. Do not run an older installer over a newer installation.

Remove Eugene

If your installation has the local removal utility, start there. On Windows, open Settings → Apps → Installed apps → Eugene Plexus → Uninstall. On Mac, open Remove Eugene Plexus in your home folder’s Applications folder. These utilities work without an internet connection or a running Eugene. The Mac app has not been run on a physical Mac yet.

The local utility shows sizes and offers two separate, unchecked choices: delete settings, app data and logs; or delete downloaded engines and managed model copies. By default it removes the software and keeps that data. Original model folders are always kept. The final report names retained files and gives a local cleanup command that works later, even after Python has been removed.

If the local utility is missing, use the matching installer below.

On Windows, open PowerShell with Run as administrator for the default service install, then run:

& ([scriptblock]::Create((irm https://eugeneplexus.com/releases/v0.5.0/install.ps1))) -Uninstall

On Linux or Mac, use your normal terminal account:

curl -fsSL https://eugeneplexus.com/releases/v0.5.0/install.sh | sh -s -- --uninstall

On Windows, on a Mac and in a Linux per-user install, these commands remove the software and startup registration while keeping settings, app data and downloads. The retained folder includes an offline cleanup utility. Linux system removal preserves its installation folder. Custom installations need their original prefix.

A cleanup warning means an item still needs attention. Read the final report before treating removal as complete. Shared operating-system dependencies, such as the Microsoft Visual C++ runtime, are kept.

For Docker, run docker compose down from the project folder to stop and remove the container while retaining the state volume and model files. Do not add --volumes if you want to keep the install's identity and configuration.

If something goes wrong

If an update left Eugene unable to start, follow the backup and recovery guide.

The first message says the model is still loading

The Home page waits for model readiness before enabling Send. If another client connects while the model is loading, wait for Tasks to show it is ready before sending again. A “still coming up” response does not mean the model has crashed.

The page does not open

Use the address printed by the installer, on the same computer. Read the final error and log location in the terminal. On Linux, check systemctl status eugene-plexus-agent, adding --user for a per-user install; on Windows, look for EugenePlexusAgent in Services.

The model will not start or is too slow

Read the problem shown on the Home page and open Tasks for details. Try a smaller model or a shorter context. A memory-fit estimate is not a speed guarantee.

A network folder is missing

Begin with a local folder. A Windows service needs its own file-server login under Settings → Model storage on each machine; a drive letter mapped in your desktop session may not exist for it.

Not sure what went wrong, or just have a question? Ask it on GitHub. You need a free GitHub account.

Report a problem on GitHub. Include v0.5.0, your OS, GPU and RAM, what you were trying to do, and the error text. Remove passphrases, API keys, private paths and prompts from shared logs or screenshots.