Develop for Enclave: WebAssembly app guide, architecture, CLI, MCP, and API reference

01The app model

An Enclave app is a WebAssembly component that targets wasi:http, the format wasmtime serve runs. It exports one interface, wasi:http/incoming-handler: the runtime hands your code an HTTP request, your code returns a response. Like a serverless function, except it runs inside a hardware-attested confidential enclave, and anyone can verify that.

Inside the enclave your app runs in a strict capability sandbox, in its own OS process, launched by the exact same wasmtime command you can run locally:

• Filesystem: a single private, writable /data directory (RAM-backed scratch, torn down with the deployment). Nothing else is visible, and paths that escape it (/data/../..) are refused by the runtime. Chapter 08 →
• Environment: empty, except what the platform hands you deliberately - ENCLAVE_PORTS for service apps, ENCLAVE_HOSTS with every hostname this deployment answers on (Chapter 14 →), ENCLAVE_MEM_MB and ENCLAVE_AVAILABLE_PARALLELISM with the memory and thread count this deployment's share actually carries, and the config/secrets channels described later. No host env ever leaks in.
• Network: none by default beyond the HTTP socket the runtime serves for you. Declaring open ports switches the app to service mode with wasi:sockets. Chapter 09 →
• GPU: none by default. A deployment that buys a GPU share gets wasi-nn - ONNX, GGUF (llama.cpp) and image-diffusion (stable-diffusion.cpp) inference through the enclave's runtime; on today's hosts the card is reached through Enclave Shield's masked offload. Chapter 12 →
• Memory: the guest's linear memory is capped at the deployment's CPU share of the node's RAM (cpuShare × 64 GB), enforced by the runtime - always at least the memMb the app's specs declare, since the specs floor the share.
• No host reach: no processes, no exec, no SSH (a Wasm app isn't an OS; there's nothing to SSH into, and the platform ships no SSH channel at all).

Two kinds of app, one format:

• Web apps (the default, and this guide's walkthrough): export the handler; the platform owns the listener and routes requests to you.
• Service apps: declare open ports (http:N / tcp:N / udp:N) and run as a long-lived command component that binds its own sockets: databases, IRC servers, DNS resolvers. Chapter 09 →

And one catalog every app reference points at:

• The on-chain app store: the Apps tab: anyone publishes, bytes live on IPFS addressed by CID, listings live in the EnclaveAppCatalog contract on Base. First-party samples (hello-world, nn-demo, llm-chat) are published there too - the enclave image ships no deployable apps, so every deploy resolves to a CID the enclave fetches and hash-verifies. Chapter 04 →

02Toolchain setup

The walkthrough uses Rust, the most mature component toolchain today (other languages in chapter 15). You need the WASI 0.2 target, cargo-component, and, for local testing, the same wasmtime runtime the enclave uses (WASI 0.3 async components are also served - their pinned toolchain is at the end of chapter 03):

# Rust component toolchain
rustup target add wasm32-wasip2
cargo install cargo-component

# the runtime the enclave runs (wasmtime 49 line), for local testing
curl https://wasmtime.dev/install.sh -sSf | bash
wasmtime --version

03Hello, enclave

Five steps from nothing to a running app: scaffold, declare the world, write the handler, build, run. The result is byte-for-byte the kind of component the platform's own hello-world sample is.

Step 1: scaffold a component crate

cargo component new hello --lib && cd hello
cargo add wasi        # WASI 0.2 bindings

Step 2: declare the world

The world tells the toolchain what your component imports and exports. An Enclave web app exports exactly one thing:

package enclave:hello;

world hello {
  export wasi:http/incoming-handler@0.2.0;
}

Step 3: write the handler

use wasi::http::types::{
    Fields, IncomingRequest, OutgoingBody, OutgoingResponse, ResponseOutparam,
};

wasi::http::proxy::export!(Component);

struct Component;

impl wasi::exports::http::incoming_handler::Guest for Component {
    fn handle(_req: IncomingRequest, out: ResponseOutparam) {
        // 1. make a response and take its body handle
        let resp = OutgoingResponse::new(Fields::new());
        let body = resp.body().unwrap();

        // 2. hand the response to the host FIRST, then stream the body
        ResponseOutparam::set(out, Ok(resp));
        let stream = body.write().unwrap();
        stream.blocking_write_and_flush(b"hello from Enclave\n").unwrap();
        drop(stream);

        // 3. finishing the body is what completes the response
        OutgoingBody::finish(body, None).unwrap();
    }
}

Step 4: build

cargo component build --release --target wasm32-wasip2
# artifact: target/wasm32-wasip2/release/hello.wasm

This emits a component (layer 1 in the wasm preamble), not a plain core module. The upload gateway and the enclave both check that field and reject core modules, so anything that builds this way is already in the right format.

Step 5: run it locally

wasmtime serve --addr 127.0.0.1:8080 target/wasm32-wasip2/release/hello.wasm
curl 127.0.0.1:8080/          # → hello from Enclave

Works? Then it works in the enclave. For a full dress rehearsal, add the exact flags the enclave launches with, giving you the same sandbox, memory cap, and /data preopen your deployment will get (the cap is your deployment's CPU share of the node's RAM - at least your published memMb; the 128 MB minimum shown here):

mkdir -p scratch
wasmtime serve -Scli -Shttp -Sp3 -W component-model-async \
  --dir scratch::/data \
  -W max-memory-size=134217728 \
  --addr 127.0.0.1:8080 target/wasm32-wasip2/release/hello.wasm

Going async: WASIp3 components

wasm32-wasip3 is the component model's native-async target: one instance serves many in-flight requests, imports don't block it, and request/response bodies are first-class streams - the right substrate for agent apps whose time goes to model and tool calls. The enclave serves both worlds side by side. The simplest guest route is the wasip3 crate - no WIT files in your repo at all. Match the WIT the fleet serves: the pinned wasmtime (the 49 line) serves wasi:http@0.3.0 final, so use a crate line whose build metadata reads +wasi-0.3.0 (0.7.x and newer); 0.6.0 targets the older 0.3.0-rc-2026-03-15 snapshot and will not instantiate against it.

[lib]
crate-type = ["cdylib"]

[dependencies]
wasip3 = { version = "0.7", features = ["async-spawn"] }   # 0.7.x+ target wasi 0.3.0 final

use wasip3::http::types::{ErrorCode, Fields, Request, Response};
use wasip3::{wit_future, wit_stream};

wasip3::http::service::export!(Hello);

struct Hello;

impl wasip3::exports::http::handler::Guest for Hello {
    async fn handle(_req: Request) -> Result<Response, ErrorCode> {
        let (mut body_tx, body_rx) = wit_stream::new();
        let (result_tx, result_rx) = wit_future::new(|| Ok(None));
        let (resp, _transmit) = Response::new(Fields::new(), Some(body_rx), result_rx);
        drop(result_tx);
        wasip3::spawn(async move {           // stream the body after returning the response
            let leftover = body_tx.write_all(b"hello from wasip3\n".to_vec()).await;
            assert!(leftover.is_empty());
        });
        Ok(resp)
    }
}

Stable Rust lists the target but ships no std for it (and the shipped linkers predate a flag the builtin target emits), so p3 builds go through the platform's blessed toolchain container (wasm/Dockerfile.wasip3-build in the platform repo). It carries a pinned nightly with rust-src, a wasip3 wasi-libc it builds itself from the upstream-pinned revision, a stripped copy of rustc's own target spec, and every determinism flag baked in - the same source and lockfile give everyone the same bytes, so commit your Cargo.lock:

docker build -f wasm/Dockerfile.wasip3-build -t enclave-wasip3-build wasm/
docker run --rm -v "$PWD":/src --entrypoint cargo enclave-wasip3-build generate-lockfile   # once
docker run --rm -v "$PWD":/src enclave-wasip3-build
# artifact: target/wasm32-wasip3/release/<app>.wasm - no custom RUSTFLAGS,
# no shim crates, no spec files in YOUR repo; the container carries all of it
wasmtime serve -Scli -Shttp -Sp3 -W component-model-async \
  --addr 127.0.0.1:8080 target/wasm32-wasip3/release/hello.wasm
for i in $(seq 8); do curl -s 127.0.0.1:8080/ & done; wait   # concurrent on ONE instance

Publishing is unchanged - the upload path reads your component's exports and stamps the detected world ("wasi": "0.3") into the version config, so only p3-capable enclaves claim it (per-box p3 on /availability; ANDed fleet-wide when every runner serves it). Notes:

• Instances are reused and concurrent. Up to 16 requests share one instance (and its linear memory and globals) before it's recycled after ~128 requests or 1s idle. That's the feature - warm state across an agent session - but if your handler assumes per-request isolation, dial it down per version in the config: {"p3": {"maxConcurrent": 1, "maxReuse": 256, "idleSeconds": 5}}. Billing is unchanged either way: you pay per second for the share, never per request.
• wasi-nn works via the 0.2 bridge. Import wasi:nn@0.2.0-rc-2024-10-28 from your p3 world exactly as from a p2 one - same backends, same /models preloads. Its compute() is a sync hostcall that stalls the instance's other requests for the duration, so nn apps on the bridge should set "p3": {"maxConcurrent": 1}. The async, streaming wasi:nn@0.3-draft (host pushes tokens over a stream<u8>) is published in the platform repo at wasm/wit/wasi-nn-0.3-draft/ and lands with the next runtime toolchain cut.
• Streams still need bytes. The gateway's ~180s cut is an idle timer per hop - any body byte resets it, and SSE comment heartbeats pass through untouched (the proxies are content-type-blind). Same rules as p2: emit early, emit often, and send content-encoding: identity on event streams.
• Don't block - it aborts (Rust builds). Until the toolchain moves to an LLVM-23 rustc, the wasip3 libc's futex has the same semantics std documents for p1/p2: a wait that would actually block aborts the instance. In a single-threaded async world that means: never hold a std::sync lock or channel across an .await, and never call blocking std APIs from the handler - use the async primitives (wit_stream/wit_future, wasip3::spawn). Uncontended locks are fine; contention only exists if you parked one across an await. (Cooperative-threads C/C++ builds are the exception: their futex suspends the thread instead - see the threads note below.)
• Cooperative threads (C/C++, rolling out). The C image enclave-wasip3c-build compiles pthread code to a wasip3 component whose threads run cooperatively on the instance's async runtime: pthread_create/join, mutexes, condvars and blocking waits all behave - threads interleave (concurrency, not extra cores; a spin-loop never yields, use the primitives). The upload path detects the thread imports and stamps "threads": true so only thread-capable enclaves claim it (per-box coopThreads on /availability, same pattern as p3); until the fleet's runtime cut lands, expect the capability to read false fleet-wide. Rust std::thread follows automatically when rustc lands on LLVM 23 - no action on your side.
• Release LTO is forced to thin by the container (a cargo config override, so it wins over your Cargo.toml): fat LTO reproducibly fails with a duplicate cabi_realloc between std's wit-bindgen copy and the app's own.

04Publish to the app store

Your app's bytes go on IPFS, addressed by their CID (a hash of the exact wasm). The listing goes on Base, in the EnclaveAppCatalog contract. Publishing is one wallet transaction on the Apps tab:

1. Connect your wallet (header button) and hit + Publish app.
2. Pick a slug, your app's stable id, e.g. my-hello (a–z, 0–9, hyphens, ≤ 40 chars). Slugs live in your wallet's namespace: the on-chain app id is keccak256(publisher, slug), so nobody can squat or write to your lineage. The slug doesn't have to match your crate name.
3. Set a version label (e.g. 1.0.0) and choose your hello.wasm. The file is validated (component check, ≤ 2 GB), its world contract is detected from the exports (wasip2 or wasip3 - stamped into the version config as wasi so runners route p3 work to p3-capable boxes), uploaded, pinned to IPFS, and the CID field fills in (or paste a CID you pinned yourself).
4. Set the display name, a description, and the app's exact minimum resources on four axes: the VRAM (GB) and GPU compute (TFLOPS) it needs on one card (both 0 for CPU-only apps, which is most of them), and the RAM (MB - also the runtime-enforced memory cap; the Hello app is fine at 128) and CPU compute (GFLOPS, at least 1 - every app computes something - and note the unit: a whole 16-vCPU node is only ≈1000 GFLOPS ≈ 1 TFLOPS, so declaring the node's full GFLOPS claims the entire node and forces a 100% CPU share; most small apps want 1-50) it needs on the node. These specs set the MINIMUM shares on the deploy page's two dials (spec ÷ server spec, the larger of the memory and compute axes); deploys below them are refused. Only for service apps, add the open ports the version may bind (chapter 09). Leave ports empty for a standard web app.
5. Optionally set an hourly fee for running your app. It is stored on the version record, shown to every deployer up front, and paid straight to your publisher wallet: whenever a deployer funds a deployment of your app, your share of that funding is forwarded to your wallet in the same transaction (non-custodial, like all Enclave payments). The fee is capped on-chain by the platform, immutable per version like the ports and config, and covered by the owner's approval - re-pricing means publishing a new version, so an approved app can never silently change its price. Leave it at 0 for a free app.
6. Publish to Base: one transaction, signed by your wallet, attributed on-chain to you.

Versioning rules (enforced by the contract)

• Versions are append-only history: you never edit a release, you publish the same slug again with a new version label and CID. editApp changes display metadata; setActive delists the app; yankVersion pulls a bad release (kept for history, hidden from browsing).
• A release's CID belongs to its app forever: no other app can ever list the same bytes, and yanking or delisting doesn't free it. The same app can re-list its own CID in a new version - that's the metadata fix (same bytes, corrected specs or ports; the add version button pre-fills it) - and the enclaves' deploy gate follows the newest listing of a CID, which starts Pending again (a metadata change is re-approved like any release). After the fix lands, yank the superseded version. Publishing a new version to a delisted slug automatically relists the app.
• A CID can be listed once across the whole catalog, so a CID maps unambiguously to one app version.
• Each version carries its own open-ports config; it can change from release to release.

05Deploy it

A deployment names an app, a slice of the card, and who may reach it. The app reference is always a catalog listing:

Unlisted CIDs can't deploy: the catalog listing carries everything a deploy needs on-chain - the resource specs that floor the dials, the open ports, the publisher's hourly fee if the version charges one (shown in the rate before you sign; paid to the publisher's wallet out of each funding), and the owner's approval of that exact CID. Built something new? Publish it first (chapter 04), then deploy the slug.

The easy path is the store: your published app's card has a Deploy button that sizes the shares from the version's specs, applies its open ports and config, and funds it in one step; the model volumes, config, protection and relay of a running deployment are tabs on its dashboard row. No wallet or crypto is needed there: sign in with a passkey (or approve from your phone), add credit by card through Stripe Checkout, and deploy with a dollar budget. Your credit sits in a credit vault that only your passkey can authorize and that can spend only on Enclave compute, and the platform pays every network fee. A wallet adds what credit deployments don't support yet: live logs, the in-browser attestation view, secrets, custom domains, config overrides and apps with a publisher fee.

Agents and direct integrations use the wallet path below, which is the same public API the site speaks:

Sign in over the API: an Ethereum signature

const API = "https://api.enclave.host/v1";

const addr  = (await ethereum.request({ method: "eth_requestAccounts" }))[0];
const { message } = await (await fetch(`${API}/auth/nonce?address=${addr}`)).json();
const signature   = await ethereum.request({ method: "personal_sign", params: [message, addr] });
const { token }   = await (await fetch(`${API}/auth/login`, {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message, signature }),
})).json();          // short-lived bearer token, bound to your address

Create the deployment: one transaction, you own the record

A deployment is an on-chain work item, not one enclave's private state. create() on the EnclaveDeployments contract records the intent - the app's catalog version record (catalog://<appId>/<versionIndex>), the two shares (in 1/1000ths), visibility - under your address, and mints the id (keccak256(sender, nonce), the Created event's first topic). The reference names a version, never bytes: runners take the wasm, config and ports from that immutable record - exactly what the catalog owner approved. (CID references are refused: a CID names bytes, and several versions with different approved configs can share bytes.) Because the ledger holds the spec and the balance, the deployment survives enclave updates and crashes: runners serve it under expiring leases, and when a runner dies, any other enclave picks the work up. Nothing to sign in besides your wallet.

// create(appRef, gpuMilli, cpuMilli, appPort, ports, isPublic, configCid,
//        feeRecipient, feePerSec6)
// appRef = catalog://<appId>/<versionIndex> - the on-chain version record
// shares are 1/1000ths: gpuShare 0.25 -> 250; a GPU app needs gpuMilli >= cpuMilli
// appPort/ports ride along untrusted (the record decides); configCid must be ""
// feeRecipient/feePerSec6 copy the version's publisher fee (its publisher's
// wallet + the per-second fee; 0x0/0 for a free app) - snapshotted like the
// rate, and runners refuse a record that under-declares it (the consoles and
// the CLI fill this in for you)
create("catalog://0x06a4…c13/5", 250, 50, 8080, "", true, "", "0x0…0", 0)
// -> the receipt's Created event: topics[1] is your deployment id (bytes32)

Attach model volumes: big weights, attested, not in the wasm

An enclave can carry attested read-only model volumes: weights declared in the enclave's config become a dm-verity image whose root hash is part of the enclave measurement, so the attestation commits to the exact bytes. A version attaches volumes by name and the runner mounts each read-only at /models/<name> inside the guest - so a multi-GB model reaches your app without riding the app wasm (no include_bytes!, no IPFS weight fetch, none of the 4 GiB linear-memory ceiling on the weights). Volumes ride the version's config - its volumes key - set at publish (the publish form's App config box, or enclave publish --config) and delivered to the app as ENCLAVE_CONFIG straight from the on-chain record. Like the bytes, specs and ports, the config is immutable once published and covered by the version's approval - a publisher cannot change an approved release's behavior; a new default config means a new version and a fresh review. For deployers it is the default, not a straitjacket: on fleets that support it, a deployment may carry its own config override at create (the deploy form's App config box, or enclave deploy --config) - it replaces the version's config as that one deployment's ENCLAVE_CONFIG, and the catalog record and every other deployment stay untouched.

Large configs. A config up to 4096 bytes is stored inline in the version record. Past that it is pinned to IPFS and the record carries its CID instead, which raises the ceiling to 1 MB - the publish path does this for you, so enclave publish --config and the App config box behave the same either way. The guarantee does not change: the CID is part of the immutable, approval-covered version record, exactly like the wasm CID beside it, and the enclave fetches it through the same path that verifies the content hashes back to the CID - so what your app receives is what the owner approved, not whatever a gateway felt like serving. Two details worth knowing if your config is large: a handful of keys (wasi, threads, set, gpuOptional, cpuFallback, volumes, _media) stay on-chain as a small manifest, because a runner reads them to pick a machine - and size the share it must have bought - before it fetches anything; and above 64 KB the config no longer fits in an environment variable (a kernel limit on argument size), so it arrives only as a file. Read ENCLAVE_CONFIG_FILE - it is set at every size, and points at the same JSON ENCLAVE_CONFIG carries when it fits.

// published WITH the version (enclave publish --config '…'); the runner reads it
// from the catalog record, mounts each volume at /models/<name> (read-only), and
// hands the whole object to the app as ENCLAVE_CONFIG.
{ "volumes": ["qwen2.5-0.5b"], "system_prompt": "…app config…" }
// GET /availability lists the volumes the fleet carries (name, bytes, which enclaves).

Secrets: private values that never touch the chain

Everything above is public by design - the catalog config and a deployment's config override live on an open ledger, so an S3 key pasted into either is published to the world. Real credentials go in the deployment's secrets instead: env-var-shaped values stored on the platform's API relay (encrypted at rest, never on-chain, capped at 64 keys / 16 KB) and handed only to the enclave that holds your deployment's live lease, which injects each one as an environment variable when the app starts - alongside ENCLAVE_CONFIG, so your app just reads its env. Managing them takes no session and no gas: each change is one personal_sign over a canonical string, and the relay honors it only from the deployment's on-chain owner wallet. A running app picks changes up on its next start (enclave restart, or the dashboard's Restart). Plain reality, stated plainly: the relay operator can technically read these values (that is what lets an unattended restart re-inject them) - for credentials even the operator must never see, use encrypted volumes, whose keys derive from your wallet signature client-side.

# stage at deploy (stored before the first claim, so the app boots with them)
enclave deploy encrypted-volumes:1.2 --fund 5 --secrets-file .env

# or manage them any time - one wallet signature per change
enclave secrets set 0x9c41…88d1 S3_SECRET_ACCESS_KEY=… --restart
enclave secrets ls  0x9c41…88d1          # names only; --show reveals
enclave secrets rm  0x9c41…88d1 OLD_KEY  # "clear" removes all

Secrets also reach apps that only read ENCLAVE_CONFIG: a $NAME (or ${NAME}) inside any config string resolves to the secret of that name when the enclave launches the app - so the on-chain config carries a harmless placeholder and the private value is spliced in at start, inside the enclave. Only names actually stored as secrets substitute (any other $ stays literal; $$ escapes one before a real name), and the deployment record keeps showing the placeholder - the resolved value exists only in the app's environment.

{ "endpoint": "https://s3.eu-central-1.wasabisys.com", "bucket": "my-bucket",
  "credentials": { "accessKeyId": "$S3_ACCESS_KEY_ID",
                   "secretAccessKey": "$S3_SECRET_ACCESS_KEY" } }

Fund it: pay-per-second, credited on-chain, no custody

On the site, card credit does this step for you: your credit vault creates and funds the record when you deploy. From a wallet, funding lands in the deployment's on-chain balance6 and the USDC splits in the same transaction: the host's share stays in the ledger as escrow, released to the host only for time it proves, and the rest forwards (ETH fundings forward in full). Your rate is snapshotted at create: gpuShare × $6/hr + cpuShare × $3/hr, plus the app's hourly publisher fee if it charges one. On a paid app every funding is split in that same transaction: the publisher's share (their fee's fraction of the rate) goes straight to their wallet, the host's share to escrow, the rest to Enclave. Pay either way:

// USDC: sign an EIP-3009 ReceiveWithAuthorization (gas-free wallet signature,
// to = the EnclaveDeployments contract, nonce prefixed with the id's first 16 bytes), then ONE tx:
fundWithAuthorization(bytes32 id, address from, uint256 value,
                      uint256 validAfter, uint256 validBefore,
                      bytes32 nonce, bytes signature)

// ETH: one payable call; credited at the Chainlink ETH/USD rate read IN the contract:
fundEth(bytes32 id) payable

Enclaves sweep the ledger for funded, unleased work about once a minute; POST /v1/claim-hint {"id": …} skips the wait by asking the fleet to claim right now. The claiming enclave fetches your wasm from IPFS, verifies it hashes to the CID, launches it, and renews its lease while healthy - balance / rate seconds of runtime, burned lease by lease, with clean handovers refunding the unused tail. The console does all of the signing and encoding for you.

Watch it come up

The ledger shows the claim (get(id).runner + a live leaseUntil); the runner's status API shows the launch. The SIWE token from above authorizes the owner-only status route - sign in with the same wallet that sent create().

let d;                                   // id = the bytes32 from the Created event
do {
  await new Promise(r => setTimeout(r, 2000));
  d = await (await fetch(`${API}/deployments/${id}`, {
    headers: { "Authorization": `Bearer ${token}` },
  })).json();
} while (d.status !== "running");

console.log(d.network.endpoint);     // https://…/x/0x…
// your app's own origin: the id's first 8 hex chars as a subdomain
console.log(`https://${id.slice(2, 10)}.app.enclave.host`);

Keep it alive, or stop it

• Top up: another fundWithAuthorization / fundEth with a fresh nonce, any time - each payment adds amount / rate seconds to the on-chain balance.
• Upgrade: setAppRef(id, "catalog://<appId>/<newIndex>") (owner-only) repoints the deployment at another approved version of the app - paid time, shares and the live lease all stay on the record, and the runner restarts the app in place on the new version within about a minute (new wasm fetched before the old instance stops). No second buy-in to pick up a new release; the dashboard's Version control and enclave upgrade are exactly this call. Shares bought at create() are immutable - and so is the publisher-fee snapshot - so a version whose minimums exceed the shares, or whose publisher fee exceeds the snapshot, can't be switched to - deploy that one fresh.
• Stop: setActive(false) on the contract (owner-only) takes the work off the queue - the current runner's watcher tears it down and releases the lease, refunding the unused tail to your deployment's balance. That balance stays on the record: setActive(true) later resumes from what's left. To get money back instead, refund(id) (the owner or its delegate) first pays the host for proven time, then returns your own unspent escrow to the owner and deactivates the deployment. Only that escrow comes back - the host's share of what the owner funded in USDC; the publisher's cut, Enclave's share and ETH fundings are final - so fund in small top-ups. DELETE /v1/deployments/{id} alone only stops the CURRENT run; an active, funded deployment gets re-claimed.
• Fairness: the quantum of trust is the lease (30 min). A runner that dies mid-lease has burned that lease - that is the worst case; clean shutdowns and enclave updates release() and lose you nothing, and another enclave resumes your app from its CID.

06Call your app

Every deployment serves HTTP on its own path and, through the gateway, its own origin (so one app can never touch another app's cookies or storage, or the site's):

# public deployment: anyone, no auth
curl https://3xk9f2qa.app.enclave.host/            # per-deployment origin (id without "dep_")
curl https://<enclave-host>/x/dep_3xK9f2Qa/    # same app, direct to its enclave

# private deployment (public: false): owner's bearer token only
curl -H "Authorization: Bearer $LOGIN_TOKEN" https://<enclave-host>/x/dep_3xK9f2Qa/

• Any method, any subpath, headers and body pass through to your handler. The one exception: the Authorization header authenticates at the platform and is stripped before your app sees the request; the token never reaches tenant code.
• public only governs who may send requests. Confidentiality is unaffected either way; the operator can't see inside the enclave regardless.
• Your app's println! / stderr output lands in the deployment log: GET /v1/deployments/{id}/logs (owner-only).

07HTTP in depth: routing, headers, body

Everything a web app needs beyond hello: reading the method, path and headers, consuming the request body, and writing a status, headers, and a streamed response. This drop-in src/lib.rs shows all of it:

use wasi::http::types::{
    Fields, IncomingRequest, Method, OutgoingBody, OutgoingResponse, ResponseOutparam,
};

wasi::http::proxy::export!(Component);
struct Component;

fn read_body(req: IncomingRequest) -> Vec<u8> {
    let body = req.consume().unwrap();
    let stream = body.stream().unwrap();
    let mut buf = Vec::new();
    while let Ok(chunk) = stream.blocking_read(64 * 1024) {
        if chunk.is_empty() { break; }
        buf.extend_from_slice(&chunk);
    }
    buf                       // a stream error here means end-of-body (Closed)
}

fn respond(out: ResponseOutparam, status: u16, ctype: &str, payload: &[u8]) {
    let headers = Fields::new();
    headers.set(&"content-type".to_string(), &[ctype.as_bytes().to_vec()]).unwrap();
    let resp = OutgoingResponse::new(headers);
    resp.set_status_code(status).unwrap();
    let body = resp.body().unwrap();
    ResponseOutparam::set(out, Ok(resp));
    let stream = body.write().unwrap();
    for chunk in payload.chunks(4096) {       // write in ≤ 4096-byte chunks
        stream.blocking_write_and_flush(chunk).unwrap();
    }
    drop(stream);
    OutgoingBody::finish(body, None).unwrap();
}

impl wasi::exports::http::incoming_handler::Guest for Component {
    fn handle(req: IncomingRequest, out: ResponseOutparam) {
        let method = req.method();                               // Method::Get, Method::Post, …
        let path   = req.path_with_query().unwrap_or_default();  // "/echo?x=1"

        match (method, path.as_str()) {
            (Method::Get, "/") =>
                respond(out, 200, "text/plain", b"routes: GET /headers - POST /echo\n"),

            (Method::Get, "/headers") => {                       // request headers
                let mut s = String::new();
                for (name, value) in req.headers().entries() {
                    s.push_str(&format!("{name}: {}\n", String::from_utf8_lossy(&value)));
                }
                respond(out, 200, "text/plain", s.as_bytes());
            }

            (Method::Post, p) if p.starts_with("/echo") => {     // request body
                let body = read_body(req);
                respond(out, 200, "application/octet-stream", &body);
            }

            _ => respond(out, 404, "text/plain", b"not found\n"),
        }
    }
}

wasmtime serve --addr 127.0.0.1:8080 target/wasm32-wasip2/release/hello.wasm
curl 127.0.0.1:8080/headers
curl -X POST --data-binary 'round trip' 127.0.0.1:8080/echo

08The /data scratch filesystem

Every deployment gets a private, writable /data directory, so ordinary file-using code (a SQLite database, a cache, config, logs) ports to wasm without a rewrite. In Rust it's plain std::fs; every language's stdlib file I/O maps to the same wasi:filesystem interface. Extending the echo app with a hit counter:

use std::fs;

// (Method::Get, "/hits"): a per-deployment counter that survives across requests
(Method::Get, "/hits") => {
    let hits: u64 = fs::read_to_string("/data/hits")
        .ok().and_then(|s| s.trim().parse().ok())
        .unwrap_or(0) + 1;
    fs::write("/data/hits", hits.to_string()).unwrap();
    respond(out, 200, "text/plain", format!("visit #{hits}\n").as_bytes());
}

Test locally with the parity flag from chapter 03 (--dir scratch::/data). Know exactly what /data is:

• Private: your app sees only its own /data; there is no preopen for anything else, and escaping paths are refused by the runtime. Isolation is the wasi capability model, not a convention.
• Ephemeral: it's RAM-backed scratch inside the enclave's already-encrypted memory, torn down when the deployment ends. No persistence, no shared storage: treat it as scratch, not a database of record. For data that persists under a key only your user holds, see encrypted volumes (ch. 13).
• Capped: usage is limited by the version's storage_mb (default 256 MB); an app that exceeds it is killed by the audit sweep, since ramdisk files consume RAM the memory cap doesn't cover. Publish with storage_mb: 0 to opt out of /data entirely.

09Service apps: open ports & ENCLAVE_PORTS

Declaring open ports (on the version you publish, applied to every deployment of it from the on-chain record) changes how your app runs: instead of wasmtime serve calling your handler, the enclave launches it with wasmtime run as a long-running command component (a main()) granted wasi:sockets: it binds its declared ports itself, and may also make outbound TCP/UDP connections and DNS lookups. Rust's std::net on wasm32-wasip2 maps straight onto it.

Declared ports are logical: your app's stable, advertised interface, like a container's EXPOSE. Each deployment gets its own actual loopback bind, so any number of tenants can run "the tcp:5432 app" simultaneously with zero conflicts; URLs always use the logical number and route by deployment id. The mapping arrives in one environment variable:

ENCLAVE_PORTS=tcp:5432=31245,udp:9053=31246     # logical=actual; BIND THE ACTUAL

Parsing the contract is a few lines; every service example below uses this helper:

/// "tcp:7000=31245,udp:9053=31246" → the actual port for a logical entry.
fn actual_port(logical: &str) -> u16 {
    std::env::var("ENCLAVE_PORTS").unwrap_or_default()
        .split(',')
        .find_map(|e| e.trim().strip_prefix(&format!("{logical}="))?.parse().ok())
        .unwrap_or_else(|| panic!("{logical} not in ENCLAVE_PORTS"))
}

Readiness: the enclave waits (~20 s) for your first http:/tcp: port to accept before marking the deployment running, so bind early in main(). Both launch modes also pass -S p3 (on runtimes that prove it), so you may target the async WASIp3 API surface instead of wasip2's poll-based one - same sandbox, same rules; the pinned p3 toolchain is at the end of chapter 03.

10TCP: bridge, in-enclave TLS, public relay

A complete TCP echo service. Note it's a command component (no --lib) with a main() that runs for the deployment's lifetime:

use std::io::{Read, Write};
use std::net::TcpListener;

fn main() {
    let port = actual_port("tcp:7000");             // ← the helper from chapter 09
    let listener = TcpListener::bind(("0.0.0.0", port)).expect("bind");
    println!("echo on {port}");                     // shows up in your deployment logs
    for conn in listener.incoming() {               // wasip2 has no threads:
        let Ok(mut sock) = conn else { continue };  // serve connections one at a time
        let mut buf = [0u8; 4096];
        while let Ok(n) = sock.read(&mut buf) {
            if n == 0 || sock.write_all(&buf[..n]).is_err() { break; }
        }
    }
}

cargo component new tcp-echo && cd tcp-echo     # no --lib: a command component
cargo component build --release --target wasm32-wasip2

# exactly how the enclave launches a service app:
wasmtime run -Scli -Sp3 -Stcp -Sudp -Sinherit-network -Sallow-ip-name-lookup \
  --env ENCLAVE_PORTS=tcp:7000=7000 \
  target/wasm32-wasip2/release/tcp-echo.wasm
printf 'ping\n' | nc 127.0.0.1 7000              # → ping   (another terminal)

Publish it with open ports tcp:7000, deploy, and reach it three ways:

# 1. WebSocket bridge on the attested origin (private deployments: append ?token=<bearer>)
websocat --binary tcp-listen:127.0.0.1:7000 \
  "wss://<enclave-host>/x/dep_3xK9f2Qa/tcp/7000"
nc 127.0.0.1 7000                                # → your app, end to end

# 2. Direct public TLS via the relay: stock clients, no websocat. Public deployments
#    only; hostname = deployment id with its underscore hyphenated (dep_abc123 → dep-abc123)
psql "host=abc12345.app.enclave.host port=5432 sslmode=verify-full"
irssi -c abc12345.app.enclave.host -p 6667 --tls

Your app does nothing for the TLS path: keep speaking plain TCP on the assigned port. The platform mints its key + cert inside the enclave at boot; the untrusted relay only routes ciphertext by SNI, and the session terminates in-enclave at /x/{id}/tls/{port}. Verifying clients can bind the session to the attestation by pinning the cert published over the attested origin:

curl -s https://<enclave-host>/v1/tls-bridge | jq -r .fingerprint256
openssl s_client -connect abc12345.app.enclave.host:6667 \
  -servername abc12345.app.enclave.host </dev/null 2>/dev/null \
  | openssl x509 -noout -fingerprint -sha256       # must match

11UDP: datagrams & per-deployment IPv6

Same shape as TCP: bind the actual port, speak datagrams:

use std::net::UdpSocket;

fn main() {
    let port = actual_port("udp:9053");             // ← the helper from chapter 09
    let sock = UdpSocket::bind(("0.0.0.0", port)).expect("bind");
    let mut buf = [0u8; 65535];
    loop {
        let Ok((n, from)) = sock.recv_from(&mut buf) else { continue };
        let _ = sock.send_to(&buf[..n], from);
    }
}

Every public deployment gets its own dedicated IPv6 address (deterministic from its id, out of the relay's routed /64). Its declared tcp:N and udp:N ports are reachable at [address]:N - at the real port you declared, routed by destination IP, no SNI and no remapping. The address is in the deploy/status response under network.address (and network.tcp / network.udp per protocol). TCP is raw passthrough (any protocol - your app owns TLS or plaintext); publish with udp:9053 or tcp:5432:

# 1a. UDP, direct to the deployment's own IPv6 (public deployments)
printf 'ping' | socat -t2 - 'UDP6:[2a01:4f9:c013:9b52:9c1e:…]:9053'

# 1b. TCP, direct to the SAME address at the real port (any protocol)
psql 'host=2a01:4f9:c013:9b52:9c1e:… port=5432 …'
nc 2a01:4f9:c013:9b52:9c1e:… 5432

# 2. the WebSocket bridge on the attested origin (1 message = 1 datagram)
websocat --binary udp-listen:127.0.0.1:9053 \
  "wss://<enclave-host>/x/dep_3xK9f2Qa/udp/9053?token=<bearer>"
printf 'ping' | socat -t2 - UDP:127.0.0.1:9053

• IPv6 only: a box has one IPv4; v4-only clients can't reach the direct endpoint (the bridge still works anywhere WebSockets do).
• The relay sees cleartext: unlike the TCP path, the UDP relay is not a confidentiality boundary. If your protocol needs privacy, encrypt at the app layer (e.g. DTLS).
• Datagram boundaries are preserved end to end; idle bridge flows close after 120 s.

12GPU inference (wasi-nn)

Buying a GPU share doesn't just reserve silicon - it grants an interface. A deployment with gpuShare > 0 is launched with wasi-nn: your component imports wasi:nn and hands the runtime a model. Three backends sit behind the same interface - ONNX Runtime for ONNX graphs, a bundled llama.cpp (ggml) backend for GGUF language models, and a bundled stable-diffusion.cpp backend for image-generation checkpoints. execution-target gpu runs on the card (the CUDA provider / CUDA-offloaded llama.cpp / GPU diffusion); cpu runs on the node. A deployment without a GPU share doesn't get the import at all - the component fails to instantiate - so the boundary is structural, not a quota. On today's hosts the card is reached only through Enclave Shield's masked offload, which serves GGUF models through the llama.cpp backend; the ONNX and diffusion GPU paths served only on the retired hosted fleet.

• The share is a reservation, not a wall. Your deployment reserves gpuShare of the card's memory and compute on the host's Shield worker, exactly the budget the deployment priced. That is scheduling and accounting between tenants, not a hardware boundary: what protects your data on the card is that the card only ever holds masked values, and every result is checked before your app uses it (Enclave Shield).
• GPU means GPU. The platform's runtime is patched so target gpu either runs on CUDA or fails the load() - never a silent fallback to the CPU. On the ONNX path that means the CUDA provider initializes or the load fails (ONNX Runtime's default is a quiet CPU fallback); on the GGUF path the whole model offloads to your slice by default, and the backend refuses to run if the CUDA module didn't actually load; the diffusion backend is strict the same way. Want CPU inference? Ask for cpu.
• Isolation is the capability model again: graphs and tensors are opaque handles scoped to your instance. Nothing like a device pointer or a raw kernel ever crosses the boundary.

Import the interfaces in your world (WIT deps vendored from the wasmtime the fleet pins, the 49 line; wasi:nn 0.2.0-rc-2024-10-28):

package you:app;

world app {
  import wasi:nn/tensor@0.2.0-rc-2024-10-28;
  import wasi:nn/errors@0.2.0-rc-2024-10-28;
  import wasi:nn/inference@0.2.0-rc-2024-10-28;
  import wasi:nn/graph@0.2.0-rc-2024-10-28;
  export wasi:http/incoming-handler@0.2.6;
}

A WASIp3 app imports the same wasi:nn@0.2 interfaces from its p3 world - the runtime links both API sets into one process, so nothing changes on the nn side (the bridge; see the p3 notes in chapter 03 for the one concurrency caveat). The async, token-streaming wasi:nn@0.3-draft is published in the platform repo and arrives with a future runtime cut.

Load once, compute per request - the whole API is four calls, and it drives all three backends. The ONNX path first. Tensors cross the boundary as little-endian bytes in any ONNX element type - fp16, fp32, fp64, bf16, i32, i64, u8 - and outputs come back in the model's actual dtype. Zero-size dimensions are legal (an empty KV cache bootstrapping a decoder's first step), and compute returns owned tensor handles you can feed straight back as the next step's inputs, so KV-cache bytes never round-trip through your linear memory.

use bindings::wasi::nn::graph::{load, ExecutionTarget, GraphEncoding};
use bindings::wasi::nn::tensor::{Tensor, TensorType};

static MODEL: &[u8] = include_bytes!("model.onnx");

let graph = load(&[MODEL.to_vec()], GraphEncoding::Onnx, ExecutionTarget::Gpu)?;
let ctx   = graph.init_execution_context()?;
let x     = Tensor::new(&[1, 4], TensorType::Fp32, &input_bytes);   // little-endian f32s
let out   = ctx.compute(vec![("X".into(), x)])?;                     // named tensors, in and out

Try it without writing code: the nn-demo app in the Apps catalog is exactly this. Deploy it with 1% GPU + 1% CPU and hit /?target=gpu; it runs a tiny ONNX graph and echoes which target served it.

The GGUF path: generative LLMs via llama.cpp. GraphEncoding::Ggml loads any GGUF model - split-GGUF families included - on the runtime's bundled llama.cpp backend. The natural delivery is a model volume (ch. 05): attach a GGUF volume to your version and the runtime preloads it once at process start as a named graph, registered under the volume's name. load_by_name() then hands you the graph without the weights ever entering your linear memory - so model size is bounded by your share of the card, not by wasm32's 4 GiB. (Small GGUFs can still ride load() from embedded bytes.) The inference contract is an autoregressive decode loop: feed "tokens" (i32, dims [1, n], chunk your prefill at 512 tokens per compute), get back "logits" (fp32, [1, n_vocab], for the last token), sample, feed the sampled token back. The KV cache lives inside the execution context and persists across compute() calls - a fresh context is a fresh sequence. Tokenization and sampling are yours: the backend speaks token ids, not strings.

use bindings::wasi::nn::graph::load_by_name;

let graph = load_by_name("qwen2.5-0.5b")?;   // the attached GGUF volume's name
let ctx   = graph.init_execution_context()?; // fresh context = fresh sequence
let mut next = prompt_ids;                   // Vec<i32>, ≤ 512 per compute
loop {
    let t   = Tensor::new(&[1, next.len() as u32], TensorType::I32, &le_bytes(&next));
    let out = ctx.compute(vec![("tokens".into(), t)])?;  // ("logits", fp32 [1, n_vocab])
    let id  = sample(&out);                  // your sampler: greedy, top-p, …
    if id == EOS { break; }
    emit(id); next = vec![id];               // KV cache persists in `ctx`
}

And for the full-scale proof, deploy llm-chat from the same catalog: an OpenAI-compatible LLM service with a web chat UI in one small component - and no weights in the wasm at all. Its versions attach GGUF model volumes; the runtime preloads each as a named graph, and the app drives the whole tokens-in/logits-out decode through wasi:nn on your share of the GPU: chunked prefill, KV cache resident in the execution context, tokenizer and sampler in the guest, target gpu strict.

The image path: diffusion via stable-diffusion.cpp. The same four calls generate images. Attach an image-checkpoint volume - SD-Turbo-class full checkpoints, SDXL, FLUX-family GGUF quants, or split-component DiT families (Qwen-Image, Z-Image) - and the runtime preloads it through the bundled stable-diffusion.cpp backend as a named graph: load_by_name(), weights never in your linear memory, exactly like GGUF volumes. The contract is one compute() per image, all named tensors: prompt (utf-8 bytes) is the only required input; negative_prompt, steps (i32, default 20), seed (i64), width/height (i32, 64-multiples, default 512), cfg (fp32, default 7.0 - set 1.0 for turbo models) and sample_method/scheduler (sd.cpp names) are optional. Back comes image: u8, dims [1, h, w, 3], RGB row-major. Generation blocks inside the call, and requests against the same checkpoint queue - one generation at a time per model.

let graph  = load_by_name("sd-turbo")?;      // the attached checkpoint volume's name
let ctx    = graph.init_execution_context()?;
let prompt = b"a lighthouse in a storm, oil painting";
let out    = ctx.compute(vec![
    ("prompt".into(), Tensor::new(&[prompt.len() as u32], TensorType::U8, prompt)),
    ("steps".into(),  Tensor::new(&[1], TensorType::I32, &4i32.to_le_bytes())),
    ("cfg".into(),    Tensor::new(&[1], TensorType::Fp32, &1.0f32.to_le_bytes())), // turbo: guidance off
])?;                                         // ("image", u8 [1, 512, 512, 3], RGB)

Getting the model in. Three routes. Embed it (include_bytes!) for anything small - it ships inside your published CID, so it's attested with your code; the ceilings are the ≤ 2 GB wasm artifact and the ≤ 4 GiB linear memory that load() passes bytes through. Attach a model volume (ch. 05) for anything big: attested read-only weights mounted at /models/<name> - and a GGUF or image-checkpoint volume is additionally preloaded as a named wasi-nn graph for load_by_name(), skipping your linear memory entirely. Or fetch at startup over outbound HTTP into memory and check the hash yourself before loading - the platform verifies your code by CID, a fetched model is your responsibility.

13Encrypted volumes

Confidential storage where only your user holds the key. A directory is encrypted client-side with rclone crypt and the ciphertext pushed to any S3-compatible bucket the owner controls; the deployment's App Config names where that ciphertext lives - never a key. At unlock time the key enters through the app, over the deployment's in-enclave-terminated TLS, and the enclave pulls and decrypts into a live mount. The bucket, the network, and the operator's host only ever see ciphertext: file names and contents are both encrypted at rest, and plaintext exists only on the CVM's encrypted ramdisk while the volume is unlocked.

Push data

scripts/enclave-encvol.sh in the Enclave repo is the client half: it encrypts locally and syncs ciphertext up, mirroring exactly what the enclave runs at unlock, so a push here always pulls there.

AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=… \
ENCVOL_PASSWORD=… ENCVOL_SALT=… \
  scripts/enclave-encvol.sh push ./my-data \
  --endpoint https://s3.example.com --bucket my-bucket --path vol --name docs

It prints the exact encVolumes App Config snippet to publish. pull and ls round-trip the volume from anywhere else you hold the key.

Name it in the App Config

Everything in the config is public and non-secret - it says where ciphertext lives and how it was packed:

What your app sees

The deployment starts immediately, with an empty live preopen per volume - no key ceremony on the critical path. After unlock, decrypted files appear in place; your code needs no crypto and no S3 client, just std::fs reads. Three environment variables are the whole contract:

ENCLAVE_ENC=docs,models          # volume names; each mounted at /enc/<name>
ENCLAVE_ENC_API=http://…         # the in-enclave manager's loopback unlock plane
ENCLAVE_ENC_TOKEN=…              # bearer for that plane - only your app holds it

Your app drives the plane over loopback: GET $ENCLAVE_ENC_API for per-volume status (locked / syncing / unlocked / pushing), and POST …/unlock (password, optional salt, optional S3 credentials), …/sync (encrypt local edits back to the bucket), …/lock (wipe plaintext, drop credentials) - all authenticated with the token, which must never reach a browser. The first-party encrypted-volumes app in the store is the reference implementation: a complete unlock UI whose /api/* proxy keeps the token server-side.

Three ways to unlock

Password. The manager takes an opaque password (+ optional salt) and runs the pull. Simplest, and what headless automation uses.

Wallet. No password to keep: the key is derived from a deterministic ECDSA personal_sign over a canonical message naming the volume - only the wallet holder can reproduce it, nothing is stored or verified server-side, and no transaction is made. The contract is byte-exact across the CLI, the push script, and the app:

message  = "Enclave encrypted volume key v1\nvolume: <keyId>\n\n
            Signing derives this volume's encryption key. Only sign in
            apps you trust with its contents."
sig      = lowercase 65-byte personal_sign hex, 0x-prefixed
password = sha256_hex( sig + "\n" + "enclave-encvol-v1:password" )
salt     = sha256_hex( sig + "\n" + "enclave-encvol-v1:salt" )

Wallet + sealed credentials: one signature, nothing typed. Bucket credentials can ride the public config encrypted under the same signature - enclave encvol seal-creds prints the credsEnvelope value. At unlock, one signature derives the crypt key and opens the credentials, in the browser, before anything is sent:

encKey / macKey = sha256( sig + "\n" + "enclave-encvol-v1:creds-enc" / ":creds-mac" )
envelope        = "encv1:" + base64( iv[16] || AES-256-CTR(encKey, iv, credsJSON)
                                            || HMAC-SHA256(macKey, iv || ct)[32] )

Plain volumes: skip the crypt layer

Not everything is secret. "encrypted": false mounts the bucket verbatim - same live /enc/<name> preopen, same unlock/sync/lock lifecycle and caps, no crypt anywhere. Think public datasets, published model weights, assets your app serves. Unlock then takes S3 credentials only - an empty body suffices for a public-read bucket - and refuses a password outright; filenameEncryption / directoryNameEncryption don't apply. Push data with any S3 client, or enclave-encvol.sh push --plain to get the matching config snippet. The bucket host sees every byte of a plain volume: keep anything confidential in an encrypted one.

Restarts, locking, write-back

Nothing survives a restart, by design: an unlocked volume is plaintext in enclave RAM plus credentials in the manager's memory, and a re-claim, update, or crash returns the volume to locked - someone holding the key must unlock again. Wallet mode makes that a ten-second signature rather than a secret to retrieve; Lock is the same wipe on demand. Push-back (sync) re-encrypts local edits to the bucket with the same key - it needs write-capable credentials at unlock and a volume not marked readOnly.

14Custom domains

Every deployment answers on its own subdomain, <label>.app.enclave.host. You can also attach a domain you own, and the app serves it under that name - same backend, no redirect, no frame - with a certificate minted inside the enclave. The private key for your domain is generated in the CVM and never leaves it, which is the same guarantee the platform subdomain already gives you.

Open Domains on the deployment in the dashboard, type the hostname, and it shows you the exact records to create. There are three:

# 1. routing - where the traffic goes
shop.example.com.                    CNAME  cc1f4f3f.app.enclave.host.

# 2. ownership - proves this deployment may claim the name
_enclave-challenge.shop.example.com. TXT    "enclave-verify-9f3a…"

# 3. certificates - delegates issuance AND renewal. Leave it in place.
_acme-challenge.shop.example.com.    CNAME  _acme-challenge.cc1f4f3f.app.enclave.host.

DNS is re-checked every few minutes, so the status moves on its own: waiting for DNS → verified → live, usually within a minute or two of the records publishing. Nothing is served on your name until it is verified and its certificate exists - a name with no certificate gets a refused handshake, never a warning page.

www vs the apex

A subdomain like www.example.com or shop.example.com is the easy case: it can hold a CNAME, so record 1 above works as written.

An apex (example.com, no subdomain) cannot hold a CNAME - RFC 1034 forbids a CNAME alongside the SOA and NS records every zone apex must have. Two ways round it, and we accept both:

• CNAME flattening (Cloudflare's CNAME at the root, Route 53 ALIAS, DNSimple ALIAS, Netlify, and most modern providers). You enter a CNAME to <label>.app.enclave.host and the provider publishes our A/AAAA records under your apex instead. Verification sees those addresses, recognizes our edge, and accepts it - flattening and a real CNAME are the same proof that traffic reaches us.
• A/AAAA by hand, pointing at our edge addresses. It works, and it is what flattening does for you, but it is a static copy of an address we may one day change: prefer flattening, or a www subdomain, wherever your provider offers it.

The common shape is to attach both: example.com (flattened) and www.example.com (CNAME), then have your app redirect one to the other. Each is a separate attachment with its own certificate. Records 2 and 3 are per-hostname either way - _enclave-challenge.www.example.com is a different record from _enclave-challenge.example.com.

Writing an app that serves more than one name

Your guest environment carries ENCLAVE_HOSTS: a comma-separated list of every hostname this deployment answers on, its own subdomain first. Use it for the checks only your app can make - a Host allowlist, CSRF trusted origins, a websocket Origin check - instead of hardcoding a name you cannot know at publish time. Build absolute URLs and redirects from the request's Host (it reaches you untouched), and leave cookies host-only unless you have a reason not to.

ENCLAVE_HOSTS is set when the app starts, so a domain attached to a running app appears in it after a restart. Routing and TLS for the new name work immediately - only the app's own view of the list waits.

When it doesn't go live

• "No TXT record …" - the _enclave-challenge record is missing or holds a different value. Some providers append the zone name for you: creating _enclave-challenge.shop.example.com in the example.com zone often needs the name entered as _enclave-challenge.shop.
• "CNAME does not point at …" - the name resolves, but somewhere else. If you use a CDN in front of us, put it in DNS-only mode (Cloudflare: grey cloud, not orange). A proxying CDN terminates TLS itself, so our edge never sees your visitors' handshakes and the certificate we mint for you is never presented.
• "CAA records only allow …" - your zone publishes a CAA policy that excludes our CA. Add 0 issue "sectigo.com" alongside whatever is there, or remove the restriction.
• A certificate error, with the CA's own words - issuance was attempted and refused. The reason is shown verbatim under the domain; nearly always it is CAA, or record 3 missing so the CA cannot find the challenge.
• It was live and went back to "waiting for DNS" - the records stopped resolving for a sustained period, so routing and issuance were withdrawn. Put them back and it recovers by itself, usually within a few minutes.

15Attestation for your users

On a confidential host the platform's core promise extends to your app: a user can verify, cryptographically and before sending a byte of data, that they're talking to an attested enclave running exactly the code that was measured. For apps deployed by CID, the attestation includes your app: its app.cid field names the exact bytes that ran, hash-verified against the CID inside the enclave by the measured runtime, with a coverage note stating precisely what covers it (the boot measurement covers the runtime; the runtime pins your app).

# Enclave's own verifier (verifier/ in the repo, bundled into the CLI):
enclave attest dep_3xK9f2Qa                       # the box your deployment runs on
enclave attest dep_3xK9f2Qa --expect <measurement>  # pin the launch measurement yourself

# what it checks: a FRESH report for a nonce it draws (sent through the relay to the box),
# AMD signature up to AMD's root, firmware floor, guest policy, the box's key bound to the
# nonce, and the launch measurement (yours with --expect; otherwise the operator's list,
# reported as "limited", never as a pass)

// same-origin, hash-pinned build of verifier/web
import { verifyMetalBoxWeb } from "https://enclave.host/vendor/enclave-verifier.js";

const r = await verifyMetalBoxWeb({ name: "metal0", expected: { measurements: ["<measurement>"] } });
if (r.status !== "verified") throw new Error("not verified: " + r.reasons.at(-1));
// r.transportKeySha256 is the key the report binds: use it for an end-to-end channel

Point your users at the attestation walkthrough for what each link in the chain proves, or embed the check in your own client as above. For raw-TCP services, add the bridge-cert pin so even the TLS session is bound to the measured enclave.

16Other languages

The platform runs components, not a language: anything that emits a wasi:http component works. Mature routes today:

• Rust: cargo-component, as used throughout this guide. The most complete support, including std::net for service apps.
• JavaScript / TypeScript: jco componentize (ComponentizeJS) turns a JS module exporting a fetch-style handler into a wasi:http component.
• Python: componentize-py builds components from Python code implementing the same world.
• Go: TinyGo's wasip2 target with the wasi:http bindings.

The acceptance test is identical regardless of toolchain. If this runs, it deploys:

wasmtime serve --addr 127.0.0.1:8080 app.wasm && curl 127.0.0.1:8080/

One caveat for service apps: raw-socket support (wasi:sockets) varies by toolchain: Rust's stdlib maps today; check yours before designing around tcp:/udp: ports.

17Limits & sandbox reference

What your code can touch

Numbers to know

18Troubleshooting

Ship checklist

1. wasmtime serve (or run, for service apps) runs it locally, including with the enclave-parity flags.
2. No hardcoded ports anywhere; everything comes from ENCLAVE_PORTS.
3. All writes go under /data, stay under the cap, and survive being wiped.
4. Publish on the Apps tab → wait for the version's Approved badge → deploy it from its card.
5. Verify your own deployment's attestation, then hand the same check to your users.

19Wallet sessions: let an agent act without your key

Every on-chain change above is a wallet transaction. A session lets an agent, a script or a browser tab make those changes without holding your wallet key. It is a P-256 key, a policy and an optional USDC budget, approved once by your wallet. The key signs each action, the platform's relayer submits it to your session vault (one SessionVault contract per wallet, on Base), and the vault checks the policy on-chain before it calls the ledger or the catalog. There is no wallet prompt per action and no ETH: the relayer is reimbursed a small USDC fee per operation out of the session's budget, at a price the key itself signed. The vault has no admin, so you can always end a session or withdraw straight from your wallet.

What a policy allows

Presets: browser (sign-in on enclave.host: every deployment action, any free app, staging and prod, $0 budget, 12 h), staging-publish (agents: publish and run named apps on staging only, $10 escrowed, $5/day, 7 days) and auth-only (status reads, no money).

Open one from a terminal

enclave session new --preset staging-publish --app myapp-staging --budget 10 --days 7 --label "Claude Code"
# prints what it allows, a check code (3F9A-0C1E) and https://enclave.host/grant#…
# you open the link, compare the check code, and sign: once, or twice with a budget
# (the grant, then the USDC it escrows). The relayer submits; you need no ETH.

enclave publish …                 # now acts through the session, no wallet prompt
enclave session status            # budget, spend, time left
enclave session terminate         # sign out: the unspent budget returns to you

Add --env to print export ENCLAVE_SESSION=… instead of storing a key file, for agents that keep secrets in their environment. Treat that value as a key. The full walkthrough is Give Claude Code a staging session.

The apps your wallet owns

A session can also manage the deployments your wallet holds, where they are. You allow it once, for your vault, with one wallet transaction to the deployments ledger: Sessions → Apps your wallet owns → Grant, or enclave session delegate run with your wallet key. After that, every session whose grant covers prod may, within its own actions:

• suspend and resume, resize, and lower the price cap;
• add runtime out of its budget, credited to your wallet (a paid app only if the grant names it and its fee is under the grant's ceiling);
• cancel, with the refund paid to your wallet.

It can never change the version or config a wallet-held app runs, raise its price cap, move it out of your wallet, or touch its secrets. Revoke on the same card, or enclave session delegate --revoke, cuts every session off your wallet's apps in one transaction. Staging-only sessions, such as the staging-publish preset, never reach them.

Always your wallet's

Topping up, extending or withdrawing from the vault; promoting a version to production; opening, changing or ending other sessions; secrets and custom domains; moving a deployment; anything touching the treasury. Ending a session, by sign-out, expiry or revocation, never stops what is already running: deployments keep their own balance on the ledger.

Contracts on Base: session vault factory 0x1F5c887c0cDF491b16AB6c449abAfDF9B2ec9C9C, deployments ledger 0xB1783B61E1FDee6a6163DC3CdaC27bF32E7d117B. The relay API is in the API reference; the agent tools are on the MCP tab.