# Run Edera

At the end of this guide, you will have launched an isolated zone and run a workload inside it.

## Launch a zone [Permalink for this section](https://on.edera.dev/run-edera/#launch-a-zone)

Launching a zone typically takes less than a minute. If it takes longer, check logs with `sudo journalctl -u protect-daemon -n 50`.

```bash
sudo protect zone launch -n test-zone --wait
sudo protect zone list
```

Expected output:

```
┌───────────┬──────────────────────────────────────┬───────┬──────────────┬──────────────────────┐
│ name      ┆ uuid                                 ┆ state ┆ ipv4         ┆ ipv6                 │
╞═══════════╪══════════════════════════════════════╪═══════╪══════════════╪══════════════════════╡
│ test-zone ┆ 1aa92875-eafa-47c9-ba31-f1e63e50079d ┆ ready ┆ 10.75.0.2/16 ┆ fdd4:1476:6c7e::2/48 │
└───────────┴──────────────────────────────────────┴───────┴──────────────┴──────────────────────┘
```

A zone in `ready` state is running and available.

## Run a workload [Permalink for this section](https://on.edera.dev/run-edera/#run-a-workload)

Launch an interactive shell inside the zone:

```bash
sudo protect workload launch \
  --zone test-zone \
  --name alpine-shell \
  -t -a \
  docker.io/library/alpine:latest sh
```

Once inside, run `uname -r` to confirm you’re running in an isolated zone with its own kernel:

```bash
uname -r
# Expected: 6.18.18
```

Type `exit` to leave the shell.

Want to see zone isolation in action? [docs.edera.dev](https://docs.edera.dev/) has guides for launching multiple zones and verifying that workloads are isolated from each other.

The setup script below is intended for demo and evaluation use only and requires **Ubuntu 24.04** or above. It bootstraps a single-node cluster on your Edera-protected EC2 instance. Use your own Kubernetes setup (EKS, kubeadm, etc.) in any other context.

ℹ️

Before continuing, make sure you ran the `k8s-prepare.sh` script from the [Prepare Your VM](https://on.edera.dev/prepare-your-vm/#preparing-for-kubernetes-optional) step **before** installing Edera. If you skipped it, you will see a `kubelet.service not found` error.

## Bootstrap Kubernetes [Permalink for this section](https://on.edera.dev/run-edera/#bootstrap-kubernetes)

Run the bootstrap script on your EC2 instance. It initializes a single-node cluster using the Edera CRI and installs Cilium as the CNI.

```bash
/bin/bash -c "$(curl -fsSL https://on.edera.dev/scripts/k8s-bootstrap.sh)"
```

This takes a few minutes. When it completes, verify the node is ready:

```bash
kubectl get nodes
# Expected: STATUS Ready
```

## Apply the Edera RuntimeClass [Permalink for this section](https://on.edera.dev/run-edera/#apply-the-edera-runtimeclass)

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

## Run a workload [Permalink for this section](https://on.edera.dev/run-edera/#run-a-workload)

```bash
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: edera-test
  namespace: default
spec:
  runtimeClassName: edera
  containers:
  - name: alpine
    image: alpine:latest
    command: ["sh", "-c", "uname -r && sleep 3600"]
  restartPolicy: Never
EOF
```

Wait for the pod and verify it’s running in an isolated zone:

```bash
kubectl wait --for=condition=ready pod/edera-test --timeout=120s
kubectl logs edera-test
# Expected: 6.x.y-edera
```

Use the `protect` CLI to display the Zone (pod sandbox) and Workload (container) corresponding to the pod created above:

```bash
sudo protect zone list
```

Expected output:

```
┌────────────────────────┬──────────────────────────────────────┬───────┬───────────────┬──────┐
│ name                   ┆ uuid                                 ┆ state ┆ ipv4          ┆ ipv6 │
╞════════════════════════╪══════════════════════════════════════╪═══════╪═══════════════╪══════╡
│ k8s_default_edera-test ┆ c9307c61-a753-463d-a1b8-499dfea17479 ┆ ready ┆ 10.0.0.102/32 ┆      │
└────────────────────────┴──────────────────────────────────────┴───────┴───────────────┴──────┘
```

```bash
sudo protect workload list
```

Expected output:

```
┌───────────────────────────────┬──────────────────────────────────────┬──────────────────────────────────────┬─────────┐
│ name                          ┆ uuid                                 ┆ zone                                 ┆ state   │
╞═══════════════════════════════╪══════════════════════════════════════╪══════════════════════════════════════╪═════════╡
│ k8s_default_edera-test_alpine ┆ 3e668170-bff9-4353-b0e3-76892fc78380 ┆ c9307c61-a753-463d-a1b8-499dfea17479 ┆ running │
└───────────────────────────────┴──────────────────────────────────────┴──────────────────────────────────────┴─────────┘
```

## Troubleshooting [Permalink for this section](https://on.edera.dev/run-edera/#troubleshooting)

### Daemon not running after reboot [Permalink for this section](https://on.edera.dev/run-edera/#daemon-not-running-after-reboot)

- Check logs: `sudo journalctl -u protect-daemon -n 50`

- Verify the KVM device is present: `ls /dev/kvm` (if missing, hardware virtualization may be disabled on the host)

- Verify Xen booted: `ls /proc/xen` (if missing, the machine booted into the stock kernel instead of Xen)
- Verify UEFI boot: `[ -d /sys/firmware/efi ] && echo UEFI || echo BIOS`

### Instance unreachable after reboot [Permalink for this section](https://on.edera.dev/run-edera/#instance-unreachable-after-reboot)

Wait 1-2 minutes after reboot. If still unreachable, check the [EC2 serial console](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-serial-console.html) for boot errors.

Wait 2-3 minutes — Xen boot takes longer than a normal boot. If still unreachable, check the [EC2 serial console](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-serial-console.html) for boot errors.

Common daemon errors:

- **“no viable machine identifiers”** — The instance may be in BIOS boot mode. Terminate and relaunch with a UEFI-compatible AMI.
- **Xen not present** (`/proc/xen` missing) — GRUB booted into the stock kernel instead of Xen. Check `sudo grub-editenv list` and verify the saved entry matches a Xen menu entry.

### License already active on another machine [Permalink for this section](https://on.edera.dev/run-edera/#license-already-active-on-another-machine)

If the daemon fails with a `license activation failed: could not register new machine to license` error and your license key is present on the machine, the license is most likely still active on a previous machine.

To fix this:

1. Go to [on.edera.dev](https://on.edera.dev/) and log in
2. Find the active machine under your license and click **Deactivate**
3. Restart the daemon: `sudo systemctl restart protect-daemon`

One license key can only be active on one machine at a time. Always deactivate before moving to a new machine.

### Missing license key [Permalink for this section](https://on.edera.dev/run-edera/#missing-license-key)

If the daemon fails with a `license activation failed: could not register new machine to license` error and no license key file exists on the machine, inject it manually:

```bash
sudo mkdir -p /var/lib/edera/protect
echo $EDERA_LICENSE_KEY | sudo tee /var/lib/edera/protect/license.key
sudo systemctl restart protect-daemon
```

For additional help, [file an issue on GitHub](https://github.com/edera-dev/on/issues).

## Clean up [Permalink for this section](https://on.edera.dev/run-edera/#clean-up)

Deactivate your node at [on.edera.dev](https://on.edera.dev/) before terminating so you can reuse your license on another instance.

Terminate the instance and delete the security group:

```bash
aws ec2 terminate-instances --instance-ids <INSTANCE_ID>
aws ec2 delete-security-group --group-id <YOUR_SG_ID>
```

If you used the installer script, you may also use a teardown script. You can view the full usage details in the [edera-dev/learn repository](https://github.com/edera-dev/learn/tree/main/getting-started/edera-on-installer#ec2-teardownsh).

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/edera-dev/learn/refs/heads/main/getting-started/edera-on-installer/scripts/ec2-teardown.sh)"
```