Skip to content
ShareOutShareOut Docs

Self-host ShareOut

import { Steps } from ‘@astrojs/starlight/components’;

Run ShareOut on your Cloudflare account. ShareOut is self-hosted only — there is no hosted cloud product and no ShareOut checkout. You need a Cloudflare account and Cloudflare’s Workers Paid plan (Durable Objects); that billing is Cloudflare’s, not ShareOut’s.

Agents: start here

Section titled “Agents: start here”

If a coding agent is installing ShareOut for you, point it at the deploy skill in the product repo (source of truth for all agent docs):

Do not edit the separate shareout-skill repo as primary — it is a publish mirror. After deploy, agents load GET {ORIGIN}/v1/skill from your Worker.

Prerequisites

Section titled “Prerequisites”
  • Cloudflare account with Workers Paid (required — Durable Objects power tables, realtime, and chat; Cloudflare’s plan, not a ShareOut fee)
  • Node 24+ for local development / CLI deploy
  • GitHub access to the public ShareOut repo (Deploy button clones it)

Deploy

Section titled “Deploy”

  1. CLI (about five minutes) — recommended:

    Terminal window
    git clone https://github.com/getshareout/shareout.git
    cd shareout/shareout-app
    npm ci
    npx wrangler login
    npm run deploy   # provisions D1/R2/KV + SESSION_SECRET + BASE_URL, migrates, deploys

    Or use Deploy to Cloudflare from the public repo README with Root directory shareout-app and Deploy command npm run deploy (not bare npx wrangler deploy).

  2. Open the worker URL. An empty database redirects to /setup. Create the first admin with an email and a password — no mail provider and no OAuth client needed. That registration endpoint closes as soon as the account exists.

    Google sign-in and email one-time codes are both optional additions afterwards.

  3. Publish a hello page to prove the path:

    Terminal window
    export SHAREOUT_ORIGIN=https://shareout.<your-account>.workers.dev
    export SHAREOUT_TOKEN=so_…   # Settings → API tokens after sign-in
    npm run smoke:hello

  4. Prove the data plane (JSON store, tables, datasets):

    Terminal window
    export SHAREOUT_ORIGIN=… SHAREOUT_TOKEN=…
    npm run smoke:data

    Full walkthrough: Data plane smoke.

  5. Point agents at this instance — save credentials with origin:

    { "token": "so_…", "origin": "https://shareout.<your-account>.workers.dev" }

    Then load GET $ORIGIN/v1/skill or the monorepo skill with that origin.

    Your Worker ships its own copy of the skill and rewrites every URL in it to SHAREOUT_BASE_URL before serving. npm run deploy sets SHAREOUT_BASE_URL for you — if you skipped that, GET $ORIGIN/health returns a warnings entry until you set it.

  6. Day 1 extras — set an AI key if you want Create with AI / Crew (OPENAI_API_KEY or Vercel AI Gateway); invite a teammate under Admin; confirm curl …/v1/admin/instance → gaps is empty (or you accept each gap). Details in the repo README Day 1.

Optional next steps

Section titled “Optional next steps”
Goal What to do
Custom domain Domain and DNS — update SHAREOUT_BASE_URL
Google sign-in GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET; callback {origin}/auth/callback
Microsoft sign-in MICROSOFT_CLIENT_ID + MICROSOFT_CLIENT_SECRET (optional MICROSOFT_TENANT); callback {origin}/auth/microsoft/callback — setup
Email one-time codes Configure the EMAIL binding + from-address vars
Workspace subdomains Wildcard DNS → worker; see Domain and DNS
Split content CDN Set ARTIFACT_ORIGIN to a second zone (optional hardening)

Same-zone serving (no CDN) is the default and is fine for most self-hosts.

What degrades without Cloudflare Paid / optional bindings

Section titled “What degrades without Cloudflare Paid / optional bindings”
Binding If missing
Durable Objects Core product incomplete — need Cloudflare Workers Paid
EMAIL One-time codes and lifecycle mail → worker logs. Password sign-in is unaffected
AI / VECTORIZE Semantic search → keyword fallback
BROWSER No thumbnails / browser smoke
Queues Analytics ingest may lag or sync-fallback

Details: Architecture · Ops.