<!-- Markdown version of https://www.kuzys.com/install.html, generated from the HTML by tools/make-md.py. Index: https://www.kuzys.com/llms.txt -->

# From zero to *a working suite.*

The kuzys tools install from PyPI, or as native packages for Debian 13 and Fedora 45. Pick one way, install what you need, and each tool can check its own setup.

## Choose a way to install

From PyPI you get the commands and the Python libraries, in a virtual environment, on any system with Python 3.11 or later. The Debian and Fedora packages add what a machine that runs the daemons needs: their systemd units and the external programs the tools call. On macOS, Homebrew has kuzychat, kuzywrap and kuzymount so far, built from source.

## Install the tools

### Python / PyPI

Python 3.11 or later, with virtual-environment support. Create an environment and install the three primary tools in it, without sudo:

```console
$ python3 -m venv ~/.venvs/kuzys
$ . ~/.venvs/kuzys/bin/activate
$ python -m pip install 'kuzychat[xmpp]' kuzymail kuzytrig
```

The `xmpp` extra brings kuzychat's XMPP transport. pip installs the commands and the daemons' programs, but it does not register systemd services, configure accounts or install the external programs the tools call: GnuPG for OpenPGP in kuzychat; isync, notmuch and msmtp for kuzymail. To run the daemons as services, use the Debian or Fedora packages.

Everything else in the [suite](https://www.kuzys.com/tools.md) installs the same way, by name: `kuzysignal`, `kuzywrap` (one package for every runtime), `kuzylaunch[tui]`, `kuzyquota`, `needlecast`, `kuzybackup`, `kuzydir`, `kuzycal`, `kuzymount`, `kuzysign`. kuzysignal also needs signal-cli and Java, which pip does not provide. parfit is not on PyPI: the PyPI project of that name is an unrelated scikit-learn package, so install ours as a Debian or Fedora package.

### Debian / APT

Debian 13 (trixie) or a distribution built on it, on amd64: the repository is published for that architecture only. Debian 14 (forky), still in development, has its own suite: write `forky-testing` in place of `trixie-testing` below. Fetch the archive signing key, then describe the repository to apt:

```console
$ sudo curl -fsSL https://apt.kuzys.com/kuzys-archive-keyring.asc \
    -o /usr/share/keyrings/kuzys-archive-keyring.asc

$ sudo tee /etc/apt/sources.list.d/kuzys.sources <<'EOF'
Types: deb
URIs: https://apt.kuzys.com
Suites: trixie-testing
Components: main
Signed-By: /usr/share/keyrings/kuzys-archive-keyring.asc
EOF

$ sudo apt update
```

Then install the three primary tools, each with its daemon. Installing `kuzys-archive-keyring` too keeps the signing key up to date through apt itself:

```console
$ sudo apt install kuzys-archive-keyring kuzychat kuzymail kuzytrig
```

kuzytrig installs its two services without starting them, so that an operator turns them on once, on purpose:

```console
$ sudo systemctl enable --now kuzytrigd.service kuzytrig-worker.service
```

Everything else in the [suite](https://www.kuzys.com/tools.md) installs the same way, by package name: `kuzysignal`, `kuzywrap-claude` (or the wrapper for your runtime), `kuzylaunch`, `kuzyquota`, `needlecast`, `kuzybackup`, `kuzydir`, `kuzycal`, `kuzymount`, `kuzysign`, `parfit`.

### Fedora / RPM

Fedora 45 on x86_64, from the kuzys testing repository. Configure it and its signing key as described at [rpm.kuzys.com](https://rpm.kuzys.com/), then install the three primary tools, each with its daemon:

```console
$ sudo dnf install kuzychat kuzymail kuzytrig
```

As on Debian, kuzytrig's two services stay off until an operator enables them:

```console
$ sudo systemctl enable --now kuzytrigd.service kuzytrig-worker.service
```

Everything else in the [suite](https://www.kuzys.com/tools.md) installs the same way, with the same package names as on Debian, except `kuzysign`: it needs a version of pyHanko that no accepted Fedora repository provides yet, so there is no Fedora package for it for now. kuzysignal needs signal-cli 0.14.10 or later from a separate repository: its README explains which one, and what trusting it means.

### macOS / Homebrew

macOS 26 on Apple silicon, the only setup tested so far; Intel Macs are untested. The [kuzys tap](https://gitlab.com/kuzys/homebrew-tap) on GitLab has kuzychat, kuzywrap and kuzymount; kuzymail and kuzytrig are not in it yet. The tap is not on GitHub, so Homebrew needs its URL, and current Homebrew loads formulae from a third-party tap only once you trust it; on an older Homebrew that has no `brew trust`, run `brew update` first:

```console
$ brew tap kuzys/tap https://gitlab.com/kuzys/homebrew-tap.git
$ brew trust kuzys/tap
$ brew install kuzys/tap/kuzychat
```

The formula builds kuzychat from source, so the first install takes a few minutes. It includes the XMPP transport with OMEMO, OpenPGP through GnuPG, and HTTP upload. It does not register kuzychatd as a service or configure accounts: run the daemon yourself, or under a launchd agent you manage.

kuzywrap installs from the same tap, with `brew install kuzys/tap/kuzywrap`. It brings the wrapper for each runtime, and tmux, but not the runtimes themselves: install Claude Code, Codex or OpenCode separately. Nothing starts when it is installed. On macOS the per-user services it creates are launchd agents; creating and starting one from the Homebrew install has not been tested yet.

kuzymount installs from the same tap too, but it mounts through sshfs on macFUSE, which the formula cannot install for you: macFUSE is a cask, and sshfs-mac comes from another third-party tap, gromgit/fuse, which Homebrew also loads only once you trust it. Install them first, then kuzymount:

```console
$ brew install --cask macfuse
$ brew tap gromgit/fuse
$ brew trust gromgit/fuse
$ brew install gromgit/fuse/sshfs-mac
$ brew install kuzys/tap/kuzymount
```

Before the first mount, launch macFUSE once, from `/Library/Filesystems/macfuse.fs/Contents/Resources/macfuse.app`, and enable it in System Settings > General > Login Items & Extensions > File System Extensions; `kuzymount doctor --profile NAME` checks the setup. The formula does not register kuzymountd as a service: run it as your user, with `kuzymountd --domain user`, and persistent mounts become LaunchAgents. The full mount cycle has been tested on a Mac from the release's source, not yet from the Homebrew install.

Other tools join the tap one at a time, once each is tested on a Mac; the tap's README lists what is there.

## Check the setup

Each primary tool can diagnose its own configuration and report what is missing, in JSON or in plain words:

```console
$ kuzytrig doctor --profile ada --human
$ kuzychat doctor --profile ada --account home
```

## Where to go next

Each project keeps its documentation in its repository, written for people and for agents, and the Debian packages install it under `/usr/share/doc/<package>`. The tool pages here explain the design: [kuzychat](https://www.kuzys.com/kuzychat.md), [kuzymail](https://www.kuzys.com/kuzymail.md), [kuzytrig](https://www.kuzys.com/kuzytrig.md). Questions and bugs go to the issue tracker of each project on [GitLab](https://gitlab.com/kuzys).
