Helix docs

Run your own vault

What's open and what isn't, stated plainly up front: everything you need to own your context by yourself is open source under AGPL-3.0 — the vault, the MCP server, the consent and audit screens, the owner door, and the iOS and Android apps. What is not open is the developer platform: the third-party app door (/api/*), app registration, billing and the partner console. The rule is single-player open, multiplayer commercial. If you want a vault for yourself and your family, clone it and it's yours, forever, with no asterisk. If you want to build a business on other people's vaults, that runs through the hosted platform and that is how Helix pays for itself.

Self-hosting costs nothing in practice: a personal vault fits inside Cloudflare's free tier.

What you get

  • Your vault, on your own Cloudflare account, on your own domain.
  • The MCP endpoint, so Claude, ChatGPT and any other MCP client connect to your server — no Helix in the path.
  • The owner door, so the iOS and Android apps point at your vault.
  • Full export at any time in the published spec format — and import, so moving a hosted vault here is one upload.

Prerequisites

  • A Cloudflare account (free tier is fine) and npx wrangler login.
  • Node 20+.
  • Optional: an OpenAI key for image generation, an ElevenLabs key for voice, a Resend key for email. Leave them out and those features simply stay off.

Deploy

git clone https://github.com/jrhodes2705/helix-mcp
cd helix-mcp
npm install

# create the two KV namespaces, then paste the ids into wrangler.jsonc
npx wrangler kv namespace create OAUTH_KV
npx wrangler kv namespace create VAULT_KV

# the cookie/token signing secret — generate, don't invent
npx wrangler secret put COOKIE_SECRET

npx wrangler deploy

The deploy prints a *.workers.dev URL. Set PUBLIC_ORIGIN in wrangler.jsoncto match it (or to your custom domain) and deploy once more — OAuth metadata is absolute, so a wrong origin will fail the discovery handshake in a way that's tedious to debug.

Optional secrets

npx wrangler secret put OPENAI_API_KEY      # generate_image
npx wrangler secret put ELEVENLABS_API_KEY  # generate_speech
npx wrangler secret put RESEND_API_KEY      # verification + reset email
npx wrangler secret put TURNSTILE_SECRET_KEY
npx wrangler secret put ADMIN_PASSWORD

With no email provider configured the signup flow shows the verification link on screen instead of mailing it — fine for a vault with one user. Password-reset links are never shown on screen, so set up email before you need one.

Backups

A nightly cron dumps the whole vault to an R2 bucket and prunes anything older than thirty days. Create a bucket, point the BACKUPS binding at it, or delete the r2_buckets and triggersblocks if you'd rather back up by hand with /account/export.

Connecting a client

Sign up at https://your-vault/signup, then add https://your-vault/mcp as a custom connector in Claude or ChatGPT. The vault is its own OAuth server with dynamic client registration, so there is nothing to register anywhere. The mobile apps take a vault URL on their first screen.

Honest limitations

  • Not end-to-end encrypted. Data is encrypted at rest in Workers KV, but the operator can read it. Self-hosting means that operator is you rather than us — which is the strongest privacy answer available today. See the security note.
  • Some things don't survive a move. Export and import are both live, so bringing a hosted vault here is a file upload. But the audit log, voice verification and app grants stay behind by design — see the spec for why.
  • Third-party apps won't find you. Apps built on the developer platform authenticate against the hosted service. A self-hosted vault serves you and your assistants, not an app ecosystem.

Why AGPL

The licence keeps the vault honest. If someone runs a modified Helix as a service, their users are entitled to that modified source — which means nobody can take these guarantees, quietly remove the audit log or the consent gate, and still call it Helix. It costs a self-hoster nothing: running it for yourself, your family or your company triggers no obligation at all.