# Kraken

> Kraken is real-time sync infrastructure for the CubiCube platform. It powers local-first collaboration—watch parties, cooking sessions, game nights, shared lists—while keeping data on users' devices. Kraken coordinates sync; it doesn't store your data.

**What You Can Build:**
- Watch parties with synchronized playback
- Video chat rooms (peer-to-peer, no third parties)
- Shared lists, notes, and collaborative documents
- Live activities: workouts, study groups, cooking together
- Real-time polls and group decisions
- Any feature that needs multiple users in sync

**How It Works:**
- Data lives locally in each user's Core Cubi
- Kraken syncs changes between connected users
- Works offline—changes merge when you reconnect
- Each deployment gets isolated rooms automatically

## Docs

- [Integration Guide](https://kraken.helixpods.ai/docs): Setup walkthrough for Core Cubi developers
- [Live Demos](https://kraken.helixpods.ai/demos): Try collaborative features in your browser

## Endpoints

- [WS /doc/:room](wss://kraken.helixpods.ai/doc/:room): Real-time document sync (requires auth token)
- [WS /webrtc/:room](wss://kraken.helixpods.ai/webrtc/:room): Video/audio signaling for peer-to-peer calls
- [GET /health](https://kraken.helixpods.ai/health): Service status check
- [GET /api/stats](https://kraken.helixpods.ai/api/stats): Server statistics (auth required)
- [POST /api/apps](https://kraken.helixpods.ai/api/apps): Register your Core Cubi (auth required)

## Integration

Add Kraken credentials to your Core Cubi's `wrangler.jsonc`:

```jsonc
{
  "vars": { "KRAKEN_URL": "wss://kraken.helixpods.ai" },
  "secrets_store_secrets": [{
    "binding": "KRAKEN_TOKEN",
    "store_id": "7abc511fc4b74147808e542ece047670",
    "secret_name": "NEXARTIS_KRAKEN_WEBRTC_SERVER_ACCESS_TOKEN"
  }]
}
```

Create a token endpoint, then connect from your Svelte 5 components:

```typescript
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';

const doc = new Y.Doc();
const provider = new WebsocketProvider(krakenUrl, 'my-room', doc, { params: { token } });
```

Required packages: `yjs`, `y-websocket`, optionally `@kraken/client` for WebRTC.

## Authentication

All connections require a bearer token in the WebSocket URL params:

```
wss://kraken.helixpods.ai/doc/my-room?token={your-token}
```

Tokens are stored in Cloudflare Secrets Store. Your Core Cubi retrieves the token server-side and passes it to the client. Rooms are automatically namespaced by your app's origin—your data stays isolated.

## Optional

- [CubiCube Platform](https://cubicube.com): Local-first application platform
- [Nexartis](https://nexartis.com): Infrastructure for data sovereignty