You are reading Nightly documentation for 0.12.4.dev0+g50bde75.

This documentation may describe behavior that differs from Stable.

Open Stable documentation

Documentation version

0.12.4.dev0+g50bde75 · 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 after configuring authenticated internal
release access:

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

# Linux and macOS
./scripts/install.sh

To pass options (extras, a specific version, the native service), download the script and run it directly on Windows, or append options after -- on Linux and macOS:

./scripts/install.sh --extras web,hacp --version 1.0.0b1

Optional extras

Add extras in brackets (pip install "holaryn-agent[web,fastembed]") or via the installer's --extras / -Extras flag:

  • 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.

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

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