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'

const client = new TCloud({ apiKey: 'sk-tan-...' })

// Chat
const answer = await client.ask('What is Tangle?')

// Streaming
for await (const chunk of client.askStream('Explain decentralized AI')) {
  process.stdout.write(chunk)
}

// Private mode (anonymous, no API key needed)
const shielded = TCloud.shielded()
await shielded.ask('Hello from the shadows')

All Endpoints

The SDK covers every endpoint the router serves:

// Chat (OpenAI-compatible)
await client.chat({ model: 'gpt-4o', messages: [...] })
await client.chatStream({ model: 'claude-sonnet-4-5', messages: [...] })
await client.ask('Quick question')

// Completions (legacy)
await client.completions({ prompt: 'Hello,' })

// Embeddings
await client.embeddings({ model: 'text-embedding-3-small', input: 'Hello world' })

// Images
await client.imageGenerate({ model: 'dall-e-3', prompt: 'A cat in space' })

// Audio
await client.speech({ model: 'tts-1', input: 'Hello', voice: 'alloy' })
await client.transcribe(audioBlob)

// Rerank
await client.rerank({ query: 'AI', documents: ['doc1', 'doc2'] })

// Web search
await client.search({ query: 'latest Tangle docs', provider: 'exa', maxResults: 5 })
await client.ask('What changed in Tangle this week?', { webSearch: { provider: 'exa', maxResults: 5 } })

// Fine-tuning
await client.fineTuneCreate({ model: 'gpt-4o-mini', training_file: 'file-abc123' })
await client.fineTuneList()

// Batch
await client.batch([{ model: 'gpt-4o', messages: [...] }])
await client.batchStatus('batch-id')

// Video
await client.videoGenerate({ prompt: 'A sunset timelapse' })
await client.videoStatus('video-id')

// Models & operators
await client.models()
await client.searchModels('llama')
await client.operators()

Blueprint Routing

Route requests to specific Tangle Blueprint operators:

const client = new TCloud({
  apiKey: 'sk-tan-...',
  routing: {
    mode: 'operator',           // 'operator' | 'provider' | 'auto'
    blueprintId: '1',           // route to operators under this Blueprint
    serviceId: '42',            // pin to a specific service instance
    prefer: '0x70997970...',    // pin to a specific operator address
    strategy: 'lowest-latency', // routing strategy
  },
})

Rotating client

import { TCloud } from '@tangle-network/tcloud'

const client = TCloud.rotating({
  apiKey: process.env.TANGLE_API_KEY,
  routing: { strategy: 'min-exposure' },
})
await client.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.

Local SDK qualification

Automatic PR verification of the SDK is retired. Merge the current default branch and qualify the affected SDK surface through the maintained admitted gate. The gate installs every workspace importer from the frozen pnpm lockfile; this comprehensive reference retains the previous build/test/package checks:

beelink-gate auto https://github.com/tangle-network/tcloud.git <full-sha> -- bash -lc 'set -euo pipefail; git diff --exit-code -- pnpm-lock.yaml; pnpm --filter "@tangle-network/tcloud..." run build; pnpm --filter @tangle-network/tcloud test; packs=$(mktemp -d -t tcloud-qualified-packs.XXXXXX); pnpm --dir packages/tcloud pack --pack-destination "$packs"; printf "Inspected local package directory: %s\n" "$packs"'

The workspace/package manifests own the package manager, runtime requirements and check commands. Build precedes tests and packing. Workflow/docs-only changes use YAML, actionlint, content/link and exact-diff checks. The two tagged publishers and their immutable shared preparation workflow are unchanged; publication still consumes its inspected exact tarball. Local packing does not publish or authorize model requests, live TEE resources or payment operations. The opt-in live proof below retains its separate authorization and cleanup requirements.

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