Enterprise Manual

HYVE Ether OS — Server Edition is a headless, multi-user, network-facing sovereign backend built on a Debian base. It does what any company's internal backend must — directory/authentication, role-based access, data services, file shares, VPN, firewalling, monitoring, and backups — while keeping HYVE's differentiators: fully local AI (no cloud), gated and attested agents, a tamper-evident audit trail, and no phone-home. It is air-gappable end to end.

It inverts three assumptions of the Desktop edition: single owner becomes multi-user with RBAC; loopback-only services move behind an authenticating reverse proxy with TLS; and the kiosk desktop becomes headless system services with a browser admin console.

Every request enters through an authenticating reverse proxy (Caddy on:443, TLS terminated with an internal CA). The proxy forward-authenticates each request to an identity signer, which validates the user's session and mints a short-lived, HMAC-signed identity. Organs (services) stay loopback-bound and additionally verify that signed identity, then authorize the specific action against a role→permission policy. Every decision is sealed to an append-only audit trail.

Identity is provided by a 389 Directory Server LDAP directory federated into Keycloak (the OIDC issuer, PostgreSQL-backed). A default-denynftables firewall exposes only :443, SSH from the LAN, and WireGuard; internal services (LDAP, PostgreSQL, Keycloak, the organs) are never reachable from the network.

Server Edition ships no built-in account. The operator chooses the admin identity and credentials at install. Two identities are provisioned:

1. STEP 01
   The OS admin — a Linux account in the sudo group with password-required sudo and an SSH key for keys-only remote access. Root is locked behind sudo by default. Collected by the installer's users module.
2. STEP 02
   The directory (SSO) admin — a directory user placed in hyve-admins. Their first login enrolls TOTP multi-factor. Provisioned on first boot.

The re-runnable provisioner hyve-server-setup.sh performs both and is also used later to add or rotate an admin (from flags, an answer file, or an interactive console prompt). Answer files carry passwords and are shredded after use.

Users and groups live in the LDAP directory. Keycloak federates them and issues OIDC tokens; multi-factor (TOTP) is enforced for every user. Directory group membership maps to a HYVE role, which the access gate checks per action. The roles, most to least privileged:

Higher roles inherit the reads of lower ones, but siblings do not cross-inherit (an operator cannot read the audit ledger). owner is a local break-glass token that is never accepted over the network.

Add a directory user and place them in the appropriate hyve-* group; their first SSO login enforces MFA enrollment. Rotate or add an admin at any time with the provisioning script. Keycloak realm settings (federation, MFA policy, brute-force protection) are managed through its admin CLI, reachable only from the box or over the VPN.

Two independent trails record activity. The access-decision trail seals every allow/deny (who, what action, which role) to an append-only log that no service account can rewrite or truncate. The kernel auditd layer watches identity, sudo, SSH, firewall, and the HYVE control surface, and is locked immutable so it cannot be silently disabled. Persistent system logging is on by default.

A role-gated Admin & Audit console (reachable at/admin, auditor and admin only) surfaces live service health, directory identity, and the access-decision trail. Auditors see the decision trail; the directory enumeration is admin-only.

PostgreSQL backs Keycloak and provides an application database. File services are provided by authenticated SMB shares, scoped behind the WireGuard tunnel — never exposed to the open LAN. Containers run rootless via Podman.

A scheduled, encrypted restic job captures the directory (LDIF export), the databases, and all configuration on a daily timer, with retention enforced and the plaintext staging shredded after each run. The directory superuser password can be recovered locally over the directory's privileged socket if it is ever lost — no reinstall required.

A default-deny nftables firewall permits only loopback, established connections, ICMP, SSH from the LAN, :443, and WireGuard; file-share ports are open only to the VPN subnet. SSH is keys-only (no passwords, no root login).fail2ban guards SSH, kernel/network sysctl hardening is applied, and services run under systemd sandboxing.

1. STEP 01
   Restart a service: sudo systemctl restart hyve-<iam|signer|depot|console> (or caddy).
2. STEP 02
   Add/rotate an admin: re-run hyve-server-setup.sh.
3. STEP 03
   Run a backup now: sudo systemctl start hyve-backup.service.
4. STEP 04
   Manage identity/MFA: the Keycloak admin CLI, over the VPN or on the box.
5. STEP 05
   Firewall/SSH changes: arm the dead-man's switch first, verify on a fresh connection, then persist.

Server Edition is hardened through independent adversarial review, and we are honest about what is and isn't closed. Known roadmap items include per-service UID separation (to shrink the blast radius of a same-host compromise), a cryptographic hash-chain over the audit trail with an off-box witness, moving the identity issuer to production mode, and off-site backup replication. We do not fake certifications or invent numbers — request the full control mapping and security package with your quote.