Reference

CLI Reference

capsule-cli — build and run Nova Enclave Capsule applications.

Global Options

Flag	Description
-v, --verbose	Increase logging verbosity. Can be repeated (`-vv`) for more detail.
-V, --version	Print version information and exit.
-h, --help	Print help information.

capsule-cli build

Package a Docker application image into a Nova Enclave Capsule release image.

Usage

capsule-cli build [OPTIONS]

Flag	Default	Description
-f, --file <PATH>	capsule.yaml	Path to the manifest file. Use `-` to read from stdin.
--pull	false	Always pull source images before building, even if they exist locally.

What build does

01

Load and validate manifest

Parse capsule.yaml, resolve image references, validate all fields.

02

Amend source image

Inject /sbin/capsule-runtime and /etc/capsule/capsule.yaml into the app image.

03

Build EIF

Run nitro-cli build-enclave in an ephemeral container to produce the Enclave Image File.

04

Package into Capsule Shell

Append the EIF and manifest to the Capsule Shell base image. Tag the result as the target image.

Examples

Build examples

# Default manifest file
capsule-cli build

# Custom manifest
capsule-cli build -f my-service.yaml

# Force pull source images
capsule-cli build --pull

# Read manifest from stdin
cat capsule.yaml | capsule-cli build -f -

# Verbose output
capsule-cli build -v -f capsule.yaml

capsule-cli run

Execute a pre-built Nova Enclave Capsule image on a Nitro-enabled host.

Usage

capsule-cli run [OPTIONS] [IMAGE]

Flag	Default	Description
IMAGE	—	Pre-built capsule image name. Only used if `-f` is not specified.
-f, --file <PATH>	—	Manifest file. Resolves the `target` field as the image name.
-p, --publish <MAP>	—	Port mapping: `HOST:ENCLAVE`. Repeatable.
-d, --debug-mode	false	Enable the debug console for interactive enclave access.
--cpu-count <INT>	manifest/2	Override vCPU count for this run.
--memory-mb <INT>	manifest/4096	Override memory allocation (MiB) for this run.
--mount <BIND>	—	Host-backed mount: `NAME=HOST_PATH`. Repeatable.

Parameter priority

1. CLI flags (highest) → 2. Manifest defaults section → 3. Hardcoded defaults (CPU: 2, Memory: 4096 MiB)

Examples

Run examples

# Basic run with image name
sudo capsule-cli run my-app-enclave:latest

# Run using manifest (resolves target image)
sudo capsule-cli run -f capsule.yaml

# Port mapping
sudo capsule-cli run my-app:latest -p 8080:80 -p 9000:9000

# Resource overrides
sudo capsule-cli run my-app:latest --cpu-count 4 --memory-mb 8192

# With debug console
sudo capsule-cli run my-app:latest -d -p 8080:80

# With host-backed mount
sudo capsule-cli run my-app:latest \
  -p 8080:80 \
  --mount appdata=/var/lib/my-service/appdata

# Multiple mounts
sudo capsule-cli run my-app:latest \
  --mount appdata=/data/app \
  --mount cache=/data/cache

# Full example
sudo capsule-cli run -v my-app-enclave:latest \
  --cpu-count 4 \
  --memory-mb 8192 \
  -p 8080:8080 \
  -p 18001:18001 \
  --mount appdata=/var/lib/my-service/data \
  -d

Port Mapping

The -p flag maps host TCP ports to enclave ingress ports.

Port mapping format

# Format: HOST_PORT:ENCLAVE_PORT
-p 8080:80        # Host 8080 → Enclave 80
-p 8080:8080      # Same port on both sides
-p 9001:18001     # Map Aux API to host port 9001

Important

The enclave port in -p must match a listen_port in the ingress section of your manifest. Ports not declared in ingress are not accessible.

Mount Binding

The --mount flag connects manifest-declared mounts to host directories.

Mount binding format

# Format: MOUNT_NAME=HOST_STATE_DIR
--mount appdata=/var/lib/my-service/appdata

# The MOUNT_NAME must match a storage.mounts[].name in capsule.yaml
# The HOST_STATE_DIR is a directory on the host for persistence

Persistence

Reuse the same HOST_STATE_DIR across runs to preserve data. A new directory or deleting .capsule-hostfs/ resets to empty.

Required vs. Optional

If required: true in the manifest, the run fails if the --mount binding is missing. Optional mounts are skipped with a warning.

Installation

Pre-built binary

# Download
curl -LO https://github.com/sparsity-xyz/\
nova-enclave-capsule/releases/latest/\
download/capsule-cli-x86_64-unknown-\
linux-musl.tar.gz

# Extract and install
tar xzf capsule-cli-*.tar.gz
sudo mv capsule-cli /usr/local/bin/

Build from source

# Requires Rust + cross
cargo install cross

cd capsule-cli
cross build --release \
  --target x86_64-unknown-linux-musl \
  --features run_enclave,capsule-runtime

# Binary at:
# target/x86_64-unknown-linux-musl/
#   release/capsule-cli

Getting Started capsule.yaml Reference