Server configuration

Production configuration is explicit. Unknown HIKYO_* variables produce a warning, while malformed security settings stop startup.

Server flags

Do not use --dev for real secret material or any non-loopback deployment.

Production network baseline

When origin is unset, Hikyo derives https://<listen> with native TLS and http://<listen> otherwise. Proxy mode should set the public HTTPS origin explicitly because the private listener cannot infer it.

Native TLS is the default direct-deployment posture. Hikyo validates the pair at startup, rejects expired or mismatched files, warns within 14 days of expiry, polls for replacements every 10 seconds, and also reloads on SIGHUP. A bad replacement leaves the last known-good certificate live and increments hikyo_tls_reload_failures_total.

Proxy mode requires trusted CIDRs when the plaintext public listener is not loopback. The list names proxies, not browser client networks. Operational routes never exist on the public router; keep the operational bind private.

MCP endpoint

The MCP endpoint is disabled by default. These settings control its exact public exposure:

Production requires an HTTPS HIKYO_EXTERNAL_ORIGIN. Development permits plain HTTP only on a loopback origin. Requests without an Origin header are accepted for non-browser MCP clients. An allowed browser origin does not enable CORS response headers, so it is an additional request check rather than a cross-origin browser API grant.

Treat every configured MCP client and its model provider as a recipient of MCP tool results. The five read tools expose bounded key definitions, environments, configuration cells, caller-owned pending changes, and revision metadata. Results may include non-secret configuration plaintext and caller-owned non-secret draft plaintext. Secret values and secret draft material are never returned. Tool calls accept only an existing workload or automation service-account bearer and repeat current authorization on every page.

For Helm and Compose deployment, client profiles, least-privilege grants, rotation, public validation, and failure diagnosis, use the MCP operations runbook.

Security response headers

Every public response carries the same set, refusals and API errors included:

Cross-Origin-Opener-Policy is same-origin-allow-popups rather than same-origin because the browser UI runs the identity-provider and workspace handoff ceremonies in popups that navigate to another origin and then close themselves; strict same-origin leaves those windows stranded open. The popups are opened with noopener and answer over a same-origin BroadcastChannel, so nothing reaches back through window.opener either way.

Permissions-Policy names no WebAuthn feature on purpose: publickey-credentials-get and publickey-credentials-create default to self, which is what passkey sign-in and reauthentication need.

HSTS

Strict-Transport-Security: max-age=31536000 is emitted when both hold:

• HIKYO_EXTERNAL_ORIGIN has the https scheme (explicitly set, or derived as https://<listen> because a native TLS pair is configured), and
• the external origin’s browser-visible host is not loopback.

The scheme of the configured public origin decides, not which process holds the certificate, so a reverse proxy terminating TLS in front of the plaintext listener emits it too, including when that internal listener binds to loopback. A plain-http external origin and any loopback external-origin host never emit it. A development instance must not pin localhost to https in the browser’s HSTS store for every other project on the machine.

If your reverse proxy already adds Strict-Transport-Security, do not also let it rewrite or append: two headers, or one with a shorter max-age, is a policy the browser resolves by rules you did not intend. Either let Hikyo emit it and pass the header through untouched, or strip Hikyo’s at the proxy and own the value there, including includeSubDomains or preload, which Hikyo deliberately does not send because they commit hostnames it does not serve.

Operational metrics

/metrics on the operational listener serves Prometheus text exposition (text/plain; version=0.0.4) using the official Prometheus Go client. Scraping requires no sidecar, external service, or egress. It is plaintext and unauthenticated by design — keep the operational bind private and scrape it from the host or a trusted network.

Alongside the retention and TLS gauges it exposes RED-style request metrics keyed by a closed surface class — auth, hierarchy, values, revisions, delivery, scim, admin, and a fail-closed other. There are no raw paths and no identifiers in any label, so cardinality is bounded no matter the traffic.

Counters cover all /api/v1/* traffic. Unmatched paths, unsupported methods, and CORS preflights use the closed other class.

Under --dev the server also emits a per-request access log (method, surface class, status, duration) at debug level. The production handler starts at Info, so these Debug request lines are absent unless debug logging is enabled.

Adapter egress is public-address-only by default. To approve a private Forgejo origin, point HIKYO_ADAPTER_EGRESS_POLICY_FILE at a JSON object whose keys are exact canonical bare HTTPS origins and whose values are CIDR lists:

{
  "https://git.internal.example": ["10.40.0.0/24", "fd42:40::/64"]
}

The file is read and validated only at startup. Origins must have no path, query, fragment, or user information. An exception applies only when both the configured origin and every dialed IP match the same entry. It does not disable TLS verification, redirects remain refused, and DNS answers are checked again when connecting.

Root key

Choose exactly one source:

• --root-key-file PATH, including a service-manager credential path.
• HIKYO_ROOT_KEY, the weakest delivery tier.

The key must be 64 hexadecimal characters. Keep it outside the datastore and outside the backup identity’s custody store.

Datastore

SQLite uses HIKYO_DB=sqlite:/absolute/path/hikyo.db. Ensure the service user owns the parent directory and no other user can read it. The write pool uses one connection and the WAL read pool is capped at four, so concurrent readers cannot open unlimited connections or retain unbounded WAL snapshots.

Remote PostgreSQL must name one host explicitly and use sslmode=verify-full or sslmode=verify-ca. Multi-host DSNs and remote plaintext connections are refused. The connection-pool maximum defaults to 10. Set HIKYO_PG_POOL_MAX to a positive 32-bit integer for larger hardware, or put pool_max_conns=N in the PostgreSQL DSN. The environment variable takes precedence when both are present. Hikyo logs the effective pool maximum once at startup for either datastore.

Authentication cost controls

Tune these together under representative load. A malformed value is a startup error, not a fallback to the default.

Update notifications

The server checks Hikyo’s public GitHub releases at most once every six hours. Only signed-in principals holding instance-config@instance see a toast and a badge on the profile icon. Dismissing the toast keeps the badge until the installed version catches up. Checks never download or install software, and a release-source outage does not stop the server.

HIKYO_DEV_ADMISSION_PER_IP_PER_MINUTE is for development only. A production server refuses to start when it is present.

Backup policy

Recipients without a destination are a configuration error. When neither is configured, migrations continue but record a loud skip with no recovery archive.

Client variables

The CLI channel is local machine state, separate from the server-wide setting:

hikyo update channel stable
hikyo update channel nightly
hikyo update channel off
hikyo update check

Stable and nightly release artifacts start on their matching channel. Direct source builds stay on off; install a published artifact before selecting a release channel. Interactive command invocations refresh release metadata before dispatch at most once per 24 hours and offer an in-place binary update when one is available; hikyo update check refreshes immediately.

Prefer flags for visible, one-off target changes and --token-file for machine credentials. See contexts and targets.