# MindsHub: make flush deletes your keys, and the health check hardcodes the port

> An MIT licensed superproject that assembles a desktop and web app, an agent backend, and a data engine from four pinned git submodules, driven almost entirely through a Makefile. It is a rename in progress in places, the clone URL and the issue tracker still point at a different repository name, the recovery target destroys your conversations and provider keys, and the compose health check probes a fixed port the environment variable lets you change.

**mindsdb/mindshub** — Make AI do actual work. Swap the model anytime, keep everything you've built.

- Repository: https://github.com/mindsdb/mindshub
- Website: https://mindshub.ai
- Stars: 39,776 · Forks: 6,246
- Language: Makefile
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/mindsdb-mindshub

## The clone URL, the help banner, and the state directories all use older names

The repository is `mindsdb/mindshub` and the product is MindsHub. The instructions do not consistently agree.

```bash
git clone --recurse-submodules https://github.com/mindsdb/minds.git
cd minds
```

The clone URL is a different repository name, and so is the directory you land in. The release badge and the bug report link at the bottom of the page both point at `mindsdb/minds`, and the `make` help target prints a header naming the Minds Platform. Look at the state the tool keeps on your disk. Provider keys live in `~/.anton`, and the database, Hermes, and projects live in `~/.cowork`. The compose file names its environment variables `COWORK_SERVER_HOST` and `COWORK_SERVER_PORT`, and the desktop download path itself contains the string mindshub-cowork. So a single install involves four naming systems at once. Nothing is broken by it, but a first-time contributor will file an issue in one repository, look for state in a directory named after a third thing, and set an environment variable named after a fourth.

## The api health check hardcodes the port that an environment variable sets

Look closely at how the compose file decides the api is up. The service publishes the port from a variable, `COWORK_SERVER_PORT: "26866"`, and the health check is a Python one-liner that fetches a fixed address.

```yaml
    healthcheck:
      test: ["CMD", "python", "-c",
             "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:26866/health',timeout=3).status==200 else 1)"]
```

The URL inside that string is a literal, not a substitution of the variable above it. The web service then declares `depends_on` the api with `condition: service_healthy`. Those two facts combine into a real failure mode. Set `COWORK_SERVER_PORT` to anything other than 26866 and the server moves while the probe does not, so the health check never passes, the api is never reported healthy, and the condition gating the web container is never satisfied. The web app simply does not start, and the compose output gives you a dependency that is waiting rather than an error. If you need a different port, change the address in the health check at the same time.

## The recovery command is the one that deletes your conversations and keys

The fresh start target is documented with a warning attached, and the warning is accurate. `make flush` removes the local runtime, which is the `cowork-server` uv tool and the virtual environments under `backend/*`, and it deletes app state in two places: `~/.anton` for provider keys, and `~/.cowork` for the database, Hermes, and projects. It is described as the way to test a from-scratch install or recover from a broken install, and it prompts for confirmation, which you skip with `FORCE=1`. The final line of that note is the one to sit with. It deletes your conversations and saved keys. So the documented path out of a corrupted install is also the path that destroys the state a fresh install cannot recover, since the keys are gone and the database is gone with them. Copy both directories out before you run it, and if you put `FORCE=1` in a script or a provisioning run, you have removed the only guard between a stuck build and a wiped install.

## Four submodules are pinned by commit, and the pins move through one command

The repository is a superproject, and it pins four modules to specific commits: `frontend`, `backend/core_api`, `backend/core_agent`, and `backend/data-vault`. That arrangement has two consequences worth internalising. First, `.gitmodules` is configured with `ignore = all`, so your branch work inside a submodule never shows up as a change in the parent repository, and a clean `git status` in the superproject is not evidence that your submodules are on what you think they are. Second, the page is explicit that pins move only via `make pin`, which records the current submodule commits as the superproject's pins in one deliberate commit. The surrounding targets make the workflow navigable. `make use` checks out the refs named in your `dev.env` across all submodules, `make refs` shows which ones the next run will use, and `make baseline` resets the submodules back to the pinned commits. That pin commit is the one to read carefully in review, because everything downstream of it moves at once.

```bash
cp dev.env.example dev.env      # then set REF=feat/my-thing (or per-module API_REF=…)
```

## The agent is a swappable component installed from its own repository

Two open-source harnesses are offered, Anton as the default and Hermes, swappable from a dropdown in the product. The build system treats that swap as a real dependency rather than a UI setting. The Makefile exports two variables into the environment, `COWORK_SERVER_REF` from the API ref and `ANTON_REF` from the agent ref, and the desktop server is described as a uv tool install keyed by those variables. The override line is the sharpest part. When the agent ref is anything other than main, the Makefile injects a requirement pointing at a separate repository, `anton-agent @ git+https://github.com/mindsdb/anton.git@$(AGENT_REF)`, and a comment explains that the injection is conditional because uv rejects a redundant `--with`. So working on a different agent means reinstalling the tool from a git reference rather than rebuilding the stack, and the agent's own code lives outside both this superproject and the release you installed. The compose file carries a commented Anthropic key variable, which is the other half of the same arrangement.

## The compose topology is two containers and a SQLite file in a volume

The deployment story is broad, covering cloud, VPC, on-prem, air-gapped, and hybrid infrastructure. The compose file that ships here is much narrower than that sentence. It defines two services, an `api` built from `docker/api.Dockerfile` and a `web` built from `docker/web.Dockerfile`, plus one named volume called `cowork-data`. There is no database service. The api's `DATABASE_URI` is a SQLite file inside that volume, at `sqlite:////home/cowork/.cowork/cowork.db`, and the api is published on 26866 while the web is published on 3000 mapping to port 80. Read honestly, this is a local development topology. The data engine the superproject pulls together is a file on a volume in this configuration, which means the VPC and air-gapped deployments the page advertises are not what this file produces and require work that is not described here. The web container's port mapping also means the SPA is served behind a proxy path rather than on the api's port, so anything you write against one origin needs to account for the other.

## Free to start means the open models, and the rest sits behind a tier

The commercial shape is stated in one line. Free to start, and Pro adds all frontier models and private artifacts. The Model Router is described as letting you switch between frontier models, naming Claude, GPT, and Gemini, and open models, naming DeepSeek, Qwen, and Kimi, without wiring up a key for each provider. That last clause is doing a lot of work. The no-key convenience is a property of the hosted product, where one account and one bill cover the choices, and the separate inference page is sold on exactly that, one set of controls and one bill. What the page does not say is how key provisioning works in a self-hosted install, where the whole point of running the superproject yourself is that the credentials are yours. The connected data section makes a related promise, that credentials stay scoped per connection and agents never see raw keys, but it does not connect that to a self-hosted key story either. Before you commit to self-hosting, establish which side of that line you are on, because the answer decides whether the frontier models are reachable at all.

## The Makefile documents itself by grepping its own comments

The project reports its primary language as a Makefile, and the build file is doing more than building. It is self-documenting by convention. The `help` target is the default goal, so a bare `make` does not build anything, it lists targets. The listing is produced by grepping the makefile itself for lines carrying a `## ` marker, sorting them, and formatting the result with awk, which means a target becomes visible in the help output only if someone wrote a comment in the expected place. That is a fine convention and an easy one to forget, so an undocumented target is invisible to the person most likely to need it. The module variables show the same hand-maintenance. Four paths are named, `FRONTEND`, `API`, `AGENT`, and `VAULT`, but only three stamp variables exist, one each for the frontend's lockfile marker, the API's virtual environment, and the agent's virtual environment. The data vault has a name and no stamp, so whatever those markers gate, the vault is not gated by one.

## Conclusion

Adopt it when you want an agent workspace you can run yourself, with the harness and the model both swappable, and you are prepared to drive a Makefile over four submodules rather than install a package. Do not reach for it if you need a settled repository layout, because the naming is mid-rename and the on-disk state directories do not match the product name. Before you run make flush on anything you care about, back up ~/.anton and ~/.cowork, because the documented recovery path deletes provider keys and conversations. And if you change COWORK_SERVER_PORT, fix the health check first, or the web container will wait forever for an api that never reports healthy.

## FAQ

### What does MindsDB do, and what is this repository?

This repository is MindsHub, described as an agent workspace for completing knowledge work and developing software, with open-source agent harnesses and a choice of models. It is the platform superproject, pulling together the desktop and web app, the agent backend, and the data engine so you can build and run the whole stack from source.

### Is MindsDB free to use?

The code is MIT licensed and the README says free to start. The paid part is named as well: Pro adds all frontier models and private artifacts, and a separate inference product is sold on one set of controls and one bill across providers.

### How do I create an AI agent in MindsDB?

The readme does not give a step-by-step for creating an agent. What it describes is two interchangeable open-source harnesses, Anton as the default and Hermes, swappable from a dropdown, and a from-source path of cloning the superproject with submodules, running `make setup`, and then `make dev`.

### What are some open-source alternatives to MindsDB?

The readme names no alternatives and makes no comparison. The one related thing it points to is MindsHub Inference, a separate hosted offering for reaching models and providers through one API, one set of controls, and one bill.

### what is mindshub

MindsHub is an open-source agent workspace for research, analysis, content creation, and software development, offering a choice of models and providers rather than one ecosystem. It can run on your machine, in your VPC, or through the hosted app at console.mindshub.ai.

## Sources

- [Official documentation](https://mindshub.ai)
- [Official README](https://github.com/mindsdb/mindshub#readme)
- [Project repository](https://github.com/mindsdb/mindshub)
- [Release notes](https://github.com/mindsdb/mindshub/releases)

---

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