You are reading Nightly documentation for 0.12.6.dev0+g563af09.

This documentation may describe behavior that differs from Stable.

Open Stable documentation

Documentation version

0.12.6.dev0+g563af09 · Nightly
Stable Beta Nightly

Installation

Installation

Holaryn Agent's external distribution shape is a signed desktop app. Authorized Synergentic
developers and operators may also install the Python package from the private source repository or
an authenticated internal distribution. Python wheels and source archives are not public release
assets.

Requirements

  • Desktop app: a supported OS (Windows, macOS, or Linux) and network access to GitHub for downloads and updates.
  • Authorized Python package: access to the private repository and approved dependency indexes.
    The install scripts bootstrap uv if it is missing, and uv downloads
    and manages the required Python 3.14 for you.
  • From source: Python 3.14 (uv provisions it automatically with uv sync).

Desktop app

The desktop app bundles the agent host, wraps the web UI in a native window with a tray icon, and
updates itself. After the external distribution gate is approved, download the installer from the
public binary-only release repository:

  • Windows: NSIS setup (.exe) or MSI installer.
  • macOS: .dmg disk image.
  • Linux: .deb package or AppImage.

See Desktop app for the window, tray, and menu behavior.

Auto-updates

The desktop app checks GitHub Releases for updates (Help → Check for updates,
or from the tray menu). Updates are cryptographically signed; the app verifies
each update against a public key baked into the app before installing, and
installs only after you consent. Choose Stable, Beta, or Nightly in
Settings → System → Software updates; each channel follows only its own
eligible releases.

Authorized Python package

This section is for people with authorized private-source access. It is not a public distribution
path.

From the private source checkout, create the managed environment and run the CLI:

uv sync --all-extras
uv run holaryn --version

uv run holaryn onboard start

Authorized operators may use the checked-in installer. It downloads the release's Python files
from the private source repository with the GitHub CLI, so sign in first with gh auth login (an
account that can read the repository's releases), or pass a folder of already downloaded files
with --release-dir / -ReleaseDir:

# Windows (PowerShell)
.\scripts\install.ps1

# Linux and macOS
./scripts/install.sh

Pass options (extras, a specific release tag, the native service) directly:

./scripts/install.sh --extras web,hacp --version 0.12.0-beta.1

The installer checks every downloaded file against the release's SHA-256 checksum file, installs
the two Holaryn wheels from those verified files only, and pins every other dependency to the
version and hash in the release's lock. It stops without installing anything if a check fails.
Never install Holaryn by name from a package index (pip install holaryn-agent,
uv tool install holaryn-agent); it is not published to one. See the
install guide for details.

Optional extras

Choose extras with the installer's --extras / -Extras flag (--extras web,fastembed), or
with uv sync --extra <name> in a source checkout:

  • web — installs uvicorn so the browser UI can run. Recommended for every install.
  • fastembed — local semantic embeddings for memory (offline after a one-time model download).
  • voice — local speech-to-text and text-to-speech (Voice).
  • hacp — WebSocket support for connected mode with Holaryn Space.
  • qdrant — Qdrant vector-database backend for memory.
  • postgres / mariadb — shared memory database backends.
  • otel — optional OTLP traces, metrics, and correlated logs.
  • documents — DOCX, XLSX, PPTX, and PDF creation, structural validation, and previews. Included in desktop and official Compose builds.
  • windows-service — kept for compatibility; the Windows service runtime (pywin32) now installs by default on Windows.

You can also install fastembed, voice, qdrant, postgres, mariadb, or otel later with
holaryn memory install-extra <name>, which works inside the desktop app too. It installs the
versions your release locked, each file hash-checked, and installs nothing in a source checkout,
where you run uv sync --extra <name> instead.

Optional Holaryn Space connected mode

Connected mode is opt-in. The persistent host creates its HACP link only when both a wss://
endpoint and a bearer credential are configured; otherwise it runs fully standalone. Install the
hacp extra, obtain a revocable node credential from the Holaryn Space operator, and place the
token in an owner-protected regular file. The stable node-id file must contain the node UUID bound
to that credential.

Linux and macOS:

chmod 600 /secure/path/hacp-token
export HOLARYN_HACP_ENDPOINT="wss://your-tenant.holaryn.space/ws/hacp/"
export HOLARYN_HACP_TOKEN_FILE="/secure/path/hacp-token"
export HOLARYN_HACP_NODE_ID_PATH="/secure/path/hacp-node-id"
holaryn serve

Windows Command Prompt:

icacls "C:\secure\hacp-token" /inheritance:r /grant:r "%USERNAME%:(R)" /grant:r "SYSTEM:(F)"
set "HOLARYN_HACP_ENDPOINT=wss://your-tenant.holaryn.space/ws/hacp/"
set "HOLARYN_HACP_TOKEN_FILE=C:\secure\hacp-token"
set "HOLARYN_HACP_NODE_ID_PATH=C:\secure\hacp-node-id"
holaryn serve

HOLARYN_HACP_TOKEN is also supported for an environment-managed secret and takes precedence over
the file setting. The status command reports only whether a credential is present; it never prints
the token or reads it back to the screen:

holaryn hacp status

The endpoint is shown and stored in plain text, so it must not hold a secret (SA-632): it is read
by the same rule as a provider base URL, with wss:// (ws:// only with
HOLARYN_HACP_ALLOW_INSECURE=1, for local testing), a host, an optional port and a path whose
final slash is kept. A user name, a password, a query or a fragment is refused: the host then
stays standalone and logs which setting to correct, holaryn hacp status prints
endpoint: not shown with the reason and exits with status 2, and the Platform settings page
shows the field empty with the reason under it. The token goes only in HOLARYN_HACP_TOKEN or
HOLARYN_HACP_TOKEN_FILE. If a credential was ever in the endpoint, rotate it.

A refused endpoint saved in the configuration file stays there until you replace it, because it
may be the only copy of a credential: saving the Platform settings while the HACP endpoint field
is empty (it is shown empty) leaves it as it is, and only a corrected endpoint replaces it. To
remove it without a replacement, delete hacp_endpoint from config.json in the state directory
while the host is stopped; an endpoint from HOLARYN_HACP_ENDPOINT is corrected or removed in
the environment.

Authentication or protocol failures are logged by error category and retried with capped backoff;
local Agent work continues. To roll back, remove the endpoint and token settings and restart the
host. No Platform module is imported into the Agent core.

Installing as an OS service

To run the host as a native service that survives reboots (systemd, launchd, or the Windows Service Control Manager):

holaryn service install --platform linux --state-dir /var/lib/holaryn

Use --platform darwin or --platform windows on those systems (Windows requires an elevated PowerShell). The Windows install script can do this in one step with -WindowsService. Details in Running the agent.

Self-hosting with Docker Compose

For a reproducible one-host deployment, the repository includes a hardened Compose stack with a
loopback-only minimal profile, optional automatic TLS, pinned non-root images, durable named
volumes, secret files, health checks, deployment diagnostics, and encrypted backup/restore:

python deploy/compose/manage.py up

Production startup validates the real DNS, certificate-recovery email, and allowed hosts before it
exposes the proxy. See Self-host with Docker Compose before enabling public
ingress or changing a volume.

First run

After installing, verify the command works:

holaryn --version
holaryn --help

For a command-line installation, start or resume the guided first-success path:

holaryn onboard start

For the desktop installer, launch Holaryn; the same guided path opens in the
native window and requires no terminal or configuration-file editing. It
connects one provider/default model, streams a real response, and asks you to
approve one reversible generated-sandbox tool action. See
First-success onboarding for CLI, Compose, source, and
offline/portable paths plus repair and reset instructions.

Upgrading and uninstalling

The desktop app upgrades itself. In an authorized source checkout, update the reviewed branch and
resynchronize the managed environment:

uv sync --all-extras
uv run holaryn --version

Run source commands through uv run unless an approved internal installer has placed holaryn on
the system path. More help is in Troubleshooting.

← Previous Holaryn Agent User Guide Next → Introduction