install

$ uv tool install --python 3.12 logcrux
$ logcrux --version
$ logcrux --doctor

--doctor checks the install itself: Python, the local classification model, the state database. Paste its output into any bug report.

Or with pipx:

$ pipx install logcrux

Or plain pip, into whatever environment you're already in:

$ pip install logcrux

Requires Python ≥3.11 and, for the full tool, glibc ≥2.28 (on Alpine/musl it runs without the classification step, see below). That's otherwise the whole install: everything logcrux needs, including its local inference models, ships inside the package. Nothing is downloaded at run time and no network access is required to run it.

If your server's system Python is older (Amazon Linux 2023, RHEL 9, and Ubuntu 22.04 all default to 3.9 or 3.10), uv fetches a matching Python automatically, so uv tool install --python 3.12 logcrux works without any manual interpreter setup. pipx instead uses whatever Python is already on your PATH, so install 3.11+ first (sudo dnf install python3.11 or sudo apt install python3.11) before using it.

Why --python 3.12: without it, on a host with no suitable Python, uv picks the newest Python release, and the runtime logcrux uses for its local classification model publishes no build for the newest Python yet. logcrux still installs and still detects every incident on that Python; it only names some of them less precisely, and says so on stderr. Pinning 3.11 to 3.14 gets the full tool.

supported platforms

Both x86_64 and arm64 are supported, on Linux and macOS:

system Python too old for pip (RHEL-family, openSUSE)

Rocky Linux, AlmaLinux, and Amazon Linux 2023 default to Python 3.9; openSUSE Leap defaults to 3.6. uv tool install --python 3.12 logcrux sidesteps this entirely, since it supplies its own Python. For the pip path, install 3.11 explicitly first:

# Rocky / AlmaLinux / Amazon Linux 2023
sudo dnf install -y python3.11 python3.11-pip
python3.11 -m venv ~/.venvs/logcrux && ~/.venvs/logcrux/bin/pip install logcrux

# openSUSE Leap 15.6
sudo zypper install -y python311 python311-pip
python3.11 -m venv ~/.venvs/logcrux && ~/.venvs/logcrux/bin/pip install logcrux

older & enterprise linux

The blocker on older enterprise distros is glibc, not Python. onnxruntime only ships modern manylinux_2_27/manylinux_2_28 wheels, and below glibc 2.28 the uv installer silently falls back to a musl build, which then can't find a matching onnxruntime wheel either:

By distro family: RHEL/Rocky/AlmaLinux 8+, Ubuntu 20.04+, Debian 10+, Amazon Linux 2023, any current Fedora, and openSUSE Leap 15.3+/SLES 15 SP3+ all clear the glibc 2.28 floor. RHEL/CentOS 7, Amazon Linux 2, Ubuntu 18.04 and older, and SLES 12 do not.

Stuck below glibc 2.28? Run logcrux from outside the old host instead of on it:

ssh oldbox 'cat /var/log/secure' | logcrux
# or a sidecar container on a glibc 2.28+ base (e.g. debian:12-slim)
# with the old host's log directory mounted in

Alpine / musl

onnxruntime publishes no musllinux wheels, so on Alpine logcrux runs without its classification step: plain uv tool install logcrux installs it, every detector works, and incidents are named less precisely. For the full tool use a glibc base image (Debian, Ubuntu, Fedora, or a RHEL-family distro), or analyze a container's logs from outside it:

docker logs <container> | logcrux

run without installing

$ uvx --python 3.12 logcrux /var/log/syslog

Runs logcrux in a throwaway environment and cleans up after. Good for a one-off check on a box you don't want to install anything on.

shell completion

$ logcrux --install-completion    # installs for your current shell
$ logcrux --show-completion       # prints the completion script

Supports bash, zsh, fish, and PowerShell (via Typer).

upgrading

$ uv tool upgrade logcrux        # or: pipx upgrade logcrux / pip install --upgrade logcrux

uninstalling

$ uv tool uninstall logcrux      # or: pipx uninstall logcrux / pip uninstall logcrux

logcrux keeps a small local state database for baseline tracking at ~/.local/share/logcrux/state.db (see config). Remove it manually if you want a clean slate:

$ rm -rf ~/.local/share/logcrux

next

Now see usage for the full command reference.