# HQBase runs a shared email workspace inside your own Cloudflare account, on an AGPL licence

> An open-source shared mailbox workspace deployed into a customer's Cloudflare account, with mail and credentials staying in infrastructure the customer controls. It ships a signed release pipeline, a D1 migration split around deployment, and a first-run setup flow that lives behind its own preview route.

**HQBase/hqbase** — AI native email workspace for teams. In your Cloudflare account.

- Repository: https://github.com/HQBase/hqbase
- Website: https://hqbase.io
- Stars: 334 · Forks: 37
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/hqbase-hqbase

## The account you deploy into is the one that holds the mail

HQBase is positioned as a shared email workspace that runs inside infrastructure the customer controls. The description line in the repository metadata says it plainly: an AI native email workspace for teams, in your Cloudflare account. That single design decision explains most of what follows, including the release process and the file layout.

Because the application, the mail and the Cloudflare credentials all sit in the same customer-side infrastructure, there is no separate vendor account holding a team's correspondence. What you get in place is a set of capabilities: shared mailboxes with team access controls, multi-domain setup with drafts and audit history, installation, update, backup and recovery operations, and an OAuth-protected remote MCP server.

The project is licensed under the GNU Affero General Public License v3.0 only. The package manifest records the same thing as AGPL-3.0-only, and the README states it in the license section. The project is private in the npm sense, meaning it is not published to a registry, and it pins pnpm 11.7.0 as its package manager with the workspace layout held in pnpm-workspace.yaml. Nothing here is a hosted service you sign up for; it is an application you deploy.

## Local development splits the schema across two migration directories

Getting a workspace onto a laptop takes four commands, and the third one needs credentials you have to create yourself first.

```sh
pnpm install
pnpm db:migrate:local
pnpm db:seed:local
pnpm dev
```

Before the seed command runs, two values go into .dev.vars: BETTER_AUTH_SECRET and HQBASE_LOCAL_SEED_PASSWORD with 8 to 128 characters. The commented .env.example that ships in the repository explains the arrangement, and it is explicit that HQBase generates BETTER_AUTH_SECRET during installation while local-only values belong in .dev.vars and secret values are never committed.

The seed is local in a specific sense. It writes only to local D1 and does not contact Cloudflare OAuth, so a seeded workspace cannot accidentally touch production. Sign in at http://127.0.0.1:5173/ as owner@hqbase.test with the seed password. Vite serves the frontend with live reload on port 5173 and proxies API requests to the Wrangler Worker on port 8787, so the dev script is a two-process setup rather than a single server.

If you would rather walk through first-run onboarding than start from a seeded workspace, omit the seed command and open http://localhost:5173/setup instead.

## Reset drops local D1 data and nothing else

Local data has its own reset path, and the project is unusually clear that the path is destructive and confined to one machine.

```sh
pnpm db:reset:local
pnpm db:seed:local
```

The reset command discards all local D1 data, rebuilds the schema and recreates the demo workspace. Its implementation makes the scope explicit: it runs a SQL file through wrangler d1 execute against the local instance and then replays migrations locally, so it never changes a deployed database. That distinction is the reason to trust the command during development and to distrust running it anywhere near a real account without reading it first.

The repository layout reflects how seriously the deployment path is treated. There is a migrations/ directory for the ordinary path and a separate migrations-after-deploy/ directory, which is the shape you need when a schema change has to run after new code is already serving traffic. Alongside that sit worker/, app/, api/, shared/, config/, scripts/ and release/ directories, a server.json, a wrangler.jsonc configuration, and a worker-configuration.d.ts that ties the Worker types back to that configuration.

Running pnpm cf:typegen after editing wrangler.jsonc is the step that keeps those generated types honest.

## Setup and design previews never call the product APIs

Two development commands exist purely for looking at the interface without touching data, and both mount at reserved routes under the same dev server. Each one opens its route automatically on start, so there is no second URL to remember.

```sh
pnpm dev:setup-ui
```

That opens http://127.0.0.1:5173/__ui/setup and is described as being for presentation-only onboarding work. Its counterpart for reviewing the visual system is one command away.

```sh
pnpm dev:ui
```

It opens http://127.0.0.1:5173/__ui/design, where you can inspect shared components, interactive states, product patterns and local screen routes. The important detail is that this gallery uses deterministic presentation fixtures and does not call product APIs, which means what you see is not a live workspace and should not be read as one.

The reservation of these paths is enforced rather than merely documented. The build pipeline ends with a script named check-setup-preview-boundary, and the dev:setup-ui variant previews the setup interface in a loading state via a state=loading query parameter, which is how you exercise the interface before the backend answers. Both routes sit under a __ui prefix, separate from the setup flow at /setup that a real first run uses.

## A release stays in draft until the previous version upgrades to it

The release process is the most distinctive part of this project and the part with the most moving pieces described. Locally, the gate is two commands.

```sh
pnpm check
pnpm deploy:dry-run
```

On the server side, pushes to main run that same quality gate and deployment dry-run. Past that, deployed staging is manual and also runs inside the signed release workflow.

The rule that decides when a release ships is specific: a release stays in draft until the previous stable version upgrades to the exact signed candidate and passes its checks. That is a different and stricter condition than the previous version merely reporting success. The installed version has to take the candidate artifact itself and pass, which is what makes the chain verifiable rather than assumed.

Customer installations and updates verify the signed manifest and artifact digest before deployment. So the trust chain has two independent checks on either side of the handoff: the release side requires an upgrade to the exact candidate, and the customer side refuses an artifact whose digest does not match the signed manifest.

The release train itself is active. Version 1.4.2 shipped on 2026-09-12, 1.4.1 and 1.4.0 both on 2026-09-06, and the manifest carries a minimumVersion of 1.0.0 for the release tooling.

## The mail API ships as generated OpenAPI and Postman artifacts

The api/ directory is not hand-maintained documentation. It holds generated artifacts, and there is a script that produces them for two API versions at once.

The api:generate task writes an OpenAPI document, a Postman collection and a Postman environment for v1, then does the same for v2, six files in total, and formats all six. A companion api:check exists to verify them, which is what keeps generated artifacts honest in a pull request the same way the architecture check does for module boundaries.

Two versions of the mail API existing side by side tells you something about the compatibility posture. It is not a single breaking surface that gets replaced in place.

The rest of the quality tooling is more conventional and unusually complete for a project at this version. Formatting and linting are handled by Biome, with separate format, format:check, lint and code:check scripts, and typecheck runs tsc with no emit. Tests split in two: a unit run against vitest.config.ts and an integration run against vitest.worker.config.ts, which is the pattern you want when the interesting behaviour lives at the Worker boundary. There is a coverage variant, and test:architecture runs a separate script that checks the module graph.

End-to-end coverage is set up as well, through a Playwright configuration at the repository root, alongside Vitest for the worker and browser runs.

## The remote MCP server is gated by OAuth

One of the four capabilities HQBase lists is an OAuth-protected remote MCP server. It is the feature that connects the workspace to outside tooling, and the OAuth protection is what keeps that connection from becoming an unauthenticated read of team mail.

Everything else in the project is deliberately unglamorous, which is what makes it interesting for an operator. Maintenance operations are a first-class listed capability rather than an afterthought: installation, update, backup and recovery are named in the same breath as shared mailboxes. Given that mail and credentials live in a customer account, that framing makes sense, since the person holding the Cloudflare account is the one who has to be able to get the data back out.

Documentation has a clear boundary. hqbase.io/docs is the public source for user and operator guides, product specifications and maintainer procedures, and the repository README points there rather than duplicating operating instructions. The repository keeps the parts that belong in version control: CONTRIBUTING.md, read before opening a pull request, SECURITY.md with a private process for reporting a vulnerability, CODE_OF_CONDUCT.md, TRADEMARKS.md, CHANGELOG.md and AGENTS.md. AGENTS.md sitting next to the code means automated contributors are expected, and the conventions for them are documented in the repository rather than held in a maintainer's head.

The last push landed on 2026-09-12, the same day as the 1.4.2 release, and the repository is not archived.

## Conclusion

Adopt HQBase when a team needs shared mailboxes with access controls, multi-domain setup, drafts and audit history, and the requirement is that the mail and the Cloudflare credentials stay in an account your organisation controls. Do not adopt it expecting a hosted trial or a permissive licence: the workspace is AGPL-3.0-only in both the package manifest and the LICENSE file. Verify three things before you commit: that your Cloudflare account can host D1 and Workers for a data-residency policy, that a release stays in draft until the previous stable version upgrades to the exact signed candidate, and that your operators read the signed manifest and artifact digest path before the first update.

## FAQ

### Where does HQBase store a team's email and credentials?

In the customer's own Cloudflare account. HQBase is deployed into infrastructure you control, keeping the application, mail and Cloudflare credentials there rather than in a vendor account, which is the whole premise of the project.

### How do I run HQBase on a local machine for development?

Run pnpm install, then pnpm db:migrate:local, then pnpm db:seed:local, then pnpm dev. The seed needs BETTER_AUTH_SECRET and a HQBASE_LOCAL_SEED_PASSWORD of 8 to 128 characters in .dev.vars, writes only to local D1, and signs you in at http://127.0.0.1:5173/ as owner@hqbase.test.

### What licence is HQBase released under?

The GNU Affero General Public License v3.0 only. The LICENSE file states it, the README repeats it, and the package manifest records it as AGPL-3.0-only.

### What has to happen before an HQBase release leaves draft?

The previous stable version has to upgrade to the exact signed candidate and pass its checks. Customer installations and updates verify the signed manifest and the artifact digest before deploying, and pushes to main run the same quality gate and deployment dry-run as pnpm check and pnpm deploy:dry-run locally.

## Sources

- [HQBase/hqbase on GitHub](https://github.com/HQBase/hqbase)
- [License: AGPL-3.0](https://github.com/HQBase/hqbase/blob/main/LICENSE)
- [Project website](https://hqbase.io)
- [README](https://github.com/HQBase/hqbase/blob/main/README.md)
- [Releases](https://github.com/HQBase/hqbase/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hqbase-hqbase