Ocean Brain

A self-hosted writing space for connected notes.

Write in the browser, link notes together, and keep the workspace on your own server.

Ocean Brain is inspired by Zettelkasten-style note taking: small notes, deliberate links, and ideas that can build on each other over time.

What it is

Ocean Brain focuses on the writing experience first, then adds enough structure to keep notes connected: links, backlinks, tags, saved views, graph navigation, search, reminders, and calendar views.

It is meant for project notes, decisions, research, learning notes, and ideas you expect to revisit.

Why connected notes?

A note is easier to reuse when it points to related notes.

Ocean Brain keeps that connection close to the writing flow. You can write a note, link it to another note, and later follow backlinks or views to see where that idea has been used.

Try it now

Live Demo - Try the hosted demo

Quick Start

npx ocean-brain / docker run baealex/ocean-brain now require explicit auth configuration.
Choose one of the two modes below:

npx

npx ocean-brain serve --allow-insecure-no-auth

Local/trusted only (no auth).
For password mode:

OCEAN_BRAIN_PASSWORD=change-me \
OCEAN_BRAIN_SESSION_SECRET=replace-with-long-random-secret \
npx ocean-brain serve

Open http://localhost:6683 after startup.

Docker

The examples below use Docker's default floating tag (latest) for quick trials.
For production, pin an exact image tag such as baealex/ocean-brain:<version>.

No auth (local/trusted only):

docker run -d \
    -e OCEAN_BRAIN_ALLOW_INSECURE_NO_AUTH=true \
    -v ./assets:/assets \
    -v ./data:/data \
    -p 6683:6683 \
    baealex/ocean-brain

Password mode:

docker run -d \
    -e OCEAN_BRAIN_PASSWORD=change-me \
    -e OCEAN_BRAIN_SESSION_SECRET=replace-with-long-random-secret \
    -v ./assets:/assets \
    -v ./data:/data \
    -p 6683:6683 \
    baealex/ocean-brain

If neither password env vars nor OCEAN_BRAIN_ALLOW_INSECURE_NO_AUTH=true is set, startup fails by design.

From Source

pnpm install
pnpm build
OCEAN_BRAIN_ALLOW_INSECURE_NO_AUTH=true pnpm start

Local/trusted only (no auth).
For password mode:

pnpm install
pnpm build
OCEAN_BRAIN_PASSWORD=change-me \
OCEAN_BRAIN_SESSION_SECRET=replace-with-long-random-secret \
pnpm start

Local Development (5173 + 6683)

When using pnpm dev in password mode, set password/session env values:

OCEAN_BRAIN_PASSWORD=change-me \
OCEAN_BRAIN_SESSION_SECRET=replace-with-long-random-secret \
pnpm dev

PowerShell:

$env:OCEAN_BRAIN_PASSWORD="change-me"
$env:OCEAN_BRAIN_SESSION_SECRET="replace-with-long-random-secret"
pnpm dev

If you run server/client in separate terminals, only the server terminal needs password/session env values.

Core features

Data, recovery, and backups

Ocean Brain provides everyday recovery paths, but it is not a replacement for regular backups.

• Deleted notes can be recovered from Trash for a limited time.
• Recent note snapshots can help recover from common editing mistakes.
• Individual notes can be exported as Markdown or HTML.
• For full-instance safety, back up the database and assets used by your deployment.

MCP Server

Ocean Brain includes a built-in MCP (Model Context Protocol) server for AI tool integration.

Setup

1. Open Settings > MCP in Ocean Brain.
2. Turn on Allow MCP access.
3. Click Rotate token.
4. Recommended: save the token to a local file and use --token-file.
5. Optional: for quick local setup, pass token directly with --token.
6. If your public/proxy host differs from the current app origin, edit the server URL before registering.

Example Claude Code .mcp.json:

{
  "mcpServers": {
    "ocean-brain": {
      "command": "npx",
      "args": [
        "-y",
        "ocean-brain",
        "mcp",
        "--server",
        "http://localhost:6683",
        "--token-file",
        "/path/to/token.txt"
      ]
    }
  }
}

The service keeps a single active MCP token. Rotating token invalidates the previous token immediately.
--token-file is recommended for safety, but --token <value> is also supported.

Available Tools