Skip to content

Setup Guide

Jump to bottom
Rahil P edited this page Jul 15, 2026 · 8 revisions

Second Brain can be set up three ways. The desktop app is the easiest — it does everything for you with no terminal. The one-click Cloudflare button and manual install are for people who'd rather deploy the Worker themselves.

Desktop app (recommended)

The desktop app is the easiest way to set up Second Brain. It creates your Second Brain in your own Cloudflare account and connects your AI tools for you — no terminal, no git, and no configuration values to copy.

1. Download

Download the latest release for your computer:

  • Mac (Apple Silicon and Intel): Second Brain_<version>_universal.dmg
  • Windows: Second Brain_<version>_x64-setup.exe

⬇ Download the desktop app

2. Install

Mac — Open the .dmg, drag Second Brain into your Applications folder, then open it. The Mac build is signed and notarized by Apple, so it opens with no security warnings.

Windows — Run the downloaded .exe. The Windows build is not yet code-signed, so Windows may show a SmartScreen "Windows protected your PC" notice on first launch — click More info, then Run anyway. (Windows code signing is in progress.)

3. Set up (about two minutes)

Open the app and follow the on-screen steps:

  1. Choose a password. This is the key to your Second Brain — keep it somewhere safe. You'll need it to connect new tools later and to set up other computers.
  2. Sign in to Cloudflare, or create a free account in the same window.
  3. The app builds your Second Brain in your own private Cloudflare account and connects your AI tools for you — one-click for Claude Code and Cursor, and copy-and-paste for ChatGPT and Claude on the web.
  4. It shows your two links to keep: your Second Brain address (your dashboard) and your AI connection link (…/mcp).

Because the app connects your AI tools during setup, you can skip the Connect your AI clients section below — that step is only needed for the one-click and manual methods.

Already have a Second Brain?

Setting up a new computer, or already deployed with the Cloudflare button? On the welcome screen choose "Already have a Second Brain?" and enter your address and password. The app connects that computer without changing or re-deploying anything.

Every launch after setup

The app opens straight into your dashboard, already signed in. Your two links are always available from the menu bar or tray under Connection details. Log out (in the Connections menu, or the Connection details window) forgets only that computer — your Second Brain and its memories stay safe, and you can reconnect anytime.

One-click deployment

Deploy the Worker into your own Cloudflare account with a single button. Use this if you'd rather set it up yourself instead of using the app.

Before clicking the button, generate a secure authentication token:

openssl rand -base64 32

Save the token somewhere secure. You will need it to authorize AI clients and test your deployment.

Keep these values handy when Cloudflare displays the configuration form:

FIELD VALUE
AUTH_TOKEN A secure token you create
DIMENSION 384
METRIC cosine

Deploy to Cloudflare

Important

Enter 384 for DIMENSION and select cosine for METRIC. These values must match the embedding model used by Second Brain.

Cloudflare will:

  • Fork the repository into your GitHub account
  • Create the D1 database
  • Create the Vectorize index
  • Create the OAuth KV namespace
  • Configure the required Worker bindings
  • Store your AUTH_TOKEN as a secret
  • Deploy the Worker

No manual SQL or Cloudflare resource setup is required. Once deployment completes, skip to After deployment.

Manual installation

For developers who want full control. Use this path if you want to deploy from a local clone, customize the configuration, or manage Cloudflare resources yourself.

Prerequisites

  • Node.js 18 or newer
  • npm
  • Git
  • A Cloudflare account (free tier is sufficient for personal use)

1. Clone the repository

git clone https://github.com/rahilp/second-brain-cloudflare.git
cd second-brain-cloudflare
npm install

2. Authenticate with Cloudflare

npx wrangler login

A browser window will open to authorize Wrangler to access your Cloudflare account.

3. Create the D1 database

npm run db:create

Copy the generated database_id into the D1 binding in wrangler.jsonc:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "second-brain",
      "database_id": "YOUR-DATABASE-ID"
    }
  ]
}

4. Create the Vectorize index

npm run vectors:create

The index must use these values:

SETTING VALUE
Dimensions 384
Metric cosine

Important

The Vectorize dimensions and metric must match the embedding model used by Second Brain.

5. Create the OAuth KV namespace

npx wrangler kv namespace create OAUTH_KV

Copy the generated namespace ID into the OAUTH_KV binding in wrangler.jsonc:

{
  "kv_namespaces": [
    {
      "binding": "OAUTH_KV",
      "id": "YOUR-KV-NAMESPACE-ID"
    }
  ]
}

6. Set your authentication token

Generate a secure token:

openssl rand -base64 32

Save the value, then add it as a Worker secret:

npx wrangler secret put AUTH_TOKEN

Paste the token when Wrangler prompts you.

7. Deploy the Worker

npm run deploy

The database schema and indexes are created automatically on the first request. No migration step is required.

After deployment

The steps below apply to the one-click and manual methods. If you used the desktop app, it already found your Worker URL, tested the deployment, and connected your AI tools for you — you're done.

Find your Worker URL

One-click deployment: Open the Cloudflare dashboard and go to Workers & Pages > second-brain.

Manual deployment: Wrangler will display the Worker URL after deployment completes.

Your Worker URL will look similar to:

https://second-brain.your-subdomain.workers.dev

Copy this URL. You will need it when connecting AI clients.

Test the deployment

Replace YOUR-WORKER-URL and YOUR-AUTH-TOKEN with your own values:

curl -X POST https://YOUR-WORKER-URL/capture \
  -H "Authorization: Bearer YOUR-AUTH-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"second brain is working","source":"test"}'

A successful response looks like:

{"ok":true,"id":"..."}

Open the dashboard

Open your Worker URL in a browser:

https://YOUR-WORKER-URL

The test memory should appear in the dashboard.

Connect your AI clients

Your MCP connector URL is:

https://YOUR-WORKER-URL/mcp

Continue to the Connect to AI Clients guide for setup instructions covering ChatGPT, Claude.ai, Claude Desktop, Claude Code, Codex CLI, and other MCP-compatible clients.

Compatible clients will open a browser login page where you can authorize the connection using your AUTH_TOKEN. Clients that cannot open a browser can authenticate directly with:

Authorization: Bearer YOUR-AUTH-TOKEN

Useful scripts

SCRIPT DESCRIPTION
npm run dev Start the local development server
npm run deploy Deploy the Worker to Cloudflare
npm run db:create Create the D1 database
npm run db:migrate Apply the schema to local D1
npm run db:migrate:remote Apply the schema to the remote D1 database
npm run vectors:create Create the Vectorize index
Local development

Start the local Worker:

npm run dev

Wrangler will display a local URL similar to:

http://localhost:8787

The local database schema will be created automatically on the first request.

Test a local request

Replace YOUR-AUTH-TOKEN with the token configured for local development:

curl -X POST http://localhost:8787/capture \
  -H "Authorization: Bearer YOUR-AUTH-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"local second brain test","source":"test"}'

Local development limitations

Cloudflare Vectorize and Workers AI are remote services. During local development:

  • Entries can still be stored in D1
  • The dashboard and REST endpoints can still be tested
  • Embedding requests may be unavailable
  • Semantic recall may not return results

Embedding failures are handled gracefully. Entries will still be stored in D1 even when vectors cannot be generated.

To develop against your live Cloudflare resources, run:

npx wrangler dev --remote
Troubleshooting

Unauthorized response

Confirm your request includes:

Authorization: Bearer YOUR-AUTH-TOKEN

Common causes:

  • Missing Bearer prefix
  • Extra quotation marks or spaces
  • Using the example token instead of your own
  • Token does not match the Worker secret

To replace the token after a one-click deployment:

  1. Open the Cloudflare dashboard.
  2. Go to Workers & Pages > second-brain.
  3. Open Settings > Variables and Secrets.
  4. Edit AUTH_TOKEN.
  5. Update any connected clients that still use the old token.

For a manual deployment, run:

npx wrangler secret put AUTH_TOKEN

Database table not found

The schema is created automatically on the first request. If the error persists, run:

npm run db:migrate:remote

Also confirm the DB binding points to the correct D1 database.

Semantic search is not working

Confirm that:

  • The Vectorize index uses 384 dimensions and the cosine metric
  • The Vectorize binding points to the correct index
  • Workers AI is available in your Cloudflare account
  • You are testing the deployed Worker or using npx wrangler dev --remote

An index created with different dimensions or a different metric will not work correctly with the configured embedding model.

Worker URL not found

Open Cloudflare Dashboard > Workers & Pages > second-brain. The Worker URL appears on the deployment page.

Dashboard does not load

Open the base Worker URL:

https://YOUR-WORKER-URL

Do not add /mcp. The /mcp endpoint is only for AI-client connections.

OAuth login does not open

Confirm that the client is using:

https://YOUR-WORKER-URL/mcp

Also confirm:

  • The client supports browser-based OAuth
  • The OAUTH_KV binding exists
  • Browser windows or pop-ups are not blocked

Headless clients can authenticate directly with:

Authorization: Bearer YOUR-AUTH-TOKEN

Deployment failed

Common causes:

  • Missing D1 database
  • Missing Vectorize index
  • Incorrect Vectorize dimensions or metric
  • Missing OAuth KV namespace
  • Missing AUTH_TOKEN
  • Wrangler connected to the wrong Cloudflare account

Check the authenticated account:

npx wrangler whoami

Then redeploy:

npm run deploy

Clone this wiki locally