# Install Edera

5 min read · Intermediate

---

**Using EderaON?** Follow the [EderaON install guide](https://on.edera.dev/install-edera/) instead. The setup process is different.

This guide walks you through installing Edera on a Linux instance using either the Xen (default) or KVM (Early Access) hypervisor backend.

## Choose a backend

|  | Xen | KVM |
| --- | --- | --- |
| Recommended for | Production workloads; maximum security and performance | Teams already running KVM; lower barrier to entry |
| Host kernel | Edera-built and maintained kernel | Your existing distribution kernel |
| Reboot required | Yes | No |
| Bootloader modified | Yes | No |
| Nested virtualization (cloud VMs) | Not required | Required if not on bare metal |
| Hardware requirement | Broad; supports PV and PVH | VT-x or AMD-V |

If you’re unsure, **use Xen**: it’s the default and the production-ready path.

## Validate your system

Before installing, run [`edera-check`](https://docs.edera.dev/reference/edera-check/) to confirm your system meets all requirements:

```bash
docker run --pull always --pid host --privileged \
  ghcr.io/edera-dev/edera-check:stable preinstall
```

All **Required** checks should pass. If anything fails, address the issue before proceeding. See the [edera-check reference](https://docs.edera.dev/reference/edera-check/) for details on each check.

### Prerequisites

- A Google Artifact Registry (GAR) key from Edera (`key.json`). Don’t have one? Contact [support@edera.dev](mailto:support@edera.dev).
- Docker or nerdctl installed on the target node with root or sudo access.

### Step 1: Log in to the registry

Run the following commands **on the target node**. Copy your `key.json` to the node first if needed.

```bash
docker login us-central1-docker.pkg.dev -u _json_key --password-stdin < key.json
```

### Step 2: Run the installer

```bash
docker run --privileged \
  --env 'TARGET_DIR=/host' \
  --volume '/:/host' \
  --volume "$HOME/.docker/config.json:/root/.docker/config.json" \
  --pid host \
  --net host \
  us-central1-docker.pkg.dev/edera-protect/staging/protect-installer:${TAG}
```

Set `TAG` to the release version you want to install. See [Edera release notes](https://docs.edera.dev/reference/release-notes/) for current versions.

The installer reboots the node when complete. Wait 1-2 minutes for it to come back online.

### Step 3: Verify installation

```bash
sudo protect --version
sudo systemctl status protect-daemon
sudo protect zone list
```

Expected output from `protect zone list`:

```text
No zones have been launched.
```

### KVM prerequisites

- A Google Artifact Registry (GAR) key with access to the Edera installer image. Don’t have one? [Contact the team](/content/contact/index.html).
- Docker installed on your target node with root or sudo access.
- Docker authenticated to GAR on the target node: `sudo docker login us-central1-docker.pkg.dev`.
- A current, non-EOL LTS kernel. `edera-check` validates this. See [kernel.org](https://www.kernel.org/category/releases.html) for LTS status.
- Hardware virtualization enabled (VT-x or AMD-V) and `/dev/kvm` accessible. Verify: `ls -la /dev/kvm`.

### Nested virtualization

ℹ️

Nested virtualization carries a performance penalty. Bare metal is the preferred deployment target for KVM.

If you’re running inside a VM, the outer hypervisor must expose KVM to the guest. For AWS EC2, see [Amazon EC2 nested virtualization](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-nested-virtualization.html). Most general-purpose EC2 instance types do **not** support nested KVM.

### Step 1: Run the installer

Run the following command **on the target host**:

```bash
docker run --privileged \
  --env 'TARGET_DIR=/host' \
  --env 'HYPERVISOR=kvm' \
  --volume '/:/host' \
  --volume "$HOME/.docker/config.json:/root/.docker/config.json" \
  --pid host \
  --net host \
  us-central1-docker.pkg.dev/edera-protect/staging/protect-installer:${TAG}
```

Set `TAG` to the release version you want to install. See [Edera release notes](https://docs.edera.dev/reference/release-notes/) for current versions.

### Step 2: Verify installation

```bash
protect help
sudo systemctl status protect-daemon
sudo protect zone list
```

## Kubernetes

These steps apply to both backends.

### Confirm nodes are back online

```bash
watch kubectl get nodes
```

### Apply the Edera RuntimeClass

```bash
kubectl apply -f https://public.edera.dev/kubernetes/runtime-class.yaml
kubectl get runtimeclass
```

Expected output:

```text
NAME    HANDLER   AGE
edera   edera     1d
```

### Label nodes for Edera workloads

The Edera RuntimeClass includes a `nodeSelector` that requires nodes to be labeled with `runtime=edera`:

```bash
kubectl label nodes <node-name> runtime=edera
```

### Test with a Pod

```bash
kubectl apply -f kubernetes/test-workload.yaml
kubectl wait --for=condition=ready pod/edera-test-pod -n edera-test --timeout=300s
kubectl get pods -n edera-test
```

## Troubleshooting

### Node unreachable after Xen install

Expected. The installer reboots the node. Wait 1-2 minutes then reconnect and run `sudo protect --version` to confirm it’s running.

### `/dev/kvm` not found (KVM)

If `/dev/kvm` is missing at install time, the installer fails during preflight. If it disappears after install, the daemon fails to start:

```text
ERROR protect-daemon: failed to initialize core runtime: missing /dev/kvm
```

To recover:

1. Check what’s missing:

```bash
ls -l /dev/kvm
lsmod | grep -E '^kvm_(intel|amd)'
egrep -c '(vmx|svm)' /proc/cpuinfo
```

2. If the KVM module isn’t loaded:

```bash
sudo modprobe kvm_intel    # or kvm_amd
sudo systemctl restart protect-daemon
```

3. If the CPU doesn’t expose `vmx` or `svm`, enable hardware virtualization in BIOS/UEFI.
4. If you’re inside a VM, the outer hypervisor isn’t exposing nested KVM. See [nested virtualization](https://docs.edera.dev/guides/install/edera-installer/#nested-virtualization) above.

### Verify Edera services

```bash
sudo systemctl status protect-daemon
sudo protect zone list
sudo protect --version
```

### Kubernetes troubleshooting

- Check pod details: `kubectl describe pod edera-test-pod -n edera-test`
- Check logs: `kubectl logs edera-test-pod -n edera-test`
- Verify RuntimeClass: `kubectl get pod edera-test-pod -n edera-test -o=jsonpath="{.spec.runtimeClassName}"`

## What’s next

- **[Monitor your workloads](https://docs.edera.dev/guides/observability/)** with Prometheus and Grafana
- **[Learn about GPU support](https://docs.edera.dev/guides/gpu/)** for AI/ML workloads (Xen only)
- **[KVM architecture overview](https://docs.edera.dev/technical-overview/architecture/kvm/)** for background on how the KVM and Xen backends compare
- **[Kernel customization](https://docs.edera.dev/guides/kernel/)** for custom kernels and boot parameters

Last updated on 2026-07-24