![\"Kraki\"](\"https://raw.githubusercontent.com/corelli18512/kraki/main/logo.png\"){kind=logo}
\n \n\n \n \n \n
\n GitHub repository\n
\n\n# @kraki/head\n\nThin encrypted relay that forwards messages between tentacles and apps.\n\n> Preview: `@kraki/head` is still early-stage. Expect breaking changes while the hosted and self-hosted flows stabilize.\n\nUse `@kraki/head` when you want to self-host the Kraki relay instead of using the hosted default.\n\n## Install\n\nRun it once with `npx`:\n\n```bash\nnpx @kraki/head\n```\n\nOr install it globally:\n\n```bash\nnpm i -g @kraki/head\nkraki-relay\n```\n\n## Quick start\n\nStart a local relay:\n\n```bash\nnpx @kraki/head\n```\n\nBy default the relay listens on `ws://localhost:4000` and stores user/device data in `kraki-head.db`.\n\nEnable GitHub login for the web app:\n\n```bash\nGITHUB_CLIENT_ID=your_client_id \\\nGITHUB_CLIENT_SECRET=your_client_secret \\\nnpx @kraki/head --auth github\n```\n\n## What the relay does\n\nThe relay has three jobs:\n\n1. **Authenticate** — verify device identity on connect\n2. **Forward blobs** — route unicast and broadcast envelopes to the right WebSocket connections\n3. **Track identity** — maintain users and devices tables\n\nIt stores no messages, no sessions, and no content. All message bodies are encrypted blobs that the relay cannot read.\n\n## Diagnostic log collection is a separate service\n\nClient diagnostic metadata is collected by [`@kraki/monitor`](../monitor/README.md),\nnot this relay. Route `/api/diag/v1/*` to the independent collector (default\nloopback port4011). Head returns404 for these paths and no longer embeds a\ncollector when `KRAKI_DIAG_DIR` is set. Existing embedded-mode deployments must\nmove that route to Monitor before upgrading Head; independent `kraki-diag`\ndeployments do not require a Head restart. See Monitor's migration instructions.\n\n## Useful options\n\n```bash\nkraki-relay --port 8080\nkraki-relay --db /path/to/kraki-head.db\nkraki-relay --auth open\nkraki-relay --auth github\nkraki-relay --log debug\n```\n\n## Auth methods\n\nThe relay supports multiple authentication methods as a discriminated union: `github_token`, `github_oauth`, `pairing`, `challenge`, `apikey`, and `open`.\n\n## Package naming\n\n- `@kraki/head` installs the `kraki-relay` CLI\n- `@kraki/tentacle` installs the `kraki` CLI\n\n## Links\n\n- Main docs: `https://github.com/corelli18512/kraki/blob/main/README.md`\n- Security model: `https://github.com/corelli18512/kraki/blob/main/SECURITY.md`\n","readmeFilename":"README.md"}