HappyToHelp

HappyToHelp is an open-source support workspace with a customer chat widget, shared inbox, AI-assisted replies, help centers, customer context and optional work delegated to your own Codex or Claude. It works with human replies without an AI provider. The editable React application runs on Cloudflare Workers with Hono, D1, R2, Queues and Durable Objects.

Release 0.5.0

Version 0.5.0 adds Help Scout response-body imports, deliberate uncertain webhook resends, a guided local-agent fix flow and provisioned new workspaces with a simpler Setup page. Re-imports preserve native edits. Commands use the published @runeditrun/rer package pinned to 0.2.23; local dev starts without private setup answers. rer deploy claims the hosted owner named by OWNER_EMAIL for you; that owner signs in by email and opens Setup. Existing owners are preserved. Back up and apply 120_activation_observations.sql then 121_move_in_categories.sql before the updated Worker starts. See Updates and recovery and the changelog.

Version 0.4.0 adds Move in for reviewed support-history imports, resolution feedback with workspace-calendar Reports, Connections with scoped API tokens, signed webhook events and Slack delivery, and the rer local path. Native passwords, owners and data are kept. Before the updated Worker serves traffic, back up and apply the ten additive migrations 0110_move_in.sql to 119_local_portability.sql in order; an existing 0.3 installation follows Upgrading from 0.3.x. The changelog lists every change. Known limits:

• Accessibility is on a confirmed owner HOLD; no WCAG conformance is claimed.
• Backups cover D1 and R2, not Durable Object storage, and full portable-storage fidelity is not established.
• Hosted operating costs are unmeasured; timed activation and paid-provider execution are not qualified.
• Imports and connections are qualified with synthetic fixtures only, without real vendor exports or live Slack.
• No hosted installation, compliance or FedRAMP qualification is claimed.
• The hosted service at app.happytohelp.com is separate legacy production and is not part of this release.

Run it on your computer

Start with the public run guide for installation, local sign-in and stopping the app.

You need Node.js 22 or later (with npm) and Git. Check with node --version; if it is older or missing, install Node 22 from nodejs.org, or with a version manager (nvm install 22, fnm install 22, or brew install node@22 on macOS). The global rer command itself needs that Node. It then provisions the checkout's own pinned Node and pnpm. Install dependencies, then start local setup:

npm install -g @runeditrun/rer@0.2.23
git clone https://github.com/just-every/run-happytohelp
cd run-happytohelp
rer install
rer dev

Dev uses its local address for the chat widget and generates a private owner password. Wait for RER_READY, then open the RER_OPEN address to enter as the real local owner and reach Setup. No private answers, email service or AI account are needed. Use rer dev --stop from the checkout to stop the managed app.

Already running 0.3? Keep your checkout and data, and follow Upgrading from 0.3.x instead. See Install for private setup answers and Local command reference for ports, preview and idle shutdown.

To try the customer flow, install the widget on a local page, send a visitor message and reply from Inbox. Set that page's exact origin in Settings → Widget → Settings; the app's own origin remains allowed. A visitor's entered email can receive operator replies even when their identity is labelled Unverified. Local visitor and teammate mail is suppressed without storage or external sending. With a hosted sender, Email sent to provider · delivery not confirmed on a reply means acceptance, not confirmed inbox delivery.

Choose how to run it

Local dev is a loopback trial on your computer. An online installation in your own Cloudflare account lets the widget on your website reach the workspace. Both use the same rer commands. An independently managed project may select its own operating contract; this seed's CLI is not a platform admission requirement.

Deploy to your own Cloudflare account

Read deployment prerequisites, configure the real declaration and private account credentials, then:

rer deploy --dry-run
rer deploy --environment production

With rer 0.2.23, supply the same private EMAIL_PROVIDER, EMAIL_FROM and EMAIL_API_KEY inputs for dry run and real deployment. Dry run validates their shape and the build locally, makes no provider request and sends no mail. Deployment provisions declared resources, applies migrations, publishes and checks health through Base deploy-kit. After a healthy deploy, rer deploy claims the owner named by OWNER_EMAIL (a real setup owner, or the value you supply privately) with a one-time token it then removes. Open your Worker's address and sign in by email as that owner to reach Setup. The owner's name is derived from their email. A Workers hostname does not name your business: a workers.dev website defaults to My workspace regardless of owner email. An explicitly chosen native workspace name takes precedence; you can change it in Project settings. Deploy refuses the local placeholder owner@run-happytohelp.test: it has no mailbox. Supply a real OWNER_EMAIL privately in your environment or an owned 0600 --env-file for both dry run and deployment. rer signin --environment production directs you to this installation's /login page. HappyToHelp uses its native email/password sign-in; the command cannot mint an owner link. If mail fails, follow the working mail recovery in operations. rer deploy --environment NAME --remove --yes removes that environment's created Worker, D1, R2 and queues in one pass, including uploaded attachments in its R2 bucket, and reads back that each is gone. Export anything you need before removal. Hosted installation and real provider execution are not qualified by this release.

What you need and what it costs

HappyToHelp is MIT licensed with no seats or subscription fees. Your Cloudflare, email and optional AI providers bill your own accounts. Enable R2 and the account capabilities required by the declaration before deployment. An email sender must be verified. Local development needs no external mail or AI credential.

Configure optional model keys, Apify crawl, Qdrant search, GitHub and email only when you need them. See Optional features and their settings and Measure local usage and costs. The optional local agent runs on the computer doing the support work and has its own runtime prerequisites.

After you install

Your workspace is already set up when you first sign in. It has a starter assistant for visitors, a reply-by-email mailbox when the installation holds an INBOUND_EMAIL_TOKEN, and mail that leaves from the installation's own sender until your sending domain is verified. The inbound token authenticates incoming mail; configure your email provider's domain routing and webhook before replies can arrive. Creating the workspace may send you one welcome email. Use Setup in the workspace sidebar: Needs you lists what cannot be done for you (the widget on your website, an AI key and, with a hosted email provider, your sending domain's DNS records), and What we've set lists the rest. Anything under Needs you can be skipped for now and picked up later from Skipped. The system runs its own checks while Setup is open, and what it confirms is counted ("N of M confirmed", without what you skipped): mail to you, sender DNS, inbound mail, model access, spend ceilings, widget origin and an authenticated widget visit. Saved settings alone do not complete them. Add the widget through Settings → Widget, set its exact website origin, publish useful articles and invite teammates through Settings → Agents. By default the widget does not ask for an email. For visitors to receive replies by email, enable Settings → Widget → Settings → Required contact details → Require email. The visitor enters their address before sending a message; operator replies can then use it on a hosted installation with email sending configured.

Set up AI replies

Your starter assistant answers visitors by itself, from the help articles you publish and from what we read on your website, and within your daily limits, as soon as the installation has a key from an AI provider. Until then, new conversations stay with your team and the AI page and Setup say a key is missing.

1. Get an API key from OpenAI, Anthropic, Google, DeepSeek, xAI or OpenRouter. The provider bills you for what you use.
2. Add the key to your installation under the name for that provider: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY (or GEMINI_API_KEY), DEEPSEEK_API_KEY, XAI_API_KEY or OPENROUTER_API_KEY. The setup answers can store one at install time (see Install).
   • On Cloudflare: in the Cloudflare dashboard, open your Worker, go to Settings → Variables and Secrets and add the key as a secret. You can also set it in your terminal before you run rer deploy --environment production (see Optional features and their settings).
   • On your own computer: add a line such as OPENAI_API_KEY=your-key to a file named .dev.vars in the run-happytohelp folder, then restart the app.
3. Setup notices the key. While the starter assistant is untouched it uses a model of whichever provider's key is installed, and Setup confirms the key with the provider. To use a different assistant, open AI in the sidebar, add one (or choose Customize on an existing one), enter the Model it uses and keep it Enabled. Then, under Responder defaults, choose which assistant answers visitors.

Keep key values out of chat messages and the browser. To cap what visitors can spend, see Limits and AI ceilings.

Try a demo inbox

When your workspace has no conversations yet, the inbox greets you with one next action and a quiet Try a demo inbox link under it. The link creates a separate, clearly labelled workspace called Demo inbox · Northstar Outfitters, with:

• fictional customer conversations
• a drafting assistant you can edit
• three published FAQ articles

Creating the demo makes no AI, email or other provider calls. To see AI drafting, open a demo conversation and press Generate. HappyToHelp then drafts suggested replies for you to review, using your AI provider. The demo's assistant uses OpenAI's gpt-5.6-luna model, so this needs OPENAI_API_KEY unless you change the assistant's model (see Set up AI replies). Generate never sends a reply to a customer.

When you are done, delete the demo workspace from its settings.

Support history, feedback, Reports and connections

Owner/admin Move in reviews five kinds: conversations, contacts, tags, saved replies and articles. Inspect per-kind plans, rejections, omissions, conflicts and publication changes; approve, resume a stopped batch, follow report links, repeat or undo through the same current role checks. Original source IDs, timestamps and private notes remain attributed; published articles stay published and drafts stay drafts. Apply and undo are inert: no mail, widget messages, model work, assignment or connection notifications. The moving-in guide explains formats, source custody and conflict-safe undo. Validation is documented-format, synthetic-only; realExport: not-supplied. The 9 October owner ruling requires exact business-state equality on repeat and undo. Platform counters/sequences, audit and import journals are excluded; business notes, source links, identities and native contact content remain checked.

A resolved widget conversation asks Did this answer your question? with thumbs up/down and an optional comment up to 1,000 characters. Only its owning visitor session can rate its current closed cycle; widget action limits apply and changes retain history. Native records store AI, assisted, human or unknown provenance. A visitor message reopens the conversation; another resolution gets its own record. Reports uses the workspace timezone and 7/30/90-day or custom calendar ranges for volume, median/p90 first response and resolution times, AI resolution and satisfaction counts/rates, daily series and latest comments with conversation links. Conversation and summary CSV exports guard formula-leading cells. Imports are excluded and Reports calls no model. The Reports guide and workspace workflows explain the denominators.

Settings offers seven explicit token scopes, optional expiry, one-time secret display, hashed storage, revoke, last use and audit. The API guide contains thirteen Bearer-only operations. Webhooks support four signed events, explicit test sends and safe attempt logs; public HTTPS destinations are checked against SSRF. Slack has incoming-webhook and bot-plus-channel modes. Both have recorded-response checks only; live Slack: not-supplied. Deliveries use ordinary platform HTTPS fetch with manual redirects. Every 3xx fails without following its Location. Requests are limited to 1 MiB, responses (including streams) to 64 KiB, and the entire request/response to 10 seconds. Public HTTPS destination syntax and literal IP validation remain enforced; this edition does not claim DNS pinning. Base HTTP 500 remains uncertain without automatic replay; 429 retains four bounded attempts with the same logical identity and exact body.

Installed owners land on the Setup page, where the system has already done what it can and lists only what needs them; new workspaces lead with the widget snippet, with secrets and verification controls under Advanced. Empty inboxes offer widget installation, a link to Setup and a demo. Workspace headers follow the selected workspace; visitors intentionally see the operator's display name. Local development suppresses email without storing messages.

Contributor setup

For work on the source, select Node 22.20.0 and pnpm 10.12.4:

pnpm install --frozen-lockfile
pnpm exec rer describe --json
pnpm exec rer check --profile first-party

Verify

rer verify

The complete target checks the contract, real build, typecheck, native runtime, command journey, current workflows and selected Base copies. For a change, run its touched tests plus pnpm run typecheck; CI is the full wall. Browser suites and full verification run on the designated remote runner. Provider fixtures prove local protocol behavior; hosted acceptance and paid-provider execution require separate evidence. Preserve the current holds.

Where to go next

Development lives in just-every/run-happytohelp; the private repository is retained for research and evidence only.

• Install: private answers and the rer journey.
• First-run setup: one-screen first run and the Setup page.
• Operations: configuration, data movement, deployment and recovery.
• Updates and recovery: owner customizations and backups.
• Product contract and acceptance: requirements and proof.
• Authoring: source selection and exact Base copies.

License

MIT. Third-party asset notices remain under docs/licenses.