Self-hosting

You can self-host the Context API instead of using the managed service at ultracontext.ai.

Prerequisites

Node.js >= 22
PostgreSQL (direct or via Supabase)
Docker (optional, for local Postgres)

Quick start with Docker

The monorepo includes a Docker Compose setup for local PostgreSQL:

git clone https://github.com/ultracontext/ultracontext.git
cd ultracontext

# start PostgreSQL
npm run ultracontext:db:up

# apply schema
npm run ultracontext:db:migrate

# start the API
npm run ultracontext:api

git clone https://github.com/ultracontext/ultracontext.git
cd ultracontext

# start PostgreSQL
yarn ultracontext:db:up

# apply schema
yarn ultracontext:db:migrate

# start the API
yarn ultracontext:api

git clone https://github.com/ultracontext/ultracontext.git
cd ultracontext

# start PostgreSQL
pnpm ultracontext:db:up

# apply schema
pnpm ultracontext:db:migrate

# start the API
pnpm ultracontext:api

git clone https://github.com/ultracontext/ultracontext.git
cd ultracontext

# start PostgreSQL
bun run ultracontext:db:up

# apply schema
bun run ultracontext:db:migrate

# start the API
bun run ultracontext:api

Database schema

Create these tables in your PostgreSQL database:

SQL

create table projects (
  id bigserial primary key,
  name text not null,
  created_at timestamptz not null default now(),
  public_id text
);

create table api_keys (
  id bigserial primary key,
  project_id bigint not null,
  key_prefix text not null,
  key_hash text not null,
  name text,
  last_used_at timestamptz,
  created_at timestamptz not null default now()
);

create table nodes (
  id bigserial primary key,
  public_id text not null,
  project_id bigint not null,
  type text not null,
  content jsonb not null default '{}'::jsonb,
  metadata jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now(),
  parent_id text,
  prev_id text,
  context_id text
);

-- GIN index for fast metadata filtering
create index if not exists idx_nodes_metadata
  on nodes using gin (metadata);

Storage adapters

The Context API uses a storage adapter pattern to abstract database operations. You can choose between two backends:

Direct PostgreSQL — Drizzle ORM with a direct connection
Supabase — Supabase REST client for managed PostgreSQL

Both produce identical API behavior.

	Direct PostgreSQL	Supabase
Best for	Self-hosted, full control	Managed hosting, quick setup
Connection	Direct TCP	REST API (HTTPS)
Latency	Lower	Slightly higher (HTTP overhead)
Setup	Manage your own PostgreSQL	Create a Supabase project
Scaling	Manual	Handled by Supabase
Atomic permanent delete	Yes (real transactions)	Best-effort (sequential REST)
Append-vs-delete race safety	Yes (SERIALIZABLE isolation)	Best-effort (no isolation)
Open source	Yes	Yes

Direct PostgreSQL

.env

DATABASE_PROVIDER=postgres
DATABASE_URL=postgresql://user:password@host:5432/ultracontext
ULTRACONTEXT_ADMIN_KEY=your_admin_key

Best for self-hosted deployments where you manage your own database. Lower latency via direct TCP connection.

Supabase

.env

DATABASE_PROVIDER=supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJhbGci...
ULTRACONTEXT_ADMIN_KEY=your_admin_key

Best for managed hosting and quick setup. Scaling handled by Supabase.

Permanent delete operations (uc.delete(..., {permanent: true}) and uc.deleteMany(...)) run as sequential REST calls on this provider — a mid-operation failure may leave partially-deleted state. Use the postgres provider for atomic permanent delete.

Use the service role key, not the anon key. The service role key bypasses Row Level Security, which the API needs to manage data across projects.

Create a Supabase project

Go to supabase.com and create a new project.

Create the tables

Run the SQL schema above in the Supabase SQL editor.

Get your credentials

In your Supabase dashboard, go to Settings > API. Copy:

Project URL — your SUPABASE_URL
service_role key — your SUPABASE_SERVICE_ROLE_KEY

Set environment variables

Add the Supabase env vars shown above to your .env file.

Environment variables

Variable	Required	Description
`DATABASE_PROVIDER`	Yes	Storage provider: `postgres` or `supabase`
`DATABASE_URL`	If using PostgreSQL	PostgreSQL connection string
`SUPABASE_URL`	If using Supabase	Supabase project URL
`SUPABASE_SERVICE_ROLE_KEY`	If using Supabase	Supabase service role key
`ULTRACONTEXT_ADMIN_KEY`	Yes	Admin key for key management endpoints
`PORT`	No	API server port (default: 8787)

Deploy to Cloudflare Workers

The Context API ships with a Workers entrypoint (src/worker.ts) that runs on Cloudflare’s edge network. Only the Supabase storage adapter is supported on Workers (no direct TCP to PostgreSQL).

Prerequisites

A Supabase project with the schema applied
Wrangler CLI installed

Configure

Create a wrangler.jsonc in apps/api:

wrangler.jsonc

{
    "name": "ultracontext-api",
    "main": "src/worker.ts",
    "compatibility_date": "2024-12-01"
}

Set your secrets via wrangler secret put:

wrangler secret put DATABASE_PROVIDER        # enter: supabase
wrangler secret put SUPABASE_URL
wrangler secret put SUPABASE_SERVICE_ROLE_KEY
wrangler secret put ULTRACONTEXT_ADMIN_KEY

Optional: API key caching with KV

You can cache API key lookups using Workers KV to reduce Supabase calls:

Create a KV namespace: wrangler kv namespace create ULTRACONTEXT_API_KEYS_CACHE
Add the binding to wrangler.jsonc:

wrangler.jsonc

{
    "kv_namespaces": [
        {
            "binding": "ULTRACONTEXT_API_KEYS_CACHE",
            "id": "<your-namespace-id>"
        }
    ]
}

When the binding is present, key lookups are cached for 1 hour. Without it, every request queries Supabase directly (same behavior as Node.js).

Deploy

cd apps/api && npx wrangler deploy

MCP endpoint

Self-hosted APIs include a built-in MCP endpoint at /mcp. No extra setup needed — it uses the same Bearer token authentication as the REST API. See MCP Server for details.

Context API

Fundamentals

Guides

Prerequisites

Quick start with Docker

Database schema

Storage adapters

Direct PostgreSQL

Supabase

Environment variables

Deploy to Cloudflare Workers

Prerequisites

Configure

Optional: API key caching with KV

Deploy

MCP endpoint

​Prerequisites

​Quick start with Docker

​Database schema

​Storage adapters

​Direct PostgreSQL

​Supabase

​Environment variables

​Deploy to Cloudflare Workers

​Prerequisites

​Configure

​Optional: API key caching with KV

​Deploy

​MCP endpoint

Prerequisites

Quick start with Docker

Database schema

Storage adapters

Direct PostgreSQL

Supabase

Environment variables

Deploy to Cloudflare Workers

Prerequisites

Configure

Optional: API key caching with KV

Deploy

MCP endpoint