# How to Deploy Supermemory to a Server: Cloudflare Workers Guide

> Deploy Supermemory to your server with this Cloudflare Workers guide. Learn simple deployment steps for public, MCP, or enterprise self-hosting options.

- Repository: [supermemory/supermemory](https://github.com/supermemoryai/supermemory)
- Tags: how-to-guide
- Published: 2026-03-25

---

**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`:

```bash
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:

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/apps/web/package.json), the deploy script wraps the Cloudflare build and upload process:

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/package.json):

```bash
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:

```bash
cd apps/mcp
bun install

```

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

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

```

### Deploy to Production

According to [`apps/mcp/README.md`](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md), deploy the MCP Worker using:

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/index.ts) registers the Hono router and Durable Object classes, while [`packages/lib/auth.middleware.ts`](https://github.com/supermemoryai/supermemory/blob/main/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:

```bash
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:

```bash
bun ./deploy.ts

```

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

- Generates [`wrangler.toml`](https://github.com/supermemoryai/supermemory/blob/main/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:

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/apps/web/package.json) for build scripts, [`apps/mcp/README.md`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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.