Frequently asked questions

Answers describe this codebase's behaviour. Where a question depends on your commercial terms or a future work package, it says so instead of guessing.

Platform and architecture

Is my transaction data ever sent to Hokeka? No. The Edge evaluates locally and records each evaluation on its own Edge Ledger. Only decision records leave the site — ids, decision, score and rule ids — plus aggregate metrics. Amounts, PAN hashes, customer data and reason text stay on the Edge. The normative rules are in the data residency contract.

Where does the Edge run? On hardware you control (your data centre or private cloud). It is a Java service plus a Rust rule kernel, its own PostgreSQL 16 ledger, and Aerospike for velocity buckets.

What exactly is "the cloud" then? The Hokeka Control Plane (API, decision-record ingest, alerts/cases/SAR/CTR workflow, billing, AI advisory layer) and the Console SPA. Hokeka staff install and operate it; you never install it.

Can the Console read transaction details if the data never leaves the Edge? Yes — over a tunnel the Edge opens outbound (mTLS WebSocket on 443). Hokeka never dials into your network, and the read is gated by your support-access consent (a maker-checker setting), logged in your data access log. It is a live read, not a copy into the cloud.

What if the Edge is offline? It keeps evaluating from its last bundle and records to its ledger; decision records queue in an outbox and ship when connectivity returns. Nothing is lost across a restart or an outage.

Installation and deployment

Which operating systems are supported? Ubuntu 22.04+, Debian 12, RHEL/Rocky/Alma 9, SLES/openSUSE 15 SP5, Arch, Alpine 3.19 (x86_64 for native), and Windows Server 2019/2022 (container only — Aerospike has no native Windows build). Full matrix: All installation methods.

Container or native? Container is the default and is identical on every platform. Choose native only when containers are prohibited: it installs Temurin JRE 21, Aerospike CE and PostgreSQL 16 on the host, all bound to loopback and firewalled.

Do I need internet access? Only outbound TCP 443: to the Control Plane (ongoing), to the artifact host at install/upgrade time, and to Docker Hub in container mode. Inbound is limited to 8443/tcp from your own API nodes.

Can I install with no internet at all? Yes — mirror the release, or place the artifacts beside the installer and pass --offline; for native mode also supply a verified Aerospike package. Signature verification is fail-closed, so an air-gapped estate must mirror SHA256SUMS.asc (or explicitly opt out on a trusted mirror). See Air-gapped installs.

How do I know the installer is genuine? Artifacts are checked against a SHA256SUMS file that is GPG-signed by the Hokeka release key, and the public key is pinned inside the installer. A tampered origin fails before anything is installed. Aerospike packages are additionally pinned through a checksum manifest that is itself verified against the signed sums.

Why does Windows need a reboot? Docker Desktop needs WSL2. The installer requests the reboot and registers a one-time resume entry so the install continues automatically after you sign back in.

Can several nodes share a database? Yes — that is an Edge Site: --ledger-url / --ledger-user / --site-id on each node, with the password in HOKEKA_LEDGER_PASSWORD. Note that velocity counters are per site; across sites they are only shared if you replicate Aerospike (Enterprise XDR).

Evaluation behaviour

Why did I get HOLD? HOLD is the fail-closed answer. The usual causes: the node is not approved yet, the ledger cannot be written, or the licence is suspended for an unpaid invoice. GET /edge/status names the reason — see the decision states.

What is a "licence suspension"? If the oldest invoice is 14 days past due (configurable), the PSP's Edge licence is suspended and nodes answer HOLD / LICENCE_SUSPENDED until it is paid. The Console stays open; payment lifts it immediately.

Do you block transactions when a plan limit is exceeded? No. Included transactions in a plan are a pricing threshold. Evaluation never stops on volume; the excess is billed as overage.

How are velocity rules scoped? Aerospike buckets are keyed per card and site (<pan_hash>:<hour>:<site_id>). A node reads only its own site's buckets.

Can the Edge call an AI model? No. The Edge never calls the AI layer and never holds the key — transaction data must not leave the site. AI is advisory on the Control Plane (sanctions, SAR drafting, rule suggestions) and always degrades to deterministic rules on timeout, error or low confidence.

Security and compliance

How is transport secured? TLS 1.3 terminates inside the Edge process; there is no plaintext listener and no sidecar. The process refuses to start without its keystore. Optional mutual TLS authenticates your API nodes.

What is pinned at enrolment? The node generates X25519 (encryption) and Ed25519 (signing) keypairs locally; public halves are pinned at activation and shown as fingerprints in the Console. Bundle pulls and metrics use those keys.

How long is data kept? 5–25 years, set by a PSP admin in Console → Settings → Data Retention (minimum and default 5, FATF R.11). Changes need a second reviewer; a reduction takes effect 30 days after approval. Records under legal hold are exempt from purge.

Who can see my data? Your own users, within their roles. Hokeka support access is opt-in, requires a stated reason and is recorded in your data access log, per request.

Is the Console protected against session theft? Sessions are Secure, HttpOnly, SameSite=Strict cookies; a revoked session is detected on the next API call and the Console redirects to sign-in. CSRF protection is disabled in this deployment (the API is cookie-authenticated with strict same-site cookies), which is documented in the architecture notes.

Operations

How do I upgrade? Re-run the installer (or the one-liner with --upgrade, or install.ps1 -Version). Upgrades do not overwrite your keystore or your ledger.

What must I back up? The Edge Ledger (multi-year system of record) and the node identity (data/). If both are lost, the node must be enrolled again with a new edge id; the old id returns 409.

What happens if the ledger disk fills? The node cannot record evaluations, so it answers HOLD (LEDGER_UNAVAILABLE). Size the disk for at least five years and alert on usage — the sizing table is in Requirements.

How do I remove a node? Uninstall it and revoke it in the Console, so its identity can never be reused.

Where do I report a problem? support@hokeka.com with the edge id, install method and the failing command. Never send secrets, keystore passwords or transaction data.