tcloud

TypeScript SDK, CLI, and private inference agent for Tangle AI Cloud — decentralized LLM inference with operator routing, reputation-based selection, and anonymous payments via ShieldedCredits.

npm install @tangle-network/tcloud

Packages

Package	Description	npm
@tangle-network/tcloud	SDK + CLI
tcloud-agent	Private inference agent + Pi extension	—

Quick Start

import{TCloud}from'@tangle-network/tcloud'constclient=newTCloud({apiKey: 'sk-tan-...'})// Chatconstanswer=awaitclient.ask('What is Tangle?')// Streamingforawait(constchunkofclient.askStream('Explain decentralized AI')){process.stdout.write(chunk)}// Private mode (anonymous, no API key needed)constshielded=TCloud.shielded()awaitshielded.ask('Hello from the shadows')

All Endpoints

The SDK covers every endpoint the router serves:

// Chat (OpenAI-compatible)awaitclient.chat({model: 'gpt-4o',messages: [...]})awaitclient.chatStream({model: 'claude-sonnet-4-5',messages: [...]})awaitclient.ask('Quick question')// Completions (legacy)awaitclient.completions({prompt: 'Hello,'})// Embeddingsawaitclient.embeddings({model: 'text-embedding-3-small',input: 'Hello world'})// Imagesawaitclient.imageGenerate({model: 'dall-e-3',prompt: 'A cat in space'})// Audioawaitclient.speech({model: 'tts-1',input: 'Hello',voice: 'alloy'})awaitclient.transcribe(audioBlob)// Rerankawaitclient.rerank({query: 'AI',documents: ['doc1','doc2']})// Web searchawaitclient.search({query: 'latest Tangle docs',provider: 'exa',maxResults: 5})awaitclient.ask('What changed in Tangle this week?',{webSearch: {provider: 'exa',maxResults: 5}})// Fine-tuningawaitclient.fineTuneCreate({model: 'gpt-4o-mini',training_file: 'file-abc123'})awaitclient.fineTuneList()// Batchawaitclient.batch([{model: 'gpt-4o',messages: [...]}])awaitclient.batchStatus('batch-id')// Videoawaitclient.videoGenerate({prompt: 'A sunset timelapse'})awaitclient.videoStatus('video-id')// Models & operatorsawaitclient.models()awaitclient.searchModels('llama')awaitclient.operators()

Blueprint Routing

Route requests to specific Tangle Blueprint operators:

constclient=newTCloud({apiKey: 'sk-tan-...',routing: {mode: 'operator',// 'operator' | 'provider' | 'auto'blueprintId: '1',// route to operators under this BlueprintserviceId: '42',// pin to a specific service instanceprefer: '0x70997970...',// pin to a specific operator addressstrategy: 'lowest-latency',// routing strategy},})

Rotating client

import{TCloud}from'@tangle-network/tcloud'constclient=TCloud.rotating({apiKey: process.env.TANGLE_API_KEY,routing: {strategy: 'min-exposure'},})awaitclient.ask('Hello privately')console.log(client.getRotationStats())// { callsByOperator: { 'op-a': 1 }, currentOperator: 'op-a' }

Rotation strategies: round-robin, random, min-exposure (per-call dispatch, stateless only — sandbox-harness sessions are rejected).

CLI

npx @tangle-network/tcloud chat "Hello"# chat
npx @tangle-network/tcloud chat --private "Anon"# anonymous inference
npx @tangle-network/tcloud models # list models
npx @tangle-network/tcloud search "Tangle docs" --provider exa --max-results 5
npx @tangle-network/tcloud operators # list operators
npx @tangle-network/tcloud wallet generate # create shielded wallet
npx @tangle-network/tcloud credits balance # check credits

Do not install or execute the unscoped tcloud npm package. It is unrelated to Tangle.

Live TEE E2E

The TEE sandbox path has an opt-in live test because it creates real cloud/operator resources.

TCLOUD_LIVE_TEE_E2E=1 \
TCLOUD_SANDBOX_API_KEY=sk-tan-... \
TCLOUD_LIVE_TEE_TYPE=tdx \
TCLOUD_LIVE_TEE_ALLOW_UNVERIFIED_HARDWARE=1 \
pnpm --dir packages/tcloud test:e2e

TCLOUD_LIVE_TEE_ALLOW_UNVERIFIED_HARDWARE=1 is required until vendor-root quote verification ships in @tangle-network/tcloud-attestation. The test still proves the live SDK -> sandbox SDK -> Tangle-backed sandbox -> nonce-bound attestation wiring.

Architecture

@tangle-network/tcloud (SDK + CLI)
├── TCloudClient — OpenAI-compatible, covers all 11 v1 endpoints
├── ShieldedClient — EIP-712 SpendAuth, auto-replenish, privacy proxy
├── Routing — X-Tangle-Blueprint / Service / Operator / Routing headers
└── CLI — chat, models, operators, credits, wallet
tcloud-agent
├── Agent / agent() — run-until loop over the sandbox bridge
├── TangleToolProvider — unified Tangle capability surface for Pi tools
└── Pi extension — tangle + tcloud_wallet tools (Pi 0.65+)

License

Apache-2.0