Guide

Examples

Working reference implementations that demonstrate common enclave application patterns.

Example Repositories

Starter

nova-app-template

Official starter template. Clone, customize, and deploy. Includes a pre-configured capsule.yaml, Dockerfile, health check, and Capsule API mock integration pattern.

github.com/sparsity-xyz/nova-app-template

Collection

nova-app-examples

A growing collection of example applications covering different languages, frameworks, and Capsule features (attestation, signing, encryption, storage, Helios RPC).

github.com/sparsity-xyz/nova-app-examples

Built-in Example: hn-fetcher

A minimal HTTP forwarder included in the Capsule repository at examples/hn-fetcher/.

What It Does

Forwards HTTP GET requests to news.ycombinator.com through the Capsule egress proxy and returns the upstream response. Exposes GET /health for liveness checks.

What It Demonstrates

Explicit proxy-aware HTTP client (Node.js), egress allow-list configuration, Aux API ingress exposure, and the full build → run cycle.

Language

Node.js with Express. Lightweight — one source file, one dependency pattern.

examples/hn-fetcher/capsule.yaml

version: v1
name: "hn-fetcher"
target: "hn-fetcher-enclave:latest"

sources:
  app: "hn-fetcher:latest"

defaults:
  memory_mb: 1500

ingress:
  - listen_port: 8000
  - listen_port: 9001

egress:
  allow:
    - news.ycombinator.com

api:
  listen_port: 9000

aux_api:
  listen_port: 9001

Ingress exposes both the app port (8000) and the Aux API port (9001) so external clients can request attestation documents.

Build & Run

Steps

# Build the app image
cd examples/hn-fetcher
docker build -t hn-fetcher:latest .

# Build the capsule
capsule-cli build -f capsule.yaml

# Run the enclave (on a Nitro-enabled host)
sudo capsule-cli run hn-fetcher-enclave:latest -p 8000:8000 -p 9001:9001

# Verify
curl http://localhost:8000/health
# → {"ok":true,"upstream":"https://news.ycombinator.com"}

Common Application Patterns

Patterns you'll see across examples and production apps.

Pattern

Attestation Service

Expose the Aux API port through ingress so external clients can fetch attestation documents. The Aux API sanitizes the response (removes public_key).

ingress:
  - listen_port: 8080    # app
  - listen_port: 18001   # aux API
aux_api:
  listen_port: 18001

Pattern

Encrypted Communication

Client generates a P-384 keypair, derives a shared secret with the enclave public key, and encrypts data with AES-256-GCM before sending to the enclave's /v1/encryption/decrypt.

# Client flow:
# 1. GET /v1/encryption/public_key
# 2. Generate client P-384 keypair
# 3. ECDH → HKDF → AES-256-GCM
# 4. POST /v1/encryption/decrypt

Pattern

On-Chain Data via Helios

Use the built-in Helios light client for trustless on-chain reads. No external RPC trust required.

from web3 import Web3

# Trustless Base Sepolia reads
base = Web3(Web3.HTTPProvider(
    "http://127.0.0.1:18545"
))
block = base.eth.get_block('latest')

Pattern

Persistent Storage with S3

Use the Capsule S3 API for encrypted object storage, with optional KMS-derived encryption keys.

# Store data
POST http://127.0.0.1:18000/v1/s3/put
{"key": "data/records.json",
 "body": "..."}

# Retrieve data
POST http://127.0.0.1:18000/v1/s3/get
{"key": "data/records.json"}

Pattern

Transaction Signing

Sign EIP-1559 transactions inside the enclave using the Capsule eth signing API.

# Get enclave address
GET /v1/eth/address

# Sign a transaction
POST /v1/eth/sign-tx
{
  "chain_id": 84532,
  "to": "0x...",
  "value": "0x0",
  "data": "0x..."
}

Pattern

Host-Backed Data Directory

Mount a persistent writable directory for application state that survives enclave restarts.

# capsule.yaml
storage:
  mounts:
    - name: appdata
      mount_path: /mnt/appdata
      required: true
      size_mb: 10240

# Run with binding
sudo capsule-cli run app:latest \
  --mount appdata=/var/lib/app/data

Get the Template Browse Examples