Skip to main content
Glama
Digital Spine

Digital Spine

Official
by 8scope
README.md
# 8scope-workspace-starter

An MIT-licensed, self-hosted Digital Spine instance for each customer. It starts with an empty SQLite database and its own owner identity. The first data source is WhatsApp message history shared by WA Bridge. The web app uses Node.js 24 with zero npm dependencies.

## Start an installation

From this directory, run each command once and save its output privately. Running a command again rotates that key. This code ships without keys, accounts, or provider credentials.

```sh
npm run key -- owner
npm run key -- bridge
npm start
```

1. Open `http://127.0.0.1:3780` and unlock the chat approvals page with the owner key.
2. In WA Bridge's Assistant/Digital Spine connection settings, enter `http://127.0.0.1:3780/api/public/whatsapp-archive` and the `waa_live_` bridge key. Enable sync. The first sync sends the catalog for locally shareable chats. The first committed batch pairs the archive with that desktop.
3. Refresh the web app and approve the chats you want to share. Sync again in WA Bridge. Its local conversation, sender and date restrictions still apply.
4. To connect ChatGPT, host the starter at an HTTPS origin, then create an MCP connection to `https://your-host/mcp` using OAuth. Leave manual client credentials blank for dynamic registration. Enter the owner key on the consent page, review the requested archive access, and choose **Allow access**. For a local MCP client with custom headers, optionally generate a key with `npm run key -- mcp` and send it as `Authorization: Bearer <mcp-key>` to `http://127.0.0.1:3780/mcp`.

The bridge receiver implements the WA Bridge v2 contract for status, selections and message events. It keeps its source checkpoint across restarts, validates the selection revision, applies a batch atomically and acknowledges an exact replay of the last committed batch. It returns an empty outbox for the desktop's periodic poll.

MCP follows Digital Spine's initialize-based Streamable HTTP flow and OAuth discovery, dynamic client registration, owner consent, PKCE, refresh rotation and revocation routes. Its only permission is `whatsapp:read`. The tools are `list_archive_conversations` and `get_archive_thread`. Use the returned `sourceId` and `conversationId` to read a chat, and pass `nextOffset` back as `offset` for the next page. Create a connection for this starter, since the full Digital Spine plugin requests permissions this instance does not offer.

The starter supports one desktop, up to 500 approved chats, and manual selection of chat history. Media files, analysis artifacts, desktop notes, summaries, thread cards and automatic tracking stay outside the starter. The service has no agents, model calls, email connections, outbound messaging or telemetry.

## Data and owner control

- Before approval, SQLite stores the shareable catalog's chat ID, name, type and last update time. Catalog entries are only listed to the owner in the web app.
- For approved chats, SQLite stores the message ID, chat ID, timestamp, type, sender display name, whether the message is outgoing, and text. The desktop's existing wire payload can include raw WhatsApp data and additional sender identifiers. The receiver discards those fields and stores only a digest of the last committed batch for replay detection.
- Revoke a chat in the web app to delete its saved messages and remove it from the MCP catalog. The catalog entry remains available for future approvals. WA Bridge may remember prior deliveries, so re-approval does not guarantee that deleted history is sent again.
- Export full stored data with `node src/export.js > archive.ndjson`. Stop the app first for a consistent export. The MCP tools return text previews up to 2,000 characters per message. Once an MCP client retrieves data, its own storage and retention settings apply.
- Back up `data/archive.sqlite` while the app is stopped. The database contains readable archive data, sync state, and key hashes. Removing it while stopped erases the installation's local copy and resets its identity and checkpoints. Delete any backups and exports separately if you want those copies erased.
- Rotate access locally with `npm run key -- <owner|bridge|mcp>`. Add `--revoke` to disable that key. Revoking MCP also ends all OAuth connections to the instance. The owner key entered into the web app stays in tab memory until the page is locked or reloaded.

## Host a copy

The server binds to `127.0.0.1`. For remote access, put a TLS reverse proxy on the same host in front of it. Set `SPINE_PUBLIC_URL` to the external HTTPS origin without a trailing slash, preserve the original `Host` and `Authorization` headers, and forward requests without rewriting paths. Use the HTTPS URL in both clients. Keep the database on a persistent, customer-controlled volume and restrict shell and filesystem access to its operator. When duplicating the source, leave out `data/` and any database files or exports. OAuth callback URLs are limited to Digital Spine's supported ChatGPT callbacks on HTTPS deployments and include loopback callbacks for local development.

Set `PORT` to change the default port and `ARCHIVE_DB` to change the SQLite path. Use the same database path for the app, key commands and export.

## Verify

```sh
npm test
```

The HTTP tests use synthetic chats and an isolated database.