Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 106 additions & 6 deletions .github/workflows/desktop.yml
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,52 @@ jobs:
working-directory: frontend/src-tauri
run: cargo test

# Build the Python runtime that release bundles ship, install it the way the
# app does on first launch, and check that `locus serve` comes up. Release
# builds run the same check on every platform before publishing.
runtime-smoke:
if: github.event_name == 'pull_request'
strategy:
fail-fast: false
matrix:
include:
- platform: ubuntu-22.04
target: x86_64-unknown-linux-gnu
- platform: windows-latest
target: x86_64-pc-windows-msvc
runs-on: ${{ matrix.platform }}
permissions:
contents: read
steps:
- uses: actions/checkout@v7
with:
# The Locus wheel's version comes from git tags.
fetch-depth: 0

- name: Install Rust stable
uses: dtolnay/rust-toolchain@stable

- name: Rust cache
uses: swatinem/rust-cache@v2
with:
workspaces: 'rust -> target'

- name: Install uv
uses: astral-sh/setup-uv@v10.3.0
with:
version: '0.13.6'
enable-cache: true

- name: Build and smoke-test the bundled runtime
shell: bash
run: |
cd frontend/src-tauri/scripts
./download-uv.sh "${{ matrix.target }}"
./build-runtime.sh 3.12
suffix=""
[[ "${{ matrix.target }}" == *windows* ]] && suffix=".exe"
./runtime-smoke.sh "../binaries/uv-${{ matrix.target }}${suffix}"

# Remove stale artifacts from the desktop-edge rolling pre-release so that
# only the current build's files are available for download. (The stable
# `desktop-latest` channel the installed app polls is never cleaned here.)
Expand Down Expand Up @@ -359,12 +405,22 @@ jobs:
- name: Install Rust stable
uses: dtolnay/rust-toolchain@stable
with:
targets: ${{ matrix.platform == 'macos-14' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}
# macOS builds a universal app; Windows ARM64 also builds the x64
# locus_rust wheel for its emulated Python backend.
targets: ${{ matrix.platform == 'macos-14' && 'aarch64-apple-darwin,x86_64-apple-darwin' || matrix.platform == 'windows-11-arm' && 'x86_64-pc-windows-msvc' || '' }}

- name: Rust cache
uses: swatinem/rust-cache@v2
with:
workspaces: 'frontend/src-tauri -> target'
workspaces: |
frontend/src-tauri -> target
rust -> target

- name: Install uv
uses: astral-sh/setup-uv@v10.3.0
with:
version: '0.13.6'
enable-cache: true

- name: Setup Node.js
uses: actions/setup-node@v7
Expand Down Expand Up @@ -405,6 +461,41 @@ jobs:
./download-ollama.sh "$OLLAMA_TARGET"
fi

# Packaged installs set up their Python backend on first launch from
# these files with the bundled uv, so users need no git, Python or Rust.
# The smoke test installs them the same way and starts `locus serve`.
- name: Bundle uv and the Python runtime
shell: bash
run: |
cd frontend/src-tauri/scripts
case "${{ matrix.platform }}" in
macos-14)
./download-uv.sh universal-apple-darwin
for arch in aarch64 x86_64; do
cp ../binaries/uv-universal-apple-darwin "../binaries/uv-${arch}-apple-darwin"
done
UV_SIDECAR=../binaries/uv-universal-apple-darwin
./build-runtime.sh 3.12 universal2-apple-darwin
;;
windows-11-arm)
./download-uv.sh aarch64-pc-windows-msvc
UV_SIDECAR=../binaries/uv-aarch64-pc-windows-msvc.exe
# The Python stack runs under x64 emulation on Windows ARM64.
./build-runtime.sh cpython-3.12-windows-x86_64-none x86_64-pc-windows-msvc
;;
windows-latest)
./download-uv.sh x86_64-pc-windows-msvc
UV_SIDECAR=../binaries/uv-x86_64-pc-windows-msvc.exe
./build-runtime.sh 3.12
;;
*)
./download-uv.sh x86_64-unknown-linux-gnu
UV_SIDECAR=../binaries/uv-x86_64-unknown-linux-gnu
./build-runtime.sh 3.12
;;
esac
./runtime-smoke.sh "$UV_SIDECAR"

- name: Determine release info
id: release-info
shell: bash
Expand Down Expand Up @@ -496,12 +587,21 @@ jobs:
version: process.env.TAURI_VERSION,
bundle: {
createUpdaterArtifacts: true,
externalBin: ['binaries/ollama'],
externalBin: ['binaries/ollama', 'binaries/uv'],
},
};
if (process.env.OLLAMA_TARGET === 'aarch64-pc-windows-msvc') {
config.bundle.resources = { 'binaries/ollama-runtime-aarch64-pc-windows-msvc/': './' };
}
// download-ollama.sh names the runtime after the target it fetched.
const ollamaTarget = process.env.OLLAMA_TARGET ||
{ macOS: 'universal-apple-darwin', Linux: 'x86_64-unknown-linux-gnu' }[process.env.RUNNER_OS];
assert.ok(ollamaTarget, `No Ollama runtime target for ${process.env.RUNNER_OS}`);
config.bundle.resources = {
// The Python runtime the app installs on first launch.
'binaries/runtime/': 'runtime/',
// Ollama's inference libraries: beside ollama.exe on Windows, and
// under its working directory on macOS and Linux.
[`binaries/ollama-runtime-${ollamaTarget}/`]:
process.env.RUNNER_OS === 'Windows' ? './' : 'ollama-runtime/',
};
writeFileSync('frontend/src-tauri/tauri.release.conf.json', JSON.stringify(config));
NODE

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ Download the installer for your platform from the [**latest release**](https://g
| **macOS (Apple Silicon and Intel)** | `Locus_<version>_universal.dmg` |
| **Linux** | `Locus_<version>_amd64.AppImage`, `.deb`, or `.rpm` |

On first launch, choose **Ollama** to run models on your PC (or point Locus at your own OpenAI-compatible server). Locus then sets itself up: it installs its private Python runtime, starts the bundled Ollama, and downloads a model sized for your RAM. You don't need to install git, Python, Rust, or Ollama yourself. First launch needs an internet connection and takes a few minutes; later launches start in seconds.

The desktop app checks for new releases and offers to install them.

> [!NOTE]
Expand Down
16 changes: 8 additions & 8 deletions docs/downloads.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ Locus runs entirely on your hardware. Choose the interface that fits your workfl
## Desktop App

The desktop app is a native window for the Locus chat UI. All inference and backend
processing happens on your local machine — the app connects to the backend you start locally.

!!! info "Backend required"
Start the backend before opening the desktop app. The quickstart script handles everything:
```bash
git clone https://github.com/aryanjsx/Locus.git && cd Locus
./scripts/quickstart.sh
```
processing happens on your local machine, and the app sets everything up itself.

!!! info "First launch"
On first launch, choose **Ollama** (runs models on your PC) or your own
OpenAI-compatible server. Locus then installs its private Python runtime,
starts the bundled Ollama, and downloads a model sized for your RAM. This
needs an internet connection and takes a few minutes; later launches start
in seconds. You don't need to install git, Python, Rust, or Ollama yourself.

### Download

Expand Down
30 changes: 20 additions & 10 deletions docs/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,19 +78,11 @@ Then open [http://localhost:5173](http://localhost:5173).
## Desktop App

The desktop app is a native window for the Locus chat UI. All inference and backend
processing happens on your local machine — the app connects to the backend you start locally.
processing happens on your local machine, and the app sets everything up itself.

### Setup

**Step 1.** Start the backend (same as Browser App):

```bash
git clone https://github.com/aryanjsx/Locus.git
cd Locus
./scripts/quickstart.sh
```

**Step 2.** Download and open the desktop app from the
**Step 1.** Download and open the desktop app from the
[:material-download: **latest release**](https://github.com/aryanjsx/Locus/releases/latest):

| Platform | File |
Expand All @@ -102,6 +94,24 @@ cd Locus
| Linux (RPM) | `Locus-<version>-1.x86_64.rpm` |
| Linux (AppImage) | `Locus_<version>_amd64.AppImage` |

**Step 2.** On first launch, choose **Ollama** to run models on your PC, or
point Locus at your own OpenAI-compatible server. Locus then sets itself up:

1. Installs its private Python runtime in `~/.locus/desktop-runtime`, including
a Python it downloads for itself.
2. Starts the bundled Ollama. If you already have Ollama installed, Locus uses
that instead, keeping CUDA acceleration if you have it.
3. Downloads a model sized for your RAM and starts the Locus server.

First launch needs an internet connection and takes a few minutes. Later
launches start in seconds. You don't need to install git, Python, Rust, or
Ollama yourself. If setup fails, relaunch Locus to retry; to start over,
delete `~/.locus/desktop-runtime`.

The bundled Ollama runs models on your CPU, with Vulkan GPU acceleration on
Windows and Linux and Metal on Apple Silicon Macs. For NVIDIA CUDA acceleration, install
[Ollama](https://ollama.com/download) yourself; Locus will use it.

The app connects to `http://localhost:8000` automatically.

!!! warning "macOS: the app isn't signed by Apple yet"
Expand Down
15 changes: 4 additions & 11 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,18 +53,11 @@ Locus is that stack. It is a framework for local-first personal AI, built around

=== "Desktop App"

The desktop app is a native window for the Locus UI.
The backend (Ollama + inference) runs on your machine — start it first, then open the app.
The desktop app is a native window for the Locus UI. It runs everything
on your machine and sets itself up on first launch: its Python runtime,
the bundled Ollama, and a model sized for your RAM.

**Step 1.** Start the backend:

```bash
git clone https://github.com/aryanjsx/Locus.git
cd Locus
./scripts/quickstart.sh
```

**Step 2.** Download and open the desktop app:
Download and open the desktop app:

[Download the desktop app](https://github.com/aryanjsx/Locus/releases/latest){ .md-button .md-button--primary }

Expand Down
4 changes: 3 additions & 1 deletion frontend/src-tauri/binaries/.gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Downloaded sidecar binaries — platform-specific, not committed
# Downloaded sidecar binaries and built runtime — platform-specific, not committed
ollama-*
uv-*
runtime/
!.gitignore
77 changes: 77 additions & 0 deletions frontend/src-tauri/scripts/build-runtime.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
#!/usr/bin/env bash
#
# Build the Python runtime bundled with the desktop app into
# frontend/src-tauri/binaries/runtime/. On first launch the app installs it
# with the bundled uv, so end users need no git, Python, or Rust toolchain.
#
# Usage:
# ./build-runtime.sh <uv-python-request> [cargo-target]
# ./build-runtime.sh 3.12
# ./build-runtime.sh 3.12 universal2-apple-darwin
# ./build-runtime.sh cpython-3.12-windows-x86_64-none x86_64-pc-windows-msvc
#
# Output:
# requirements.txt third-party dependencies, hash-locked from uv.lock
# locus_assistant-*.whl, locus_rust-*.whl
# manifest.json the Python request and file names the app installs
#
# Requires uv, a Rust toolchain for the target, and the repository's git
# history (the Locus version comes from git tags).

set -euo pipefail

PYTHON_REQUEST="${1:?usage: build-runtime.sh <uv-python-request> [cargo-target]}"
CARGO_TARGET="${2:-}"

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
OUT_DIR="$SCRIPT_DIR/../binaries/runtime"
rm -rf "$OUT_DIR"
mkdir -p "$OUT_DIR"
OUT_DIR="$(cd "$OUT_DIR" && pwd)"
cd "$REPO_ROOT"

# The rust/ workspace pins an MSRV toolchain without the cross targets the
# release jobs install on stable.
export RUSTUP_TOOLCHAIN="${RUSTUP_TOOLCHAIN:-stable}"

echo "Exporting locked requirements..."
uv export --frozen --no-dev --no-header --no-emit-project \
--no-emit-package locus-rust \
--extra desktop --extra inference-cloud --extra inference-google \
--format requirements-txt -o "$OUT_DIR/requirements.txt"

echo "Building the Locus wheel..."
uv build --wheel --out-dir "$OUT_DIR"

echo "Building the locus_rust wheel for Python $PYTHON_REQUEST..."
uv python install "$PYTHON_REQUEST"
PYTHON_BIN="$(uv python find --managed-python "$PYTHON_REQUEST")"
maturin_args=(
build --release
--manifest-path rust/crates/locus-python/Cargo.toml
--interpreter "$PYTHON_BIN"
--out "$OUT_DIR"
)
if [ -n "$CARGO_TARGET" ]; then
maturin_args+=(--target "$CARGO_TARGET")
fi
uvx --from 'maturin>=1.12.6,<2' maturin "${maturin_args[@]}"

"$PYTHON_BIN" - "$OUT_DIR" "$PYTHON_REQUEST" <<'PY'
import json
import sys
from pathlib import Path

out, python = Path(sys.argv[1]), sys.argv[2]
wheels = sorted(p.name for p in out.glob("*.whl"))
for prefix in ("locus_assistant-", "locus_rust-"):
found = [w for w in wheels if w.startswith(prefix)]
if len(found) != 1:
sys.exit(f"expected one {prefix}*.whl in {out}, found {found}")
manifest = {"python": python, "requirements": "requirements.txt", "wheels": wheels}
(out / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
print(json.dumps(manifest, indent=2))
PY

ls -lh "$OUT_DIR"
Loading
Loading