mirror of
https://github.com/mudler/LocalAI.git
synced 2026-10-28 17:18:49 -04:00
mudler-agentandEttore Di Giacinto
33459f2e2a
* feat(launcher): package a Linux AppImage Ship the existing Fyne launcher as an additive release asset without bundling the server or changing its runtime downloader. Pin packaging tools and the type-2 runtime, preserve the caller environment, and document the native amd64 graphics requirements. Validate packaging contracts and wire extraction smoke checks into CI. Assisted-by: Codex:gpt-5 * fix(launcher): harden AppImage release checks PR builds must not receive repository write credentials. Isolate uploads in a gated job that consumes the tested artifact without checkout. Keep the existing release check and dependency on GoReleaser. A surviving process does not prove that the UI event loop works. Require observable startup progress, reject initialization errors, and bound termination. Document the remaining limits without changing the launcher application. Add permission and smoke failure regressions. Assisted-by: nib:unknown * fix(launcher): install file for AppImage builds appimagetool fails after Go compilation when file is missing. Install it explicitly in CI and document the local build dependency. Check for it before compilation and cover the missing-command failure in tests. Assisted-by: nib:unknown --------- Co-authored-by: Ettore Di Giacinto <mudler@localai.io>
164 lines
5.2 KiB
Markdown
164 lines
5.2 KiB
Markdown
---
|
|
title: "Linux Installation"
|
|
description: "Install LocalAI on Linux using binaries"
|
|
weight: 9
|
|
url: '/installation/linux/'
|
|
---
|
|
|
|
## Desktop launcher AppImage (x86_64)
|
|
|
|
Download `LocalAI-Launcher-x86_64.AppImage` and its `.sha256` file from
|
|
[GitHub Releases](https://github.com/mudler/LocalAI/releases). In that directory:
|
|
|
|
```sh
|
|
sha256sum --check LocalAI-Launcher-x86_64.AppImage.sha256
|
|
chmod +x LocalAI-Launcher-x86_64.AppImage
|
|
./LocalAI-Launcher-x86_64.AppImage
|
|
```
|
|
|
|
You can also double-click the executable image in a file manager. Normal
|
|
AppImage mounting requires FUSE support (on Ubuntu 22.04, `libfuse2`). If FUSE
|
|
is unavailable, extract it into a writable directory and run the launcher:
|
|
|
|
```sh
|
|
./LocalAI-Launcher-x86_64.AppImage --appimage-extract
|
|
./squashfs-root/AppRun
|
|
```
|
|
|
|
This is the existing desktop/tray launcher, not the server bundled into an
|
|
image. First use needs internet access to download LocalAI. Models and backends
|
|
are downloaded separately. The launcher stores configuration in
|
|
`~/.localai/launcher.json`, runtime downloads in `~/.localai/bin`, and default
|
|
models/backends under `~/.localai/`. Fyne preferences use the user configuration
|
|
directory. These remain writable outside the read-only image. Keep your home
|
|
writable; replacing or deleting the AppImage does not delete your data.
|
|
|
|
The supported release target is **x86_64 Ubuntu 22.04 or newer**, with glibc
|
|
2.35+, OpenGL and X11 desktop libraries (XWayland on Wayland). A tray-enabled
|
|
desktop is recommended. This is not a static executable: other distributions
|
|
must provide compatible graphics libraries. ARM64 AppImages are not currently
|
|
published; use the server binaries below instead. Server/backend requirements
|
|
are separate from launcher requirements. Replace the AppImage manually to
|
|
update the launcher; there is no AppImage self-updater.
|
|
|
|
For build dependencies, pinned tools and smoke checks, see
|
|
[the AppImage build guide](https://github.com/mudler/LocalAI/blob/master/contrib/appimage/README.md).
|
|
|
|
## Manual Installation
|
|
|
|
### Download Binary
|
|
|
|
You can manually download the appropriate binary for your system from the [releases page](https://github.com/mudler/LocalAI/releases):
|
|
|
|
1. Go to [GitHub Releases](https://github.com/mudler/LocalAI/releases)
|
|
2. Download the binary for your architecture (amd64, arm64, etc.)
|
|
3. Make it executable:
|
|
|
|
```bash
|
|
chmod +x local-ai-*
|
|
```
|
|
|
|
4. Run LocalAI:
|
|
|
|
```bash
|
|
./local-ai-*
|
|
```
|
|
|
|
### Run your first model
|
|
|
|
Starting the binary on its own gives you an empty server. To get a working chat right away, run LocalAI with a model name and it will download and serve it from the gallery:
|
|
|
|
```bash
|
|
./local-ai-* run qwen3-4b
|
|
```
|
|
|
|
Once it is ready, open the WebUI at `http://localhost:8080` or send a request to the API:
|
|
|
|
```bash
|
|
curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{
|
|
"model": "qwen3-4b",
|
|
"messages": [{"role": "user", "content": "Hello!"}]
|
|
}'
|
|
```
|
|
|
|
### System Requirements
|
|
|
|
Hardware requirements vary based on:
|
|
- Model size
|
|
- Quantization method
|
|
- Backend used
|
|
|
|
For performance benchmarks with different backends like `llama.cpp`, visit [this link](https://github.com/ggerganov/llama.cpp#memorydisk-requirements).
|
|
|
|
## Configuration
|
|
|
|
After installation, you can:
|
|
|
|
- Access the WebUI at `http://localhost:8080`
|
|
- Configure models in the models directory
|
|
- Customize settings via environment variables or config files
|
|
|
|
## Start LocalAI on demand with systemd
|
|
|
|
LocalAI accepts a single TCP listener passed through the systemd socket
|
|
activation protocol. This lets systemd listen on the public port and start
|
|
LocalAI only when the first client connects.
|
|
|
|
Create `/etc/systemd/system/local-ai.socket`:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=LocalAI API socket
|
|
|
|
[Socket]
|
|
ListenStream=8080
|
|
NoDelay=true
|
|
|
|
[Install]
|
|
WantedBy=sockets.target
|
|
```
|
|
|
|
Create the matching `/etc/systemd/system/local-ai.service`:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=LocalAI
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=localai
|
|
Group=localai
|
|
ExecStart=/usr/local/bin/local-ai run
|
|
WorkingDirectory=/var/lib/local-ai
|
|
```
|
|
|
|
Adjust the user, binary path, working directory, and model configuration for
|
|
your installation. Then enable the socket, not the service:
|
|
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now local-ai.socket
|
|
```
|
|
|
|
The first connection to port 8080 starts `local-ai.service`; systemd holds that
|
|
connection until LocalAI is ready to accept it. `LOCALAI_ADDRESS` and
|
|
`--address` are ignored while an inherited listener is present. LocalAI
|
|
rejects activation with multiple stream listeners so it cannot silently choose
|
|
the wrong endpoint.
|
|
|
|
For a Podman-managed container, configure Podman to preserve and pass the
|
|
systemd socket file descriptor into the container. The LocalAI process inside
|
|
the container consumes the same activation protocol.
|
|
|
|
Activation needs both `LISTEN_PID` and `LISTEN_FDS`. If only one of them is set,
|
|
LocalAI ignores them and binds `--address` as usual. A container engine started
|
|
from a socket-activated system unit can leak a bare `LISTEN_PID` into every
|
|
container it spawns, and that is not an activation attempt.
|
|
|
|
## Next Steps
|
|
|
|
- [Try it out with examples](/basics/try/)
|
|
- [Learn about available models](/models/)
|
|
- [Configure GPU acceleration](/features/gpu-acceleration/)
|
|
- [Customize your configuration](/advanced/model-configuration/)
|