# Founder OS: a seeded demo that will not let a connector fake a connection

> Founder OS is an open-source demo build of a business console that runs a one-person company as a set of AI-assisted departments. The design rule it is built around is that every page reads through a repository layer and every integration reports a real status, which makes the demo honest but means the interesting parts, the knowledge layer and the memory runtime, are the pieces that are stubs in this repository.

**Bennettxai/FounderOS-DEMO** — An open-source, single-operator business command center: run a one-person operated company as AI-assisted departments (comms, funnel, social, finances, agents, and a knowledge graph) from one live dashboard.

- Repository: https://github.com/Bennettxai/FounderOS-DEMO
- Website: https://www.thefounderos.com
- Stars: 960 · Forks: 276
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/bennettxai-founderos-demo

## The repository is the demo half of a product sold elsewhere

The framing sentence is that this is a personal operating system for a one-person business, a live web command center that runs a company as a set of AI-assisted departments. Then the repository describes itself precisely: it is the open-source demo build, seeded with realistic placeholder data, so every page is alive out of the box with no accounts, no API keys and nothing to configure. The same system is taught live in a cohort, and the repository exists so you can explore and run it yourself. The cohort links in the readme, though, point at a domain that reads as a placeholder rather than a real site, while the project homepage is a different domain entirely. That is a small thing, but it is the kind of thing that tells you the readme and the commercial site were last edited at different times.

## Every screen reads through a repository layer, and the rule is called load-bearing

The architecture section names its own central constraint and calls it the load-bearing design rule. The demo looks alive because of rich seeded data, but every page and API route reads through a repository layer rather than issuing a raw query, and every connector returns an honest status rather than pretending. Swapping seeded tables for live sources is then described as a repository-level change rather than a rewrite. That is a real architectural commitment, and the file layout backs it up: one module holds the database singleton and seeds on first touch, another holds the connection function plus typed repositories for agents, departments, social, funnel, finances and more, and a third holds all the seeded demo content in one place. Keeping every fake row in a single file is what makes the claim maintainable rather than aspirational.

## Zod validates rows on the way out, which is the opposite of the usual choice

The schema module validates every row on the way out of the database, and the stated reason is that bad data should fail loudly. Most systems validate on the way in, at the boundary where untrusted data arrives. Validating on the way out instead means the seed data and the live data are held to the same standard at the moment they are handed to the interface, which is what makes a demo's placeholder data a useful proxy for real data. The cost is that the database itself is not constrained, so an invalid row can exist and only fails when something reads it. The companion rule for adding anything new is a four-item checklist: a repository method, a schema, a seed entry, and a test, followed by an instruction to keep it that way. That is a small, enforceable convention and it is the kind of thing that survives a change of maintainer.

## Connectors report three states and are forbidden from reporting a fourth

The connector layer is described as twenty or more connector groups covering email over IMAP, Slack, Stripe, Notion, calendar, CRM and social, among others. Each returns a typed status with exactly three values: connected, not configured, or error. The comment attached to that union is that it is always the truth and never a fake green light. This is the single most important design decision in a demo product, because the usual failure mode of a seeded dashboard is a grid of connected badges that mean nothing. The agent layer takes the same position: every seeded agent maps one to one onto a runtime agent with a real run function, and runs persist and surface on the roster page rather than being simulated on each render. The trade is that a first-time visitor sees a board where most rows are honestly unconfigured, which looks broken until you understand that it is the feature.

## The knowledge graph needs a command-line tool this repository does not ship

The retrieval design has two halves that are worth separating because they answer for different failures. When the vector store is reachable, the same chunked corpus answers both keyword and semantic queries, fused by reciprocal rank, which is a specific choice that avoids picking one retrieval mode. When it is not reachable, retrieval falls back to a plain text search over the markdown files, and the documented consequence is fewer smarts with zero downtime. That is the right trade for an agent runtime, where a hard failure to answer is worse than a worse answer. The deeper decision is that the source of truth is a directory of markdown files rather than a database or a proprietary index, which means the knowledge base is inspectable, diffable and portable with ordinary tools, and the embedding store is a derived artefact you could rebuild from nothing.

## Nothing becomes known without passing review, and agents cannot self-promote

The second half of the knowledge system is a governed memory runtime, and it is described with an explicit division of labour: the library stores documents, the librarian and system of record governs what the operating system actually knows. The memory is organised as a four-level topology of tenant, organisation, workspace and node, and inside that there is a five-stage lifecycle.

```text
Source -> Signal -> Claim -> Fact -> Memory
```

Raw sources produce signals, signals become claims, claims are reviewed and promoted into verified facts, and facts distill into durable memories the agents draw on. The constraint is the sentence that matters: agents may write sources, signals and pending claims, but facts are promotion-gated, so nothing becomes known without passing review. That single rule is what makes an agent-generated operating system auditable. An agent can propose, an agent cannot conclude. The cost is that the pipeline has a human or policy step in it, and anything hoping to run fully autonomously will find a queue forming at the claim-to-fact boundary.

## The environment template annotates which payments actually work

One file in the repository is more revealing than the feature list, because it carries honest per-integration annotations. Up to four mail inboxes are supported over IMAP, with a note that a hosted mail provider requires an app password obtained through two-factor settings, and the port shown commented with its default. The Slack entry names the exact token scopes required. Then the payment section is annotated by implementation status: the card processor is marked as having a full client covering balance and charges, the other processor is marked as registered with the client landing when keys arrive, and two further processors carry keys with no status annotation at all. The analytics section goes further, with one vendor marked as pulling registrants and attendees, another marked as status-only until that vendor ships an API, and a third carrying both a private integration token and a separate location identifier. That is unusual candour in a configuration file, and it is the fastest way to see what actually works.

## A one point zero manifest with no release, and two agent directories

The manifest is conventional in shape and a year behind in versions. It is a private package at one point zero, requiring Node twenty-two in the twenty-two line, built on a version fourteen release of the web framework with React eighteen, a version three release of the utility stylesheet framework, and the version two test runner. The scripts are short and honest: development and start both pin a non-default port, the seed script is idempotent, and there is a separate script whose only job is to generate the knowledge documents. There are no tagged releases, so nothing corresponds to the version in the manifest. The directory listing also holds two different agent locations, one at the top level and one inside the library, which is the kind of thing that makes a newcomer grep twice. A committed assistant instruction file at the root is consistent with the project's habit of writing its conventions down.

## Conclusion

Founder OS suits an evaluator who wants to see whether a multi-department command center is a coherent idea before paying to be taught one, and it is unusually transparent about being a demo. Four things to check. Read the connector board first, because the honest-status rule means half the screen will show not configured, and that is the correct state rather than a bug. Expect to supply a separate knowledge command-line tool on your path for the graph route to do real work, or run it in stub mode. Read the memory lifecycle before trusting anything an agent states as fact, since promotion is gated on review and agents can only write the earlier stages. And note the version: the manifest says one point zero while there is no tagged release, so pin a commit.

## FAQ

### How do I run the Founder OS demo?

Install Node 22, then `npm install`, optionally copy `.env.example` to `.env.local` if you want to wire live integrations, and run `npm run dev` for http://localhost:4100. A local SQLite database seeds itself with demo data on first run, so every page is populated and no credentials are needed to browse. `npm run seed` re-seeds idempotently.

### Does Founder OS pretend integrations are connected?

No, and that is the stated load-bearing rule. Twenty or more connector groups each return a typed status of connected, not_configured or error, and the code comment says it is always the truth and never a fake green light. The integrations board is therefore partly not configured on a fresh install, which is the correct state rather than a fault.

### What is G-Brain in Founder OS?

The knowledge base, where plain markdown files are the source of truth and get chunked and embedded into a vector store so one store answers both keyword and semantic queries through reciprocal-rank fusion. If the vector backend is unreachable, retrieval falls back to a local grep over the markdown. This repository ships a stub provider, and the configuration expects a knowledge command-line tool on your path unless you set the provider to stub.

### How does Founder OS decide what counts as known?

Through a five-stage lifecycle of Source, Signal, Claim, Fact and Memory. Agents may write sources, signals and pending claims, but facts are promotion-gated, so nothing becomes known without passing review. Optimal Engine is the system of record for this, while G-Brain stores the documents, and agents query both before they act.

### What does the Founder OS production plan use?

Railway for hosting. The web application deploys as a Railway service, the seeded SQLite store is replaced by a managed database, and the two knowledge services run as companion services alongside it, with environment variables managed per environment. The repository-layer contract is unchanged from the demo.

## Sources

- [Bennettxai/FounderOS-DEMO on GitHub](https://github.com/Bennettxai/FounderOS-DEMO)
- [Issues](https://github.com/Bennettxai/FounderOS-DEMO/issues)
- [License: MIT](https://github.com/Bennettxai/FounderOS-DEMO/blob/main/LICENSE)
- [Project website](https://www.thefounderos.com)
- [README](https://github.com/Bennettxai/FounderOS-DEMO/blob/main/README.md)

---

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