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.
- 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). - Cryptographic Key Binding: Ephemeral HPKE public keys are bound to the hardware quote's 64-byte
REPORT_DATAenvelope. - End-to-End Encryption (RFC 9180 HPKE): Prompts are sealed client-side using standard RFC 9180 HPKE (
DHKEM-X25519-HKDF-SHA256+AES-256-GCM). - Tenant Authority Ingress: Requests are authenticated using canonical Ed25519 request signatures (
Authorization: Cevell-Ed25519 ...). - 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_keyvia info tagcevell-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 setOPENAI_BASE_URL="http://127.0.0.1:8080/v1"andOPENAI_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.ConfidentialTransportfor Pythonhttpx/OpenAI, and@cevell/tunnelwithcreateConfidentialFetchfor JavaScript/TypeScript runtimes. - Wire Protocol: Binary Protobuf messages for
cevell.wire.v1.EncryptedInferenceRequestandStreamingInferenceFrame.
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 || "");
}