Getting started

Build Hikyo from source and run a local evaluation instance with its embedded web UI.

This guide creates a local, loopback-only evaluation instance. Hikyo is still in 0.x, so the supported installation path is currently a source build rather than a stable release artifact.

At the end, you will have the Hikyo binary, an embedded browser UI, a local SQLite database, and one administrator account.

Prerequisites

Go 1.27.3 or newer within the Go 1.27 line.
Node.js 26.7.0, matching the repository’s .nvmrc.
Corepack 0.35.0 with pnpm 11.24.0.

1. Clone and build

git clone https://github.com/Hikyo-Org/Hikyo.git
cd Hikyo
npm install --global --ignore-scripts corepack@0.35.0
corepack enable
corepack install --global pnpm@11.24.0
pnpm --dir clients/ts install --frozen-lockfile
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
mkdir -p bin
go build -tags ui -o ./bin/hikyo ./cmd/hikyo

The ui build tag embeds the Vite output in the Go binary. A build without that tag remains useful for API-only development but does not serve the browser app.

2. Start an evaluation instance

install -d -m 0700 "$PWD/.hikyo-runtime"
./bin/hikyo server --dev --cli-socket "$PWD/.hikyo-runtime/hikyo.sock"

Development mode binds to 127.0.0.1:8080, creates hikyo-dev.db, and writes a mode-0600 root key beside it. Keep the database and key together: losing the key makes the encrypted data unrecoverable. Open the browser through http://localhost:8080: WebAuthn requires a hostname even when the listener binds to an IP address.

On Linux and macOS, the owner-only socket directory lets the CLI authenticate the local server by operating-system identity before sending credentials over loopback HTTP. The directory must have mode 0700; the server refuses wider permissions. Keep it out of version control. Windows CLI connections require HTTPS rather than this Unix-socket evaluation path.

Check the server from another terminal:

curl --fail http://127.0.0.1:8081/healthz

3. Create the first administrator

Run this on the same host and from the same directory as the development server:

./bin/hikyo admin --dev create \
  --username admin \
  --output-file ./hikyo-admin-authority

The leading group-level --dev selects the same development datastore and root key defaults as the server. Use the same prefix for backup and restore when working with an evaluation instance. Production remains the default without it.

The output file is created with mode 0600. The authority is single-use and expiring; it establishes a password but creates no session.

Display the authority on your terminal, then run Hikyo’s credential-establishment command:

cat ./hikyo-admin-authority
./bin/hikyo account establish-credential \
  --instance http://localhost:8080 \
  --as admin \
  --socket "$PWD/.hikyo-runtime/hikyo.sock"

Confirm the instance origin and local socket, paste the authority at the controlling-terminal prompt, and choose a password of at least 12 characters that is not in the bundled common-password list. Neither value crosses argv, environment variables, or a pipe. Delete hikyo-admin-authority after the command succeeds, then open the local sign-in page.

Evaluation only

--dev is deliberately convenient, not a production configuration. It uses local plaintext HTTP and a zero-config SQLite datastore in its own development trust domain. Follow the self-hosting guide before exposing Hikyo beyond loopback.

4. What the first administrator does not hold yet

The first administrator holds the operator template at instance scope and, once the instance has adopted its own configuration, the admin template on the Hikyo organisation it creates. Two capabilities are deliberately outside every template and must be granted explicitly, to yourself or anyone else:

Capability	Where	Unlocks
`audit-read`	an organisation, project or environment	that scope’s audit trail (Audit, Project audit)
`instance-directory`	the instance	Remotes: the directory of connected instances

Grant them in the browser under Members (organisation scope) and Instance members (instance scope), or from the CLI after hikyo login:

hikyo access grant add --principal <your principal id> --capability audit-read --org <org id>
hikyo access grant add --principal <your principal id> --capability instance-directory --instance-scope

Every grant to yourself ends your current session. Sign in again and present your second factor before continuing.

The Hikyo organisation and its Hikyo <instance id> project are the instance’s own configuration. They refuse machine access, deployment adapters, SCIM provisioning and additional projects by design, so those pages are absent there. Create an organisation of your own for your projects, as your first project does.

Next steps

Complete your first project to create environments and a validated value.
Review installation options before choosing a longer-lived setup.
Read core concepts before declaring production keys and environments.
Move to the self-hosting baseline before using real secret material.

Getting started

PrerequisitesCopy Anchor Link

1. Clone and buildCopy Anchor Link

2. Start an evaluation instanceCopy Anchor Link

3. Create the first administratorCopy Anchor Link

4. What the first administrator does not hold yetCopy Anchor Link