Installation

Hikyo is in 0.x development and has no published stable release yet. Signed nightly prereleases are published; build from source for evaluation. Do not treat a development build or a nightly as a supported production release.

Choose an installation pathCopy Anchor Link

Nightly container imagesCopy Anchor Link

The nightly workflow publishes the same signed release binaries in a non-root distroless image for linux/amd64 and linux/arm64:

docker pull ghcr.io/hikyo-org/hikyo:nightly
docker run --rm ghcr.io/hikyo-org/hikyo:nightly --version

:nightly follows the newest successfully verified container publication. Each image also has the corresponding GitHub prerelease version as a tag, without the leading v. Find versions in GitHub releases. The container job can be retried independently if the GitHub release succeeded but image publication failed.

For a repeatable deployment, pin the image digest reported by the nightly workflow instead of the moving tag. Docker and Kubernetes use the same reference:

image: ghcr.io/hikyo-org/hikyo@sha256:<verified-image-digest>

The image digest is signed with GitHub OIDC by the nightly workflow. See the nightly container verification runbook for the verification command and retry behavior. These signatures are separate from the signed archive inventory. Pulling the image does not provision the database, root key, or authenticated runtime bundle. Follow the manual deployment runbook for Compose and Helm inputs. The image has no shell.

Native packages after a signed releaseCopy Anchor Link

Published releases include local-install packages for Linux amd64 and arm64: Debian (.deb), RPM (.rpm), Alpine (.apk), and Arch Linux (.pkg.tar.zst). Download the complete release bundle first and verify it against recovery-authorized trust with the release’s pinned verify-bundle.sh. Follow the release verification runbook; do not install a package copied out of an unverified or draft bundle.

After verification, install the matching local file. These examples show amd64 names for version 1.0.0:

sudo apt install ./hikyo_1.0.0_amd64.deb
sudo dnf install --nogpgcheck ./hikyo-1.0.0-1.x86_64.rpm
sudo apk add --allow-untrusted ./hikyo_1.0.0_x86_64.apk
sudo pacman -U ./hikyo-1.0.0-1-x86_64.pkg.tar.zst

--nogpgcheck and --allow-untrusted disable native repository signatures, not Hikyo’s verification. The preceding signed-bundle check is mandatory; hosted Linux repositories and their package-index keys are intentionally not published yet. For arm64, package filenames use arm64 (Debian) or aarch64 (RPM, APK, and Arch).

Each package installs only /usr/bin/hikyo and /usr/share/doc/hikyo/LICENSE. It does not create configuration, generate keys, install a service, or start a server.

After a stable release’s protected tap PR is merged, macOS users can install the same macOS archive bytes through the Homebrew convenience channel:

brew install --cask hikyo-org/tap/hikyo

Homebrew does not verify Hikyo’s pinned signing root. It authorizes the tap/cask and verifies the archive SHA-256 recorded in that cask; compromise of the tap could replace the verification instructions, key, URL, and checksum together. Use the complete signed-bundle verification flow above when the Hikyo-root guarantee is required. The Homebrew path is convenient distribution, not an official fail-closed installer.

Unsigned development snapshotsCopy Anchor Link

Every successful trusted main build attaches a 14-day hikyo-development-<commit> artifact to its GitHub Actions run. It contains Linux, macOS, and Windows archives for x86_64 and arm64, plus checksums and an unsigned-development warning. GitHub may require a signed-in account to download Actions artifacts.

Use a snapshot only for evaluation. Its commit is immutable and its checksums detect download corruption, but it has no signed release manifest, official installer, upgrade promise, or production support. The online release ceremony defines the path from built bytes to an official Hikyo release.

Local evaluationCopy Anchor Link

Use the source build with hikyo server --dev. Development mode creates its SQLite database and root key in the working directory and listens only on 127.0.0.1:8080.

This path is intended for learning the product. It is not suitable for real secret material or network exposure.

Production preparationCopy Anchor Link

A production-like deployment needs decisions that an installer cannot make for you:

1. Choose SQLite or PostgreSQL.
2. Place the 32-byte root key outside the database backup.
3. Configure native TLS, or terminate HTTPS at a trusted reverse proxy with exact CIDRs.
4. Configure encrypted exports and run a restore drill.
5. Record the exact source commit used to build the binary.

Production boot also requires the authenticated offline release bundle, the separately pinned operator public key and durable installation state. The installer places verified binaries; it does not supply instance-specific backup proof or operator private custody. Follow the manual installation runbook for native, Compose and Helm inputs. Helm requires separate prepopulated public artifact and writable installation-state PVCs. These are retained across pod replacement and database recovery. Official signed bundle publication is still required before the first production release can start.

Hikyo fails closed when these boundaries are missing. Continue with the self-hosting baseline and server configuration.

Platform supportCopy Anchor Link

Source builds follow Go’s supported host platforms. Unsigned development snapshots and signed nightlies cover Linux, macOS, and Windows on x86_64 and arm64. Stable downloads do not exist until the first stable release is published.

The server is designed to run as one binary. The browser UI is embedded when the binary is built with the ui build tag.

What to read nextCopy Anchor Link

• New evaluation: Getting started.
• Existing checkout: Build from source.
• Deployment planning: Self-hosting baseline.
• Runtime settings: Server configuration.