How to Deploy Supermemory to a Server: Cloudflare Workers Guide

Deploy Supermemory to a server by running bun run deploy for the public Cloudflare-hosted version, bun run deploy from apps/mcp for the MCP server, or bun ./deploy.ts for enterprise self-hosting on your private Cloudflare account.

Supermemory is a cloud-native, serverless platform built exclusively for Cloudflare Workers. The supermemoryai/supermemory repository ships three deployable components: a Next.js Web UI, a Model Context Protocol (MCP) server, and an enterprise self-hosting package for private infrastructure. This guide covers how to deploy Supermemory to a server using the specific file paths, scripts, and environment configurations defined in the source code.

Public Cloudflare Deployment (Web App)

The Supermemory Web App is a Next.js application packaged for Cloudflare Workers via the opennextjs-cloudflare adapter.

Clone and Install

Start by cloning the repository and installing dependencies with bun:

git clone https://github.com/supermemoryai/supermemory.git
cd supermemory
bun install

Configure Environment Variables

The UI reads configuration from apps/web/.env. Copy the example file and edit the required values:

cp apps/web/.env.example apps/web/.env

Critical variables include NEXT_PUBLIC_HOST_ID (provided by Supermemory) and BETTER_AUTH_URL. The apps/web/.env.example file lists all expected variables for the build process.

Deploy the Worker

In apps/web/package.json, the deploy script wraps the Cloudflare build and upload process:

bun run deploy

This command expands to opennextjs-cloudflare build && opennextjs-cloudflare deploy, which bundles the Next.js app and uploads the Worker script to Cloudflare. Upon completion, you receive a route like https://<your-subdomain>.workers.dev.

Optionally, upload source maps to Sentry using the post-deploy hook defined in the same package.json:

bun run postdeploy

MCP Server Deployment

The MCP server provides a stand-alone, OAuth-protected endpoint (https://mcp.supermemory.ai/mcp) that runs on Cloudflare Durable Objects for session state.

Setup and Local Testing

Navigate to the MCP directory and install dependencies:

cd apps/mcp
bun install

Create a .dev.vars file for local development with the main Supermemory API URL:

echo "API_URL=https://api.supermemory.ai" > .dev.vars
bun run dev

Deploy to Production

According to apps/mcp/README.md, deploy the MCP Worker using:

bun run deploy

This executes wrangler deploy, creating the Worker and instantiating a Durable Object for memory persistence. The entry point in apps/mcp/src/index.ts registers the Hono router and Durable Object classes, while packages/lib/auth.middleware.ts handles OAuth and API-key validation.

Enterprise Self-Hosting

For data residency, compliance requirements, or custom connectors, deploy Supermemory to your private Cloudflare account using the enterprise deployment package.

Prerequisites

Before deploying, ensure you have:

• A Cloudflare account with an API Token (permissions: AI Gateway, Hyperdrive, Workers KV, Workers R2)
• A PostgreSQL database with the pgvector extension
• LLM provider keys (OpenAI, Anthropic, Gemini, Groq)

Configuration

Extract the enterprise deployment package and configure the environment variables:

unzip supermemory-enterprise-deployment.zip
cd supermemory-deployment
cp packages/alchemy/env.example .env

# Edit .env with DATABASE_URL, CLOUDFLARE_API_TOKEN, and provider keys

The apps/docs/deployment/self-hosting.mdx file contains the canonical reference for all environment variables and prerequisites.

Execute the Deploy Script

Run the idempotent deployment script included in the package:

bun ./deploy.ts

This script, referenced in the self-hosting documentation, automatically:

• Generates wrangler.toml with proper bindings
• Uploads the compiled Worker bundle (approximately 12MB)
• Creates KV namespaces and R2 buckets
• Binds the PostgreSQL connection via Workers Hyperdrive

Verify the Deployment

Test the API endpoint to confirm successful deployment:

curl -H "Authorization: Bearer sm_<your-api-key>" https://api.<your-custom-domain>.workers.dev/v3/status

A 200 OK response with a JSON status payload indicates the API is live.

Architecture Overview

When you deploy Supermemory to a server, you are deploying three integrated components:

• Supermemory Web UI (apps/web): Next.js frontend running on Cloudflare Workers
• MCP Server (apps/mcp): Model Context Protocol endpoint using Durable Objects for session state
• API Layer: REST endpoints (/v3/*) authenticated via Better-Auth

Data persistence relies on PostgreSQL with pgvector for semantic search, Cloudflare KV/R2 for session blobs and assets, and Hyperdrive for database connection pooling. The client SDK in packages/lib/api.ts connects the UI and MCP server to the API layer using standard fetch calls.

Summary

• Public deployment: Run bun run deploy from the repository root after configuring apps/web/.env
• MCP server: Execute bun run deploy inside apps/mcp with API_URL configured in .dev.vars
• Enterprise self-host: Use bun ./deploy.ts with the enterprise package to deploy private Cloudflare Workers with KV, R2, and Hyperdrive bindings
• Key source files: Reference apps/web/package.json for build scripts, apps/mcp/README.md for MCP workflows, and apps/docs/deployment/self-hosting.mdx for enterprise variables
• Verification: Query /v3/status with your API key to confirm successful deployment

Frequently Asked Questions

What Cloudflare services does Supermemory require?

Supermemory requires Cloudflare Workers for compute, KV for key-value storage, R2 for object storage, and Hyperdrive for database connection pooling. Enterprise deployments also utilize AI Gateway for LLM routing and Durable Objects for MCP session state.

Can I deploy Supermemory without using Cloudflare?

No. The supermemoryai/supermemory source code is specifically architected for the Cloudflare Workers runtime. The Web UI depends on opennextjs-cloudflare as specified in apps/web/package.json, and the MCP server relies on Wrangler configurations that target the Cloudflare platform.

How do I update an existing self-hosted deployment?

Re-run bun ./deploy.ts from the enterprise package directory. The script is idempotent and will overwrite the existing Worker while preserving KV and R2 data. Modify your .env file before running the script if you need to update configuration values like DATABASE_URL or API tokens.

What is the difference between the public and enterprise deployment methods?

The public method deploys only the Web UI to Cloudflare's edge network under Supermemory's managed infrastructure. The enterprise method deploys the complete API stack—including Workers, KV, R2, and Hyperdrive—to your private Cloudflare account, giving you full control over data residency, custom OAuth connectors, and compliance requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}