Sonny ships as a single static binary plus an optional desktop package. This page covers every install path and how to confirm the result. If you just want the fastest route to a first session, use Getting Started .

Version covered
These instructions apply to Sonny 0.12.1. Run sonny version to check what is installed on your machine.

Requirements

  • Building from source needs Go 1.27.1 or newer (go.mod pins go 1.27.1).
  • The Linux release binary and the deb/rpm/apk packages are built with cgo enabled (for the mesh identity resolvers), so they need a glibc-compatible Linux. The macOS and Windows binaries are cgo-free.
  • No recipes are preinstalled. Sonny ships with one embedded recipe (sonny-base); everything else you add yourself through recipe sources .

Pre-built binaries

Every tagged release publishes an archive per OS/architecture:

sonny_<version>_<os>_<arch>.tar.gz    # linux, darwin
sonny_<version>_windows_<arch>.zip    # windows

Download the archive for your platform, extract it, put sonny on your PATH, then check the version:

sonny version

Obtain release assets through your authorized CodePros distribution channel. Verify each file against the signed checksums.txt supplied with that release. See Licensing and access .

apt (Debian / Ubuntu) 

curl -fsSL https://apt.codepros.org/codepros-keyring.gpg \
  | sudo tee /usr/share/keyrings/codepros-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/codepros-archive-keyring.gpg] https://apt.codepros.org stable main" \
  | sudo tee /etc/apt/sources.list.d/codepros.list
sudo apt update
sudo apt install sonny

sonny-desktop is a separate native package for graphical workstations. It depends on the exact same version of sonny, so installing or upgrading the desktop app cannot silently pair it with a different client-protocol build.

sudo apt install sonny-desktop

rpm (Fedora / RHEL / Rocky / Alma) 

sudo rpm --import https://rpm.codepros.org/RPM-GPG-KEY-codepros
sudo dnf config-manager --add-repo https://rpm.codepros.org/codepros.repo
sudo dnf install sonny
sudo dnf install sonny-desktop

The repository serves x86_64 and aarch64 packages, and its metadata is signed (repo_gpgcheck=1) with the same key as the apt repository.

What installing a package actually does

Installing a package (rather than dropping a tarball binary on PATH) does more than copy a file:

  • Creates a system user and group named sonny (home /var/lib/sonny, no login shell) for server mode (sonny serve, the sonny-mesh unit).
  • Runs sonny init --system once to seed system-wide configuration.
  • Lays out /usr/local/share/sonny/packs, /etc/sonny (including a mesh/ subtree for mTLS material), /var/lib/sonny, /var/log/sonny, /run/sonny, and /var/cache/sonny.
  • Installs the sonny-mesh systemd unit — not enabled and not started. You provision CA/cert material under /etc/sonny/mesh/ first, then run systemctl enable --now sonny-mesh yourself. This is deliberate: with no certificate material and no authz.yaml, there is nothing the unit could start safely with. See Running the mesh .

The postinstall step is idempotent: reinstalling or upgrading re-runs it safely.

Purge is destructive on Debian/Ubuntu
apt purge sonny-desktop deletes each local account’s profile sessions/ and journal/ directories under ~/.local/share/sonny/profiles/{personal,org}/<profile>/. It keeps the sonny base package, desktop settings, keys, caches and control.db. A package script cannot discover a custom XDG_DATA_HOME, so delete profile data there by hand when a full purge is intended. RPM has no purge transaction: removal always preserves user data.

From source

Source builds require CodePros authorization and access to the private repository. The following commands are for an existing authorized checkout.

# In your authorized Sonny source checkout:
make install                        # PREFIX defaults to /usr -> /usr/bin/sonny
make install PREFIX=$HOME/.local    # user install, no sudo
make go-install                     # go install ./cmd/sonny ./cmd/sonny-api into $GOBIN

make build-windows cross-compiles a Windows binary (WINARCH=amd64 by default; override with make build-windows WINARCH=arm64).

What make install does

Beyond copying binaries to $(DESTDIR)$(BINDIR) (default /usr/bin), a plain make install with no DESTDIR does two extra things:

  • Shadow clean — if an older sonny earlier on PATH would shadow the one it just installed, the stale copy is removed. Set NO_SHADOW_CLEAN=1 to skip this.
  • Daemon restart — if a sonny-mesh service is already running, it is restarted so the new binary takes effect. Set NO_DAEMON_RESTART=1 to skip.

Pass DESTDIR=/tmp/stage to build a staged tree instead of installing on the current machine (what packagers do); both extra steps are skipped in that case.

First run 

sonny init
sonny config path

sonny init creates your config, data and cache directories and seeds models.yaml with an example model-category catalog — but only if models.yaml doesn’t already exist. It also creates models.d/ in the config directory for drop-in catalog fragments. Running it again is safe: it will not overwrite a models.yaml you have edited unless you pass --force.

sonny config path prints every standard path Sonny resolves on this host: config dir, data dir, cache dir, state dir, and which per-project config file (if any) was picked up. It is the first command to run when something seems to be reading the wrong file.

The XDG layout after a clean first run:

DirectoryContents
$XDG_CONFIG_HOME/sonny/models.yaml, models.d/, pack-sources.yaml, tui.yaml
$XDG_DATA_HOME/sonny/sessions.db, discovered recipes, catalogs/
$XDG_CACHE_HOME/sonny/cloned recipe repositories, tui.log

Verifying the install 

sonny version
sonny version --sbom | head -3
sonny version --third-party-licenses | head -3

sonny version also takes --license and --sbom (CycloneDX 1.5 JSON) for compliance review.

There is no -v flag
sonny -v fails with Error: unknown shorthand flag: 'v' in -v. Use sonny --version or sonny version.

Upgrading

Re-run whichever install method you used the first time. A fresh make install or package upgrade overwrites the binary in place. Your configuration, recipes and sessions live outside the install path — confirm with sonny config path — so upgrading never touches them.

When you upgrade past v0.10.69, the catalog registry layout changes: each installed catalog version moves to <data-dir>/catalogs/<id>/versions/<version>/. The first run of a newer build performs the migration itself. Downgrading is unsupported — an older binary cannot read a versions/ registry, so it treats every registry catalog as unreadable. If you must go back, stop every Sonny process, back the directory up, and move the versions back by hand.

Uninstalling 

make uninstall    # honors the same PREFIX/DESTDIR you installed with

This removes the installed binaries only. Config, data and cache directories — and, for a package install, the sonny system user plus /etc/sonny, /var/lib/sonny and friends — are left in place. Remove them by hand for a clean slate.

Windows notes

The CLI ships for Windows with a ConPTY-backed terminal. Windows binaries are cgo-free, so make build-windows cross-compiles without a C toolchain. There is no deb/rpm/apk equivalent for Windows — use the release zip or go install.

Troubleshooting installation

SymptomCauseFix
sonny version prints an older version right after make installShadow clean was skipped (NO_SHADOW_CLEAN=1, or a DESTDIR= staged build)which -a sonny, remove the earlier copy, reinstall
Error: unknown shorthand flag: 'v' in -vThere is no short version flagUse sonny --version
sonny-mesh unit never starts on its ownPostinstall installs but deliberately does not enable or start itProvision /etc/sonny/mesh/{node.crt,node.key,ca.crt} and authz.yaml, then systemctl enable --now sonny-mesh
models.yaml doesn’t reflect edits you expected sonny init to makesonny init only seeds models.yaml the first timeEdit it directly, or delete it and re-run sonny init

More symptoms and their fixes are in Troubleshooting .

See also