hex/docs/nix.md
Dax 66d91dd47f
docs: nix install is linux only (#1582)
* docs: nix install is linux only

* docs: shorter nix label
2026-11-09 05:11:35 -05:00

215 lines
8.7 KiB
Markdown

# Nix
The flake packages Hex for Linux only, `x86_64-linux` and `aarch64-linux`;
there is no macOS package. Both targets build from source; `aarch64-linux`
evaluates but has not been built or run on real ARM64 hardware yet. It
supports the Linux X11 beta and native Wayland on compatible wlroots
compositors. Wayland requires layer-shell for the recording overlay, the
clipboard protocol used by `wl-copy`, and the virtual-keyboard protocol
used by `wtype`. Global shortcuts come from the desktop's GlobalShortcuts
portal, or from your own compositor keybindings running the `hex` commands.
This is not a claim of support for every Wayland desktop; GNOME and KDE are
not covered by this contract.
## Run Or Install
On macOS, install the [DMG or Homebrew cask](../README.md#downloads) instead;
the flake has no `aarch64-darwin` package.
From a checkout, with Nix flakes enabled:
```sh
nix build
nix run . -- model install
nix run . -- app
```
Or add `hex.url = "github:anomalyco/hex"` to your configuration's flake inputs
and install `hex.packages.${system}.default` (`x86_64-linux` or
`aarch64-linux`). The package supplies the
`hex` command and desktop launcher, native libraries (including PipeWire and
libva for Annotate), and the `curl`, `wl-copy`, `wtype`, and `ffmpeg`/`ffprobe`
runtime dependencies. Annotate's hardware encoder uses whatever VA-API driver
your system provides (NixOS: `hardware.graphics`, through `/run/opengl-driver`);
without one it falls back to ffmpeg's libx264. Your system still needs a
working audio session and a Vulkan driver for Settings, even when inference
falls back to the CPU. On non-NixOS hosts, Nix GUI
applications may require the host's usual Nix graphics integration.
On NixOS, Hex built from its own pinned nixpkgs can use an older glibc than
your system's graphics drivers need. Hex then finds no suitable Vulkan
adapter and its window does not open. Make Hex's nixpkgs follow your
system's, so both use the same glibc:
```nix
{
inputs.hex = {
url = "github:anomalyco/hex";
# Use the name of your own nixpkgs input here.
inputs.nixpkgs.follows = "nixpkgs";
};
}
```
Models are downloaded into your user data directory, not the Nix store.
Run `hex model install` once, then launch Hex as your normal desktop user.
Do not run Hex as root.
The Nix store is not Hex's user-local managed installation layout. In-app
updates do not replace a Nix installation. Update the flake input and
rebuild or switch your Nix/Home Manager configuration instead. Remove any
old source-install XDG autostart entry before enabling a second autostart
mechanism; do not run two Hex listeners.
## NixOS
Import `hex.nixosModules.hex` and enable the package:
```nix
{
imports = [ hex.nixosModules.hex ];
programs.hex.enable = true;
}
```
This installs Hex system-wide. It does not start a root service or enable
autostart for every account. Use the
Home Manager module below for per-user autostart. Both modules accept an
explicit `programs.hex.package` override. The flake also exports
`hex.overlays.default` for configurations that prefer `pkgs.hex`.
## Home Manager
```nix
{
imports = [ hex.homeManagerModules.hex ];
programs.hex = {
enable = true;
autostart = true;
# Use your compositor's session target when appropriate:
# systemdTarget = "sway-session.target";
};
}
```
The module always installs the systemd **user** service. Autostart defaults to
`false`; when enabled, the unit is wanted by `graphical-session.target` by default.
It waits for a Wayland socket or an X11 window manager before launching `hex service`,
which reports readiness to systemd (`Type=notify`) once its socket answers.
Hex is one process: `hex` opens its window, starting the unit when it is not
running, and `hex start` starts it without the window. Closing the window never
stops Hex; a tray icon shows when the desktop has a tray host. The unit stops with the configured target
and retries failed starts without a tight restart loop; a crash restart opens no
window. `hex quit` (or **Quit Hex** in the window) leaves it stopped until the
next session or the next launch.
Your session manager must import its current `DISPLAY`, `XAUTHORITY`,
`WAYLAND_DISPLAY`, and `XDG_RUNTIME_DIR` values as applicable into the systemd
user environment **before** starting the target, and stop the target at
logout. Use your compositor's systemd integration, such as Home Manager's
Sway integration, rather than starting the target from a shell login.
The module does not create a graphical session or grant permission to use
one. A bare `startx`/i3 session without systemd session integration will not
start this service automatically.
`hex start` records the current display/session environment in an owner-only
file read by the unit; it clears stale variables when switching between X11 and
Wayland. There is one Hex per user. Launching it from a different desktop
explicitly restarts the unit for that session. The unit names Hex's default
data folder, so Hex still treats it as its own supervised service: a stale
`XAUTHORITY` from an earlier login (GNOME's XWayland cookie) is replaced with
the user manager's current one, keeping the HUD working after a re-login (#1140).
Home Manager's normal service-switch policy applies: newly enabled services
can start during a switch if the session target is already active, and
package changes can restart a running service. Do not switch during an
active recording. Inspect failures with:
```sh
systemctl --user status hex.service
journalctl --user -u hex.service
```
### Declarative Settings
```nix
{
programs.hex = {
enable = true;
shortcut = "control+option+space"; # dictation_hotkey
model = "parakeet_v3";
language = "de";
installModel = true;
settings = {
shortcut_mode = "toggle";
sound_effect_volume = 0.4;
paste_with_shift = true;
"meetings.enabled" = true;
};
};
}
```
`settings` takes the dotted keys `hex settings list` shows, with JSON values:
booleans, numbers, text such as shortcuts and choices, `null` to clear an
optional setting, and attribute sets or lists for its `json` settings. The
`shortcut`, `model`, and `language` options are shorthands for
`dictation_hotkey`, `transcription.model`, and `transcription.language`.
Every activation merges them into Hex with `hex settings apply`, after
systemd units reload. Declared keys overwrite Hex's values; anything you
change in the window that isn't declared keeps its value until you declare
it. A running Hex saves and adopts the settings at once, so it never writes
older values back from memory; with Hex stopped they go straight into
`settings.json`. `settings.json` stays an ordinary writable file. An unknown
key or invalid value applies nothing and prints a warning, without failing
the switch.
Declaring a model only selects it; activation never downloads. With
`installModel = true`, the `hex-model` user service runs `hex model install`
for the selected model at login, once the system's `network-online.target`
is reached (or after two minutes), and retries a failed download. A switch
does not wait for it.
## Wayland Shortcuts
Hex reads no input devices, so neither module adds users to the `input`
group, installs udev rules, or grants capabilities. With a GlobalShortcuts
portal, the desktop grants the shortcuts Settings records; the portal
identifies Hex by the package's `anomaly.hex.desktop` entry, so keep the package's
`share/applications` on `XDG_DATA_DIRS` (NixOS and Home Manager profiles do).
Without the portal, bind the commands in your compositor, for example in Sway:
```sh
bindsym F9 exec hex dictation start
bindsym --release F9 exec hex dictation stop
```
`hex dictation toggle` and `hex paste-last`
are also available; see the
[Linux guide](linux.md#shortcuts). The paste helper is `wtype`; no privileged
input-injection fallback is installed.
## Development
```sh
nix develop
cargo build --locked
cargo test --locked
cargo run --locked -- app
```
The package and shell share the native build environment and runtime
library/plugin paths. OpenBLAS link ordering is handled by `build.rs`, not
by Nix-only `RUSTFLAGS`. The shell also supplies the paste and download
helpers, so it does not rely on the installed app's wrapper. Desktop commands
still require a real graphical/audio session and the permissions described above.
`nix flake check` evaluates the module and shell-environment regressions and
builds the package with its normal display-free Rust tests. Tests explicitly
marked ignored because they require a desktop or installed model remain
ignored; the Nix build does not download models or exercise live input.
The initial packaging design builds on [PR #29](https://github.com/anomalyco/hex/pull/29).
Declarative settings follow
[@SymphonySimper's request in #588](https://github.com/anomalyco/hex/issues/588).