App Template
Start from the official template repository for the fastest path to a production-ready enclave application.
nova-app-template
A ready-to-use starter repository that includes all the scaffolding you need.
# Clone the template repository
git clone https://github.com/sparsity-xyz/nova-app-template.git my-nova-app
cd my-nova-appWhat's Included
- Working
Dockerfile - Pre-configured
capsule.yaml - Sample app with Capsule API integration
- Mock service detection pattern
- Health check endpoint
What You Customize
- Your application logic
- Ingress ports
- Egress allow list
- Resource defaults (CPU/memory)
- Storage, KMS, Helios configuration
Recommended Workflow
Follow this four-phase approach to go from template to production.
Get Running
Clone the template, build the Docker image, and run capsule-cli build + capsule-cli run without any modifications. Verify the template app starts and responds on the ingress port.
Reduce to Your Use Case
Replace the template app logic with your own. Keep the capsule.yaml structure but update image names, ports, egress rules, and resource defaults to match your needs.
Integrate Capsule APIs
Add calls to 127.0.0.1:18000 for attestation, signing, encryption, or storage. Use the mock service during local development.
Lock Down
Tighten the egress allow list to only required domains. Enable S3 encryption if using storage. Configure KMS if needed. Review the manifest reference for security-relevant settings.
Local Development with Mock Service
Develop and test your Capsule API integrations without running a real enclave.
External Mock Endpoint
An external Capsule API mock is available at http://capsule-runtime.sparsity.cloud:18000/. This is hosted by the Nova Platform team and may not be version-locked to your Capsule Runtime.
import os
IN_ENCLAVE = os.getenv("IN_ENCLAVE", "false").lower() == "true"
MOCK_URL = os.getenv("CAPSULE_API_MOCK_URL", "http://capsule-runtime.sparsity.cloud:18000")
API_BASE = "http://127.0.0.1:18000" if IN_ENCLAVE else MOCK_URL
# Use API_BASE for all Capsule API calls
response = requests.get(f"{API_BASE}/v1/eth/address")
address = response.json()Mock Limitations
The external mock is for lightweight development only. Endpoints may not exist for all API surfaces. Responses may not exactly match real enclave behavior. Error codes may differ.
HTTP Proxy Support in Your App
Inside the enclave, outbound HTTP goes through the Capsule egress proxy. Your app must support HTTP proxying.
Auto-configured
Capsule Runtime sets http_proxy, https_proxy, HTTP_PROXY, HTTPS_PROXY and no_proxy=localhost,127.0.0.1 when the egress allow list is non-empty.
What to Verify
Your HTTP client must honor proxy environment variables, or be explicitly configured with http://127.0.0.1:<egress.proxy_port>.
Local Traffic
Requests to 127.0.0.1 (Capsule API, Helios) must bypass the proxy. The no_proxy variable handles this automatically.
import { HttpsProxyAgent } from 'https-proxy-agent';
const proxyUrl = process.env.HTTPS_PROXY;
const agent = proxyUrl ? new HttpsProxyAgent(proxyUrl) : undefined;
const response = await fetch('https://api.example.com/data', { agent });examples/hn-fetcher in the repository demonstrates this pattern for Node.js with explicit proxy agent construction.
Recommended Startup Self-Tests
Add these checks to your app startup to fail fast on common misconfiguration.
Test outbound HTTP
Make one request to an allowed external URL through your HTTP client. Confirm it succeeds through the egress proxy.
Test Capsule API
Call http://127.0.0.1:18000/v1/eth/address — confirm it returns a valid response. This verifies the local API path.
Fail early
If either test fails, exit immediately with a clear error log. Don't let the app run in a broken state.