CyborgDB JavaScript/TypeScript SDK

The CyborgDB JavaScript/TypeScript SDK is the JavaScript/TypeScript client for CyborgDB — the vector database that stays encrypted even while it's searching. Run similarity search directly on encrypted data with client-side keys; only the result of a query is ever decrypted, never the index. Built with TypeScript, it ships full type definitions for JavaScript and TypeScript apps.

This SDK talks to cyborgdb-service, which you self-host in your own VPC or on-prem and run alongside your app. Install and start it separately. See our docs for more info.

Key Features

• Encryption-in-use: Search runs directly on ciphertext — only the query result is decrypted, never the index or stored vectors
• Encrypted ANN: Disk-backed encrypted DiskIVF index with recall within 2% of a plaintext baseline (read the benchmarks)
• Filters on encrypted metadata: Combine vector similarity with equality and range predicates in a single request
• BYOK / HYOK: Wrap per-index keys with AWS KMS or AWS Secrets Manager, or hold the key client-side — you control the key material
• Per-tenant key isolation: Per-index, per-user keys with cryptographic RBAC; revoke a user and their keys are erased
• TypeScript-first API: Complete type definitions and IntelliSense for JavaScript and TypeScript apps

Getting Started

To get started in minutes, check out our Quickstart Guide.

Installation

1. Install cyborgdb-service

# Pull the CyborgDB Service image
docker pull cyborginc/cyborgdb-service

2. Install cyborgdb SDK:

# Install the CyborgDB TypeScript SDK
npm install cyborgdb

Usage

import { Client } from 'cyborgdb';

// Initialize the client
const client = new Client({ 
  baseUrl: 'https://localhost:8000', 
  apiKey: 'your-api-key' // optional; only if the service was started with one
});

// Generate a 32-byte encryption key
const indexKey = client.generateKey();

// Create an encrypted index
const index = await client.createIndex({
  indexName: 'my-index',
  indexKey: indexKey,
});

// Add encrypted vector items
const items = [
  {
    id: 'doc1',
    vector: [0.1, 0.2, 0.3, /* ... 128 dimensions */],
    contents: 'Hello world!',
    metadata: { category: 'greeting', language: 'en' }
  },
  {
    id: 'doc2', 
    vector: [0.4, 0.5, 0.6, /* ... 128 dimensions */],
    contents: 'Bonjour le monde!',
    metadata: { category: 'greeting', language: 'fr' }
  }
];

await index.upsert({ items });

// Query the encrypted index
const queryVector = [0.1, 0.2, 0.3, /* ... 128 dimensions */];
const results = await index.query({
  queryVectors: queryVector,
  topK: 10,
  include: ['distance']
});

// Print the results
results.results.forEach(result => {
  console.log(`ID: ${result.id}, Distance: ${result.distance}`);
});

Advanced Usage

Batch Queries

// Search with multiple query vectors simultaneously
const queryVectors = [
  [0.1, 0.2, 0.3, /* ... */],
  [0.4, 0.5, 0.6, /* ... */]
];

const batchResults = await index.query({
  queryVectors: queryVectors,
  topK: 5
});

Metadata Filtering

// Search with metadata filters
const results = await index.query({
  queryVectors: queryVector,
  topK: 10,
  nProbes: 1,
  greedy: false,
  filters: { category: 'greeting', language: 'en' },
  include: ['distance', 'metadata', 'contents']
});

Bring Your Own Key (BYOK) via KMS

Indexes can be encrypted under a key managed by a KMS instead of one held by the SDK. The KMS entries (kms.registry) are configured server-side in the cyborgdb-service YAML and referenced by name via kmsName. The SDK has no KMS management surface — see BYOK.md for operator/customer setup.

There are two key-management modes — supply exactly one of indexKey / kmsName:

// Mode 1 — SDK-managed (default): the SDK supplies the 32-byte key.
const indexKey = client.generateKey();
const index = await client.createIndex({
  indexName: 'my-index',
  indexKey,
});
// Loading requires the same key:
await client.loadIndex({ indexName: 'my-index', indexKey });

// Mode 2 — KMS-managed: the service generates and wraps the key.
// Pass a `kmsName` that references a registry entry (`aws-kms` or
// `aws`/Secrets Manager) and omit `indexKey`.
const kmsIndex = await client.createIndex({
  indexName: 'tenant-acme',
  kmsName: 'customer-acme',
});
// No key needed to load — the service resolves it from its KMS:
await client.loadIndex({ indexName: 'tenant-acme' });

At least one of indexKey / kmsName is required on createIndex, and you must not supply both — the service rejects that with a 400 (the named slot already determines the key source). Mode 1 is recorded server-side as provider: none; none is not a registry slot you reference by name. The LangChain integration accepts the same kmsName option in its store config.

Supported runtimes

The SDK ships as a single dependency-free bundle that imports and runs on any JavaScript runtime with fetch and Web Crypto:

Runtime	Supported	Notes
Node.js	>= 18	Full functionality, including the on-disk sample-dataset cache.
Bun / Deno	Yes	Node-compatible; same functionality as Node.
Browsers	Yes (modern)	verifySsl: false has no effect.
Vercel Edge Runtime	Yes	-
Cloudflare Workers	Yes	-

Documentation

For more information on CyborgDB, see the Cyborg Docs.

License

The CyborgDB JavaScript/TypeScript SDK is licensed under the MIT License.