Copyable Example

Minimal Example

This is the smallest useful Capsule shape for a developer who wants one app, one manifest, and one successful enclave run.

Use this page after the parent instance is already prepared. The example keeps the manifest small, keeps the application boundary simple, and uses the Capsule API only from inside the enclave.

Minimal capsule.yaml

Start with the smallest manifest that still expresses the runtime boundary clearly.

capsule.yaml

version: "v1"
name: "hello-capsule"
target: "hello-capsule:enclave"

sources:
  app: "hello-capsule:latest"

defaults:
  cpu_count: 2
  memory_mb: 4096

ingress:
  - listen_port: 8000

egress:
  allow:
    - "api.openai.com"
    - "169.254.169.254"

api:
  listen_port: 18000

aux_api:
  listen_port: 18001

If the app only calls Capsule APIs from inside the enclave, you usually do not need to expose 18000 or 18001 through ingress.

Minimal Application Integration

Your application talks to Capsule over localhost HTTP, not through direct Nitro SDK integration.

Application Code Example

const capsuleBase = "http://127.0.0.1:18000";

export async function loadCapsuleContext() {
  const [identity, entropy] = await Promise.all([
    fetch(`${capsuleBase}/v1/eth/address`).then((r) => r.json()),
    fetch(`${capsuleBase}/v1/random`).then((r) => r.json()),
  ]);

  return {
    enclaveAddress: identity.address,
    randomBytes: entropy.random_bytes,
  };
}

This is the recommended app boundary: regular application code calls regular local HTTP endpoints. Capsule handles the enclave-native plumbing behind those endpoints.

Build And Run Commands

Assuming the parent instance is already prepared, these are the commands most developers need.

01

Build the normal application image

Run docker build -t hello-capsule:latest . and make sure the container shape already works.

02

Build the Capsule release image

Run capsule-cli build -f capsule.yaml.

03

Run the enclave

Run sudo capsule-cli run -f capsule.yaml -p 8000:8000.

04

Verify the endpoint and local Capsule calls

Call the app endpoint from outside the enclave and confirm the app can still call the Capsule API on 127.0.0.1:18000 internally.

Build And Run

docker build -t hello-capsule:latest .
capsule-cli build -f capsule.yaml
sudo capsule-cli run -f capsule.yaml -p 8000:8000

Do not treat a launch failure as an app bug first. If the host allocator or hugepage pool is wrong, fix the host before you change application code.

Verify The App

# Example external call
curl http://127.0.0.1:8000

# Then inspect logs if needed
docker logs <capsule-shell-container>

The external verification path should prove that ingress works, while the application logs should prove that the internal Capsule API calls also succeeded.

Next step: after this minimal flow works, move to App Template or Examples and replace the toy shape with your actual service.