Self-Hosted Mode

Run TypeGraph on your own infrastructure with pgvector, embeddings, LLM extraction, telemetry, and tenant-scoped clients.

What Changes in Self-Hosted Mode

Self-hosted mode uses the same SDK surface as Cloud mode. The operational difference is that you provide the database, embedding model, search embedding model, LLM, ontology, and deployment lifecycle.

The public setup path is intentionally small: vectorStore + embedding + searchEmbedding + llm. If the adapter supports graph and memory capabilities, TypeGraph auto-wires the internal stores.

Install and Initialize

Use the Self-Hosted Initialization guide for complete setup. Do not call public bridge constructors; they are internal implementation details.

terminal

pnpm add @typegraph-ai/sdk @typegraph-ai/adapter-pgvector @ai-sdk/gateway @neondatabase/serverless

Ingest Documents

Self-hosted document ingestion runs in your process unless you put it behind your own job queue. Use arrays for batching and idempotencyKey for retry safety.

Document ingest

const result = await typegraph.document.ingest(
  largeDocumentArray,
  {
    bucketId: 'knowledge-base',
    graphExtraction: true,
    idempotencyKey: 'kb-seed-2026-05-08',
  },
)

Batch Large Corpora

Keep batches bounded by payload size, provider rate limits, and database write throughput. Each batch can still use graph extraction and idempotency.

Batch ingest

import type { DocumentInput } from '@typegraph-ai/sdk'

async function ingestInBatches(
  documents: DocumentInput[],
  batchSize = 100,
) {
  for (let i = 0; i < documents.length; i += batchSize) {
    const batch = documents.slice(i, i + batchSize)
    await typegraph.document.ingest(batch, {
      bucketId: 'knowledge-base',
      graphExtraction: true,
      idempotencyKey: `kb-batch-${i}`,
    })
  }
}

Search With the Same API

Search does not change between Cloud and self-hosted. Pick resources, tune weights, and build a prompt when needed.

const response = await typegraph.search('customer onboarding checklist', {
  resources: ['documents', 'events', 'entities', 'facts'],
  weights: { semantic: 1, bm25: 0.7, graph: 0.5, recency: 0.3 },
  limit: 10,
  promptBuilder: true,
})

Monitor Telemetry

SDK telemetry writes to typegraph_telemetry. Business events live in typegraph_events. Keeping these separate makes app events queryable without mixing them with operational logs.

telemetry.sql

-- SDK telemetry is stored in typegraph_telemetry.
select event_type, count(*)
from typegraph_telemetry
where created_at > now() - interval '1 day'
group by event_type
order by count(*) desc;

Back to All Guides

What Changes in Self-Hosted Mode

The public setup path is intentionally small: vectorStore + embedding + searchEmbedding + llm. If the adapter supports graph and memory capabilities, TypeGraph auto-wires the internal stores.

import type { DocumentInput } from '@typegraph-ai/sdk' async function ingestInBatches( documents: DocumentInput[], batchSize = 100, ) { for (let i = 0; i < documents.length; i += batchSize) { const batch = documents.slice(i, i + batchSize) await typegraph.document.ingest(batch, { bucketId: 'knowledge-base', graphExtraction: true, idempotencyKey: `kb-batch-${i}`, }) } }

const response = await typegraph.search('customer onboarding checklist', { resources: ['documents', 'events', 'entities', 'facts'], weights: { semantic: 1, bm25: 0.7, graph: 0.5, recency: 0.3 }, limit: 10, promptBuilder: true, })