> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kvelden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Private Virtual Appliance

> Deploy Kvelden Enclave inside your own infrastructure as a pre-packaged OVA — your network perimeter, your keys, your data.

## Overview

The **Private Virtual Appliance** is Kvelden Enclave packaged as an **OVA (Open Virtual Appliance)** that you deploy on your own VMware infrastructure. The entire Enclave stack — application, database, and runtime — is pre-installed and pre-configured inside the virtual machine image. No source code, no Dockerfiles, and no build toolchain are involved.

The appliance operates as a sealed unit. Kvelden provides the OVA file and a licence key; your IT team provisions and operates it like any other enterprise virtual appliance (similar to a firewall or security gateway).

<Info>
  You run the appliance entirely — **Kvelden has no access to it, its data, or its
  keys.** Your master key lives in your KMS/HSM or in the appliance's local master
  key. Note that the appliance itself (which you operate) can decrypt Envelope and
  personal files to serve downloads and run the workflows you enable (DLP, signing);
  for content that even your own appliance can never read, use **Zero-Knowledge /
  ZK-Strict rooms**, where keys stay only on your users' devices.
</Info>

***

## What Kvelden provides vs what you manage

| Kvelden provides                     | You manage                                                           |
| ------------------------------------ | -------------------------------------------------------------------- |
| OVA image with Enclave pre-installed | VMware infrastructure (ESXi / vSphere)                               |
| Licence key and activation           | VM provisioning, networking, and firewall rules                      |
| OVA updates for new releases         | DNS and TLS certificate                                              |
| Support and patch advisories         | Storage backend (S3, NFS, or local disk)                             |
|                                      | KMS configuration (AWS KMS, Thales CipherTrust, or platform-managed) |
|                                      | Backup and disaster recovery                                         |

***

## System requirements

### Hypervisor host

| Component  | Requirement                                                                      |
| ---------- | -------------------------------------------------------------------------------- |
| Hypervisor | VMware ESXi 7.0+ (ESXi 8.0+ / vSphere 8 recommended), KVM/QEMU, or VirtualBox 7+ |
| Network    | 1 Gbps (10 Gbps recommended)                                                     |

### Sizing profiles

The OVA ships at the **Minimum** profile (8 vCPU / 16 GB). To grow, **increase the
VM's vCPU and RAM in the hypervisor and reboot** — the appliance detects the new
capacity on boot and **re-tunes itself automatically** (Postgres memory, the DLP
and text-extraction services, and worker concurrency all scale to the tier). No
manual configuration. File contents never transit the appliance (browsers upload
and download directly against your S3-compatible storage), so sizing is driven by
metadata, audit history, and content-scanning (DLP) volume — not by file sizes.

| Profile                      | vCPU | RAM    | Disk        | Sized for                                                      |
| ---------------------------- | ---- | ------ | ----------- | -------------------------------------------------------------- |
| Minimum (OVA default)        | 8    | 16 GB  | 100–250 GB  | evaluation / PoC, small teams, light DLP                       |
| **Recommended — production** | 8    | 32 GB  | 250 GB      | up to \~2,500 users, \~10 M file records, steady DLP           |
| Large                        | 16   | 64 GB  | 500 GB NVMe | **millions of files, thousands of users**, heavy DLP           |
| X-Large                      | 32   | 128 GB | 1 TB NVMe   | very large orgs, high upload concurrency, long audit retention |

Use **SSD/NVMe** storage — the metadata database, the audit log, and the job queue
are I/O-sensitive (and the disk is LUKS-encrypted). The tier is selected by total
RAM; verify the applied tier from the console `health` command.

<Note>
  The virtual disk is thin-provisioned — it consumes only what is actually
  used. The main long-term disk consumers are the metadata database and audit
  history; container logs are rotation-capped. The disk can be extended
  without reinstalling: grow the virtual disk in the hypervisor, then extend
  the LVM volume inside the appliance. Current usage is shown by the console
  `health` command.
</Note>

### Network

* Outbound access to your KMS endpoint (AWS KMS or Thales CipherTrust)
* Outbound access to your S3-compatible bucket for file storage
* Outbound SMTP to your mail relay for notifications and invitations
* Inbound HTTPS (port 443) from your users' browsers or a reverse proxy

<Note>
  The appliance validates its licence **entirely offline** and requires no inbound
  access from Kvelden. There is no phone-home.
</Note>

**Network adapter.** The OVA ships with a **VMXNET3** adapter mapped to the
`VM Network` label; map it to a routable port group at deploy time. The guest is
adapter- and interface-agnostic, so it also works with E1000 if you change it.

**Addressing — DHCP first (zero-config).** By default the appliance comes up on
**DHCP** and is immediately reachable at `https://<leased-ip>`; the leased address
is shown live at the VM console login prompt. To assign a **static IP** you have
two options:

* **At deploy time** — fill in the vApp *Customize template* fields (see
  [First‑run setup](/deployment/appliance/first-run)).
* **Any time from the console** — `network set <iface> <ip/cidr> <gateway> <dns>`.

<Warning>
  **Outbound SMTP on port 587 is frequently blocked** by corporate firewalls. If
  a mail test times out, use your provider's alternate submission port — for AWS
  SES that is **2587** (STARTTLS) or **465 / 2465** (implicit TLS). The block is
  in the network, not the appliance.
</Warning>

***

## Deployment steps

<Steps>
  <Step title="Request the OVA">
    Contact [hello@kvelden.com](mailto:hello@kvelden.com) or your account manager. Kvelden will provide a signed OVA download link and a licence key scoped to your organisation.
  </Step>

  <Step title="Deploy the OVA on VMware">
    1. In **vSphere Client** (vCenter/ESXi), right-click your cluster or host → **Deploy OVF Template**; or in **VMware Workstation/Fusion**, **File → Open**. (VMware Workstation shows a benign *"OVF conformance"* prompt for any third-party OVA — click **Retry**.)
    2. Enter the OVA download URL or upload the file.
    3. Map the `VM Network` adapter to a routable port group.
    4. On the **Customize template** step, optionally set a static **IP / gateway / DNS / hostname / NTP** — or leave blank to use **DHCP**.
    5. Power on the VM once deployment completes.
  </Step>

  <Step title="Complete first-run setup">
    On the VM console the appliance shows its **IP address**, a **one-time console password**, and a **first-signup code**. In a browser, open `https://<appliance-ip>` and:

    * **Enrol an SSH public key** (required before the first account — the appliance ships with no SSH access).
    * **Create the first account** using the first-signup code.
    * **Set the hostname/FQDN and install a TLS certificate** under **Admin → Network & TLS**.
    * **Activate the licence** at **`/license`**.

    See [First‑run setup](/deployment/appliance/first-run) and [Web TLS certificate](/deployment/appliance/tls) for the full walkthrough.
  </Step>

  <Step title="Configure platform infrastructure">
    Log in to the **Admin Panel** and complete the infrastructure setup:

    * **KMS** — Connect a KMS for file encryption key wrapping. See [KMS Configuration](/deployment/appliance/kms).
    * **Storage** — Configure where encrypted file data is stored. See [Storage Configuration](/deployment/appliance/storage).

    Both are required before users can upload files.
  </Step>

  <Step title="Invite your first users">
    Once infrastructure is configured, navigate to **Admin → Users → Invite** and add your organisation's users. The appliance is ready.
  </Step>
</Steps>

***

## Licensing

The appliance runs a **30-day full-featured trial** from first boot. To license
it beyond the trial, upload the licence file issued by your Kvelden account team
at **`/license`**. See [Licensing & Activation](/deployment/appliance/licensing)
for the full process, renewal, and expiry behaviour.

***

## Time and clock synchronisation

The appliance runs on **UTC**; the web UI displays times in each user's local
timezone automatically. An accurate clock is required for KMS/TLS operations and
for licence activation, so keep the appliance synchronised:

* **NTP (recommended):** on the console, `time ntp <server>` — for example your
  internal domain controller (`time ntp dc01.corp.local`). Most networks that
  block *public* NTP still allow internal NTP.
* **Hypervisor sync:** on VMware/ESXi and KVM the appliance's guest tools keep
  the clock synchronised with the host automatically, including after
  suspend/resume.
* **Manual (air-gapped):** where no NTP is reachable, set it with
  `time set <YYYY-MM-DD> <HH:MM:SS>` in **UTC**.

Check the current state any time with `time show`. If AWS/TLS or licence
operations fail unexpectedly, verify the clock first — an appliance whose clock
has drifted is the most common cause.

***

## TLS configuration

The appliance ships with a self-signed certificate so the web UI is reachable
immediately (browsers show a warning). Before inviting users, set a hostname and
install a trusted certificate under **Admin → Network & TLS** — either upload a
CA-issued chain or generate a self-signed cert for client-trust distribution.

See [Web TLS certificate & hostname](/deployment/appliance/tls) for the full
guide.

***

## Updates

Kvelden releases OVA updates for new features and security patches. You receive an advisory email with a download link for each release.

**Update process:**

1. Take a VM snapshot before updating (rollback point)
2. Download the new OVA from the link in the advisory
3. In the appliance Admin Panel, go to **Admin → System → Update** and upload the OVA package
4. The appliance applies the update and restarts — typically under 5 minutes of downtime
5. Verify the version number in **Admin → System → About** after restart

<Warning>
  Always snapshot the VM before applying an update. Database migrations run automatically on startup and cannot be reversed without restoring the snapshot.
</Warning>

***

## Post-deployment checklist

* [ ] OVA deployed and VM powered on
* [ ] Domain name configured and resolving to appliance IP
* [ ] Appliance clock verified (`time show`) and NTP configured
* [ ] TLS certificate installed (not self-signed)
* [ ] [Licence activated](/deployment/appliance/licensing) at `/license`
* [ ] [KMS configured](/deployment/appliance/kms) and connection tested
* [ ] [Storage backend configured](/deployment/appliance/storage) and connection tested
* [ ] First admin user invited and logged in
* [ ] VM snapshot taken after successful first-boot configuration