Heimdal Intelligence Appliance

This article walks you through installing the Heimdal Intelligence Appliance (HIA) on a new virtual machine, completing first-time browser setup, and running the first-use checks before sending feedback. Follow the sections in order.

Before you begin

Arrange the following before starting:

• A test environment that meets the VM requirements below.
• Heimdal connection details, if you will collect live data.
• The intended entity scope for testing.
• The coordinator's stated feedback destination.

For a new installation, always use the latest main branch. Only use an older pinned commit when you are explicitly reproducing a historical test.

Repository access

The GitHub repository is private. Each tester needs their own GitHub account and a repository invitation.

1. Accept the invitation while signed in to that account.
2. Open the repository in your browser to confirm access.
3. If the repository is unavailable, resolve access before attempting installation.

Git authentication on the VM

Authenticate Git on the VM using your organization's approved SSH setup or HTTPS token method.

• A GitHub website password is not an HTTPS Git credential. Use a personal access token with access to this repository and the minimum required read permissions, subject to your organization's policy.
• Enter credentials only at the authentication prompt or in an approved credential manager.
• Being signed in to GitHub in your laptop browser does not authenticate Git on the VM.

Alternative: reviewed source package

Instead of using Git on the VM, the coordinator can supply the exact reviewed source package and a checksum through an approved channel. Verify the checksum and follow the package's guarded extraction helper. This avoids needing Git credentials on the VM. Do not extract over an existing installation.

Step 1: Prepare the VM

Operating system

Ubuntu Server 24.04 or higher (currently accepted LTS releases: 24.04 and 26.04) with systemd, accurate time, a stable IP address and DNS, and administrator sudo access.

Sizing (evaluation planning point)

These are planning figures, not measured capacity guarantees. Local AI is optional and affects capacity.

Storage

• Mount the intended persistent filesystem at /data with a persistent mount configuration.
• Check its identity, free space, and that it survives a reboot.
• The installer does not partition or format a disk.
• A root-disk evaluation is an explicit alternative, not the normal storage design.

Network access

• Inbound (management): allow SSH and browser HTTPS from the test team. Initial browser ports are HTTPS 443 and HTTP redirect 80. Keep the unclaimed first-setup page restricted to trusted administrators.
• Outbound: allow access to the required package/container sources, Heimdal API services, and any enabled enrichment, identity, and delivery services. See the outbound connectivity reference.
• Docker, PostgreSQL, Redis, and local AI endpoints must not be exposed as public application services.

Host platform

The documented host baseline is x86-64. ARM64 is used in development and requires its own full installation acceptance. Choosing Proxmox or VirtualBox as the host does not remove the guest architecture and capacity checks.

Step 2: Download the latest source

The commands below download the latest main available at installation time and record its exact commit. There is no fixed release hash to replace manually.

(
  set -euo pipefail
  sudo apt-get update
  sudo apt-get install -y git python3 ca-certificates curl openssl tar coreutils
  HIA_SOURCE_DIR="$HOME/hia-rc1-source"
  test ! -e "$HIA_SOURCE_DIR"
  sudo test ! -e /opt/heimdal-intelligence
  git clone --branch main --single-branch https://github.com/dantehavershem/Heimdal-Intelligence-Appliance.git "$HIA_SOURCE_DIR"
  HIA_SOURCE_COMMIT="$(git -C "$HIA_SOURCE_DIR" rev-parse origin/main)"
  git -C "$HIA_SOURCE_DIR" checkout --detach "$HIA_SOURCE_COMMIT"
  test "$(git -C "$HIA_SOURCE_DIR" rev-parse HEAD)" = "$HIA_SOURCE_COMMIT"
  printf 'Downloaded HIA main commit: %s\n' "$HIA_SOURCE_COMMIT"
  sudo mv "$HIA_SOURCE_DIR" /opt/heimdal-intelligence
)

Keep in mind:

• If any step fails, resolve it before continuing. Do not delete an existing source directory or appliance to make the command pass.
• Keep the checkout unchanged once installation starts, including during a resume.
• Git authentication runs as your normal account; installation uses sudo.
• Do not copy another appliance's .env, credentials, private keys, database, or runtime directories.

Step 3: Run the preflight check and install

3.1 Preflight check

From the source directory, run the check first:

cd /opt/heimdal-intelligence
sudo bash scripts/install_hia.sh --check --install-docker

Read the result and resolve any reported problems.

3.2 Installation

After a successful preflight, run the applying installation as a separate command:

sudo bash scripts/install_hia.sh --install-docker

The installer presents a fresh-install confirmation.

Installer flags

Do not use historical version-specific installers or INSTALL_UPDATE.sh as a substitute for a fresh installation.

What the installer creates

The installer creates independent secrets, data directories, the manifest-driven database, a bootstrap HTTPS certificate, and 19 normal services. It creates no default administrator account or tenant API credential. See the detailed installer guide for each stage, optional flags, state, and recovery.

If the installation is interrupted

1. Inspect the reported cause.
2. Resume with the same source and configuration using --resume, keeping the original storage and model choices.

A completed installation is not an update or resume target. Do not erase guard files or database directories to bypass a refusal.

Step 4: First browser setup

1. Open https://<VM-IP-or-DNS>/. Check the bootstrap certificate with the administrator and arrange trusted TLS for normal use.
2. On Secure initial setup, create your own administrator account and password.
3. Connect Heimdal using the correct PROD/RC environment and credential domain, or choose Configure later. A deferred connection does not require reinstalling.
4. Review the connection's discovered entities. Adopt or map the intended entities and configure Collection Scope.
   • A connection determines credentials.
   • An entity owns data.
   • An Operational View selects the entities to analyze.
5. Create the team's users and entity permissions. Test with a restricted account as well as an administrator.
6. Let collection run. Review collection progress, source coverage, errors, and timestamps before interpreting empty dashboards.
7. Configure trusted certificates, authentication, mail, retention, and backups as appropriate using the administration guide.

Step 5: First-use exercise

Work through the following to confirm the appliance is functioning:

1. Open Endpoint Inventory and inspect a known authorized device.
2. Open Cyber Operations and review the entity scope and coverage.
3. Run a simple report, save it under a test name, reopen it, export it, and add it to a dashboard.
4. Follow the PowerBI example.
5. Verify that a restricted account cannot see another entity's data.

Step 6: Send feedback

Use the release verification checklist. Record:

• The exact source or package identity
• Architecture
• Test date
• Expected and actual result
• Sanitized evidence

Send feedback to the coordinator's stated destination.

Troubleshooting access errors

When you hit an access error, first identify which layer is failing:

• Repository permissions
• Git authentication
• VM connectivity
• HIA sign-in

Keep in mind:

• An HIA API 401 is not proof that reporting is absent.
• An empty chart is not proof that collection succeeded.

Related articles

• Detailed installer guide
• Outbound connectivity reference
• Administration guide
• Release verification checklist
• Navigation map