CEVELL Developer Guide & API Reference

Zero-trust, end-to-end encrypted AI inference running inside hardware-isolated Confidential Virtual Machines (CVMs) backed by Intel TDX, AMD SEV-SNP, and NVIDIA Hopper H100 SPDM hardware security engines.

Zero-Trust Architecture

CEVELL eliminates intermediary trust assumptions. Neither network gateways, cloud hypervisors, nor platform operators can observe prompts, weights, or token completions.

  1. Hardware Silicon Attestation: The client fetches the hardware attestation document (GET /attestation) and verifies the hardware quote signed by silicon manufacturer root certificates (Intel, AMD, NVIDIA).
  2. Cryptographic Key Binding: Ephemeral HPKE public keys are bound to the hardware quote's 64-byte REPORT_DATA envelope.
  3. End-to-End Encryption (RFC 9180 HPKE): Prompts are sealed client-side using standard RFC 9180 HPKE (DHKEM-X25519-HKDF-SHA256 + AES-256-GCM).
  4. Tenant Authority Ingress: Requests are authenticated using canonical Ed25519 request signatures (Authorization: Cevell-Ed25519 ...).
  5. Streaming Frame Decryption: Streaming tokens are decrypted frame-by-frame on the client in volatile memory.

Authentication

All API requests require a canonical Ed25519 signature generated with your tenant authority key:

Authorization: Cevell-Ed25519 key="<pubkey_hex>",sig="<signature_hex>",ts="<unix_timestamp>",nonce="<random_nonce>",req="<request_id>"

Base URLs & Endpoints

  • CVM Gateway: https://cvm.cevell.com/<target_ip>/v1
  • Direct CVM Address: https://<target_ip>:443/v1
  • Attestation Endpoint: https://cvm.cevell.com/<target_ip>/attestation
  • Fleet Orchestrator: https://ox.cevell.com/v1

Pricing & Compute Model

CEVELL operates on a pure Bring Your Own Cloud (BYOC) model. Platform access during Developer Preview is 100% Free ($0/mo) with zero platform margin on your cloud infrastructure. Compute runs inside your own cloud account at standard spot or on-demand rates.

Silicon Hardware Attestation Document

Clients fetch the attestation document via GET https://cvm.cevell.com/<target_ip>/attestation?nonce=<32-byte-hex>. The document is an In-toto Statement v1 containing the CPU hardware quote (Intel TDX / AMD SEV-SNP), NVIDIA Hopper/Blackwell SPDM 1.2 evidence, and 5-tier DICE certificate chain.

Verification Invariants

  • TLS Socket Channel Binding: REPORT_DATA[0:32] == SHA-256(SubjectPublicKeyInfo(TLS_Cert)) guarantees no MITM proxy intercepts the connection.
  • Anti-Splicing Composite: REPORT_DATA[32:64] == SHA-256(hpke_pub || nonce || gpu_evidence_digest || auth_pub) binds the CVM HPKE public key, client replay nonce, NVIDIA GPU evidence, and tenant authorization key into the hardware quote.
  • Silicon Register Offsets: Intel TDX embeds user_data at bytes 568..631 in raw quotes; AMD SEV-SNP embeds user_data at bytes 80..143.
  • Root CA & CRL Checks: Validated against Intel SGX/TDX Root CA, AMD KDS, and NVIDIA Device Identity Root CA with live CRL revocation checks.

Custom RFC 9180 HPKE Cryptography

Requests are encrypted client-side using RFC 9180 HPKE (DHKEM(X25519, HKDF-SHA256) + AES-256-GCM / ChaCha20Poly1305). Plaintext requests are rejected by CVM instances with HTTP 415.

  • Symmetric Key Derivation: Derives req_key via info tag cevell-hpke-req-aes-gcm, and response keys (resp_key, resp_base_iv) bound to the request nonce.
  • Streaming Frame AEAD: Streaming token chunks are framed as binary Protobuf messages. Frame nonces are derived by XORing the sequence number into the base IV. Authenticated with a 13-byte AAD layout [seq (4B BE)][frame_type (1B)][timestamp_ns (8B BE)] enforcing strict monotonic ordering.
  • Volatile Zeroization: All symmetric keys are zeroized in RAM upon session completion.

cevell-tunnel: Zero-Trust Local Proxy & Wire Architecture

cevell-tunnel bridges developer tooling (OpenAI SDK, LangChain, Cursor IDE, Continue.dev, cURL, Go, Rust) directly to confidential CVM instances:

  • Local Loopback Proxy: Run cevell-tunnel proxy --ip <CVM_IP> --port 8080 --auth-key ~/.cevell/tenant.pem. Then simply set OPENAI_BASE_URL="http://127.0.0.1:8080/v1" and OPENAI_API_KEY="dummy". The proxy intercepts local HTTP requests, audits CVM hardware attestation, seals bodies in Protobuf HPKE envelopes, signs Ed25519 headers, and yields decrypted SSE chunks transparently.
  • Python & TypeScript SDKs: cevell_tunnel.ConfidentialTransport for Python httpx/OpenAI, and @cevell/tunnel with createConfidentialFetch for JavaScript/TypeScript runtimes.
  • Wire Protocol: Binary Protobuf messages for cevell.wire.v1.EncryptedInferenceRequest and StreamingInferenceFrame.

Chat Completions

POST https://cvm.cevell.com/<target_ip>/v1/chat/completions

{
  "model": "Qwen/Qwen2.5-3B-Instruct-AWQ",
  "messages": [
    {"role": "system", "content": "You are a confidential AI assistant."},
    {"role": "user", "content": "Explain zero-trust confidential computing."}
  ],
  "stream": true,
  "max_tokens": 512,
  "temperature": 0.7
}

Error Codes

  • 400 Bad Request: Malformed JSON or invalid parameters
  • 401 Unauthorized: Invalid Ed25519 signature or timestamp skew
  • 403 Forbidden: Tenant authority key mismatch
  • 422 Unprocessable Entity: Silicon attestation quote verification failed
  • 429 Too Many Requests: CVM concurrency saturated
  • 502 Bad Gateway: CVM runtime unreachable or offline

Code Example: Python (cevell)

import os
from cevell import CVMClient

# 1. Initialize client with target CVM endpoint and tenant private authority key
client = CVMClient(
    base_url="https://cvm.cevell.com/<target_ip>/v1",
    auth_key=os.environ.get("CEVELL_PROVISION_KEY"),
    verify_attestation=True,
)

# 2. Audit hardware silicon attestation (Intel TDX / NVIDIA H100 SPDM)
attestation = client.audit_and_bind_attestation()

# 3. Stream encrypted completions (prompt encrypted client-side with RFC 9180 HPKE)
stream = client.chat.completions.create(
    model="Qwen/Qwen2.5-3B-Instruct-AWQ",
    messages=[{"role": "user", "content": "Hello confidential AI!"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Code Example: TypeScript (@cevell/sdk)

import { CVMClient } from "@cevell/sdk";

const client = new CVMClient({
  baseUrl: "https://cvm.cevell.com/<target_ip>/v1",
  authKey: process.env.CEVELL_PROVISION_KEY,
  verifyAttestation: true,
});

await client.auditAndBindAttestation();

const stream = await client.chat.completions.create({
  model: "Qwen/Qwen2.5-3B-Instruct-AWQ",
  messages: [{ role: "user", content: "Hello confidential AI!" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}