Getting started
Install a packaged build, or build from source. Both are covered below.
Install / update in one line
curl -fsSL https://raw.githubusercontent.com/Hankanman/Orrery/main/scripts/install.sh | bashThis installs the latest release AppImage for your user, with no root needed:
- the download is checked against the release's
SHA256SUMS; - it's stored in
~/.local/opt/orrery; - it's launched by a small
~/.local/bin/orreryscript; - it gets an app-menu entry (
orrery.desktop) and icon.
AppImageLauncher: if you have AppImageLauncher installed, it normally offers to "integrate" any AppImage you run, copying it into ~/Applications with a second menu entry. The launcher script and menu entry set APPIMAGELAUNCHER_DISABLE=1, so the installed copy runs as it is. If AppImageLauncher already integrated a copy, remove it (right-click its menu entry → Remove AppImage from system). Keep the orrery.desktop entry this script installs: the global shortcut relies on it (see below).
Updating: run the same command again. If you're already on the latest release it downloads nothing, and just refreshes the launcher and menu entry.
Options:
ORRERY_VERSION=v1.0.0installs a specific tag.ORRERY_PREFIX=…changes the install location from~/.local.
Uninstalling: append -s -- --uninstall to the command. Your config and cache are left in place.
Install a release manually
Or grab the latest artifact for your distro from the releases page:
# Optional: verify the download against the release's SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
# AppImage — portable, no install
chmod +x Orrery-x86_64.AppImage
./Orrery-x86_64.AppImage
# Debian / Ubuntu
sudo apt install ./orrery_*_amd64.deb
# Fedora
sudo dnf install ./orrery-*.x86_64.rpmThe AppImage bundles a llama.cpp engine, so the local-AI features work out of the box once you download a model. The .deb and .rpm don't; use Ollama or a llama-server on your PATH (see Local AI). Code search needs ripgrep (rg) installed.
Prerequisites
Orrery is a native Rust app on GPUI — no webview. Building from source needs:
- Rust — the toolchain pinned in
rust-toolchain.toml(rustup auto-selects it) - GPUI system libraries — Vulkan, Wayland/XCB,
libxkbcommon,fontconfig, plus a C/C++ toolchain,cmakeandpkg-config
The repo ships a setup script that installs these across dnf/apt/pacman/zypper:
bash scripts/setup.shOr install them by hand. On a Debian/Ubuntu base:
sudo apt install libvulkan-dev libwayland-dev libxkbcommon-dev \
libxkbcommon-x11-dev libxcb1-dev libfontconfig1-dev libssl-dev \
build-essential cmake pkg-configOn Fedora:
sudo dnf install vulkan-loader-devel vulkan-headers mesa-vulkan-drivers \
wayland-devel libxkbcommon-devel libxkbcommon-x11-devel libxcb-devel \
fontconfig-devel openssl-devel gcc gcc-c++ make cmake pkgconf-pkg-configNode + pnpm are optional — only the docs site and the icon generator use them.
Clone and run
git clone https://github.com/Hankanman/Orrery.git
cd Orrery
cargo run -p orrery # first build is slow: it compiles all of GPUIOn first launch, open Settings → Workspace roots and point Orrery at the directories where you keep your projects (defaults to ~/dev). Then Save.
The desktop entry and the global shortcut
The summon shortcut (Ctrl+Alt+O) goes through the desktop's GlobalShortcuts portal, which needs to know which app is asking. Orrery registers the app id orrery with the portal at startup, and the portal accepts it only if a desktop entry named orrery.desktop is installed. The packages and the install script provide one. A source build doesn't, so install the repo's copy once:
install -Dm644 packaging/orrery.desktop ~/.local/share/applications/orrery.desktopWithout it the log shows couldn't register app id 'orrery' … App info not found, and on KDE the shortcut fails with An app id is required. With it you'll see registered app id 'orrery' and bound 'activate' → Ctrl+Alt+O.
Build a release
Tagged releases (v*) build the bundles in CI. To produce them locally:
cargo build --release --locked -p orrery
cargo install --locked cargo-deb@3.8.0 cargo-generate-rpm@0.21.0
cargo deb -p orrery --no-build # → target/debian/*.deb
cargo generate-rpm -p crates/orrery \
--metadata-overwrite packaging/rpm-requires.toml # → target/generate-rpm/*.rpm
bash packaging/fetch-llama.sh # optional: bundle llama-server in the AppImage
bash packaging/appimage.sh # → dist-appimage/Orrery-x86_64.AppImage (fetches pinned linuxdeploy)
bash packaging/collect-artifacts.sh # → dist/ + SHA256SUMSCI runs this same sequence as a dry run on every pull request (.github/workflows/package.yml), so packaging breakage shows up before a tag.
Useful commands
| Command | What it does |
|---|---|
cargo run -p orrery | Run the desktop app |
cargo build --workspace | Build everything |
cargo test --workspace | Run the tests |
cargo clippy --workspace --all-targets -- -D warnings | Lint |
cargo fmt --all | Format |
bash scripts/dev-clean.sh | Force an asset re-embed and relaunch |
pnpm icons | Regenerate the committed icon SVGs (optional) |
Next: the feature tour or configuration reference.