Guide

Nitro Host Setup

Prepare an EC2 parent instance so it can run Capsule enclave applications reliably.

Instance Requirements

Platform

AWS x86_64

Instance Type

*.xlarge+

Enclave Support

Enabled

OS

Amazon Linux 2023

Enclave-capable instance types

Most *.xlarge and larger metal/virtualized instances support Nitro Enclaves. Common choices: m5.xlarge, c5.2xlarge, r5.xlarge, m6i.xlarge. The instance must be launched with "Nitro Enclave" support enabled in EC2 settings.

Setup Steps

Complete these steps on a fresh EC2 instance with Nitro Enclave support enabled.

01

Install Nitro Enclaves packages

Install the AWS Nitro Enclaves CLI and allocator service first, before you start preparing Docker images.

Install Nitro CLI and allocator

# Amazon Linux 2023
sudo dnf install -y aws-nitro-enclaves-cli aws-nitro-enclaves-cli-devel

# Add your user to the ne group
sudo usermod -aG ne $USER
sudo usermod -aG docker $USER

# Enable services
sudo systemctl enable nitro-enclaves-allocator.service
sudo systemctl enable docker

02

Reboot once, then reserve memory as early as possible

After package install and group changes, reboot the host. On the fresh boot, set allocator memory and hugepages before you start memory-heavy services, builds, or large Docker pulls.

Write /etc/nitro_enclaves/allocator.yaml

# Example: reserve 12 GiB and 4 vCPUs for enclaves
sudo tee /etc/nitro_enclaves/allocator.yaml >/dev/null <<'EOF'
memory_mib: 12288
cpu_count: 4
EOF

memory_mib and cpu_count define the maximum host-side pool available to enclaves. Individual Capsule runs must fit inside that pool.

03

Inspect hugepage state and activate the allocator

Check the current page pool, enable the allocator service, and verify the reservation after it applies.

Inspect and apply the reservation

# Show current hugepage state
grep -E 'MemTotal|HugePages_Total|HugePages_Free|Hugepagesize' /proc/meminfo
ls /sys/kernel/mm/hugepages
for d in /sys/kernel/mm/hugepages/hugepages-*; do
  echo "$(basename "$d") nr=$(cat "$d/nr_hugepages") free=$(cat "$d/free_hugepages")"
done

# First activation
sudo systemctl enable --now nitro-enclaves-allocator.service

# If allocator.yaml changes later
sudo systemctl restart nitro-enclaves-allocator.service

# Verify again after the service runs
grep -E 'HugePages_Total|HugePages_Free|Hugepagesize' /proc/meminfo

04

Install Docker

Docker is required for building and running capsule images.

Install Docker

# Amazon Linux 2023
sudo dnf install -y docker
sudo systemctl start docker
sudo systemctl enable docker

# Verify
docker --version

05

Install capsule-cli

Download the CLI binary and verify the installation.

Install capsule-cli

# Download latest release
curl -LO https://github.com/sparsity-xyz/nova-enclave-capsule/releases/latest/download/capsule-cli-x86_64-unknown-linux-musl.tar.gz
tar xzf capsule-cli-x86_64-unknown-linux-musl.tar.gz
sudo mv capsule-cli /usr/local/bin/

# Verify
capsule-cli --version

06

Verify after reboot and before enclave launch

After every reboot, confirm that Docker, allocator state, and hugepages are still correct before you try to launch an enclave.

Verify complete setup

# Reboot
sudo reboot

# After reboot, verify:
# 1. Docker running
docker info

# 2. Nitro Enclaves allocator running
sudo systemctl status nitro-enclaves-allocator

# 3. Hugepages allocated
grep -E 'HugePages_Total|HugePages_Free|Hugepagesize' /proc/meminfo

# 4. User in correct groups
groups  # should include: ne docker

# 5. capsule-cli available
capsule-cli --version

Hugepage Configuration Details

Use these commands when you need to inspect or adjust the page pool directly at the Linux layer.

2 MiB Hugepages

Set and verify

# Example: 6144 pages * 2 MiB = 12288 MiB
echo 6144 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages

# Verify
cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
grep Hugepagesize /proc/meminfo

1 GiB Hugepages

Set and verify

# Example: 12 pages * 1024 MiB = 12288 MiB
echo 12 | sudo tee /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages

# Verify
cat /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages

Troubleshooting Hugepages

Set hugepages right after reboot: this is the safest moment because large page reservations are easier before the host becomes busy.
Not enough hugepages: increase memory_mib in /etc/nitro_enclaves/allocator.yaml, restart the allocator service, and verify the counters again.
Allocation fails: the host may not have enough contiguous memory left for the requested page pool.
Enclave fails to start with a memory error: ensure the free hugepage pool is large enough for memory_mb in your manifest and remember that the host allocator is the hard ceiling.

Automated Setup with CloudFormation

Use the included CloudFormation template for a fully automated host setup.

Deploy the CloudFormation stack

# The template is in the repository at:
# aws/cloudformation/infrastructure.yml

aws cloudformation create-stack \
  --stack-name capsule-host \
  --template-body file://aws/cloudformation/infrastructure.yml \
  --capabilities CAPABILITY_IAM

The CloudFormation template provisions an EC2 instance with Nitro Enclave support, Docker, and all prerequisites pre-configured. Review the template parameters for customization options.

Security Considerations

Instance Network

Use a VPC with security groups that only expose the ports your application needs. The enclave itself has no direct network access — all traffic passes through the host.

IAM Roles

If your capsule uses S3 storage, the host EC2 instance needs an IAM role with appropriate S3 permissions. The enclave accesses IMDS through the egress proxy.

Host Security

The host is outside the enclave trust boundary. Keep the host patched and minimize the software surface. The enclave protects against host compromise for data in use.

Getting Started View Architecture