# taOS: a self-hosted AI agent OS that treats the framework as replaceable

> taOS runs agents, memory and files on hardware you own, with an offline-first default and AGPL-3.0 licensing. It is beta software, and the README is candid that parts of its app and model catalogs are untested.

**jaylfc/taOS** — Self-hosted AI agent OS. Your memory, chat, agents, and files stay on hardware you own, offline by default, cloud by choice. Offline AI memory (taOSmd), self-hosted multi-framework group chat, a full web desktop + app store, and auto-clustering across the consumer hardware you already have (Orange/Raspberry Pi, Mac mini, gaming PC).

- Repository: https://github.com/jaylfc/taOS
- Website: https://taOS.my
- Stars: 554 · Forks: 41
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/jaylfc-taos

## The problem taOS targets: agent state scattered across vendors

Most agent stacks tie the agent's memory, chat history and channel connections to one execution framework. Change the framework and the state has to be migrated or abandoned. taOS inverts that. The README describes the framework as "just a replaceable execution engine" and claims that switching from SmolAgents to LangChain to OpenClaw preserves history, Telegram, Discord and Slack connections, trained LoRA adapters, files and API keys. The project's stated mechanism for this is that taOS manages the full agent lifecycle outside the framework.

The intended user is someone with spare consumer hardware: an Orange Pi, Raspberry Pi, Mac mini, gaming PC, or an SBC sitting unused. The pitch is that several such machines become one distributed inference cluster. The README also names Apple Silicon via MLX, NVIDIA, AMD, Rockchip NPU, Raspberry Pi and Android phones as supported targets, and the repository topics include kv-cache-quantization, rockchip-npu and vllm.

A secondary audience is anyone who objects to long-term memory living in a vendor's cloud database. The README frames this as data sovereignty: offline memory on a self-hosted knowledge graph, with cloud models described as opt-in rather than required.

## How taOS is put together: taOSmd, the Librarian layer and the catalogs

The memory system, taOSmd, is the most concrete part of the design. It is published separately to PyPI and pinned in pyproject.toml as taosmd==0.4.0, so the memory layer is a versioned dependency rather than code buried in the app. The README describes its stack as a temporal knowledge graph with validity windows and contradiction detection, hybrid semantic plus keyword vector search with cross-encoder rerank, an LLM-assisted query expansion step it calls the Librarian, a zero-loss append-only archive, automatic fact extraction, intent-aware retrieval routing and multi-layer context assembly. Any framework can read and write through an HTTP API.

On accuracy, the README reports 97.0% end-to-end Judge accuracy on LongMemEval-S: retrieve, generate, then judge with an LLM grader, across 500 questions and 50 or more sessions each. It also states plainly that the most-cited open comparators, MemPalace at 96.6% and agentmemory at 95.2%, publish Recall@5 retrieval scores on the same dataset, which measure only whether the correct session lands in the top five. The README's own words are that the metrics "aren't apples-to-apples until one of us re-runs end-to-end." That is the right caveat to make, and it is worth repeating: the headline number is not directly comparable to the retrieval numbers it is placed beside.

The rest of the platform is catalog-driven. The README lists 43 bundled apps, 109 catalog apps, 47 MCP plugins, 17 agent frameworks, and a curated local model catalog of 120 manifests covering LLMs, vision, embeddings, audio and image generation, including RK3588 NPU variants and Hailo-10H HEF variants. Alongside that sits a search index of 167k+ HuggingFace models. The README is direct that this breadth is partly aspirational: "plenty of install manifests have not been exercised on real hardware yet, so some apps, frameworks, and models will fail to install."

## Installing the taOS controller and running a first agent

The README gives a single install command for the controller, covering Debian, Ubuntu, Fedora, Arch, Alpine and macOS. Running it with sudo installs a system service; running it without sudo installs a user-mode systemd unit instead. The script is described as idempotent and safe to re-run, and it accepts environment-variable overrides for install path, branch and port.

```bash
curl -fsSL https://raw.githubusercontent.com/jaylfc/taOS/master/scripts/install-server.sh | sudo bash
```

Before you run that, check the Python version. pyproject.toml pins requires-python = ">=3.11,<3.14" and explains why: litellm, the proxy extra used as the agent and model proxy runtime, supports only >=3.10,<3.14. On a fresh distribution where python3 points at 3.14, the virtual environment build aborts with "No matching distribution found for litellm". The installer steers the venv to a supported interpreter, but the cap makes the constraint explicit to pip and uv.

After install, the README points to a web desktop as the entry point, with a dashboard that includes the app store, agent deployment, training, generation tools and system monitoring. The README does not document a first-agent walkthrough step by step. What it does show is the outcome: a screenshot captioned with six agents on six different frameworks (OpenClaw, Hermes, SmolAgents, Langroid, PocketFlow and the OpenAI Agents SDK) talking in a single shared channel. If you are evaluating taOS, reproducing that shared-channel setup is the test that matters, because it exercises the framework-agnostic claim rather than just the installer.

One packaging detail is worth knowing because it constrains upgrades. fastapi is capped below 0.137 in pyproject.toml, with a comment that 0.137.0 regressed include_router so a mounted APIRouter contributes none of its routes, leaving create_app() with an empty API surface. 0.136.3 is named as the last good release.

## Where taOS is the wrong tool

The README is unusually explicit about its own state: beta software, dated 2026-06-02, meant for testers running it on their own hardware, with "rough edges" expected. It says the install script, backend, API, memory system and multi-framework group chat all work, while the desktop GUI is wired up for everyday use but some flows are still being smoothed out: agent management, worker connections and model routing are named.

That list matters more than a generic beta warning. Those three flows are exactly the ones a production deployment depends on. If you need model routing to be predictable, or worker connections to survive a reboot unattended, the README does not claim that today.

The catalog is the second failure mode. With 100+ apps, 16 frameworks and a large model catalog, the README states that many install manifests have not been exercised on real hardware. A failed install is therefore an expected outcome, not an anomaly. The maintainer asks for an issue with the name and the error, and says most manifest fixes ship same-day. That is a reasonable process, but it means your first hours with taOS may be spent filing bugs rather than building.

Third, taOS is the wrong choice if you want a managed service. There is no hosted option described. The whole value proposition is that you supply the hardware, the power and the maintenance. If nobody on your team wants to own an Orange Pi that runs a knowledge graph, the sovereignty argument does not survive contact with operations.

Finally, the memory benchmarks, while carefully caveated, are self-reported by the project on its own configuration. Independent reproduction is not something the README claims.

## How taOS differs from running a bare inference server

The obvious alternative is to run a local inference server such as vLLM or Ollama and point your own agent code at it. That approach is smaller and better understood. You get a model endpoint and nothing else. Memory, channel connections, agent lifecycle and file storage remain your problem, and they stay coupled to whichever framework you picked.

The difference in approach is where the state lives. A bare inference server is stateless with respect to your agent: swap the model and nothing else changes. taOS puts the state in the platform and treats the model and the framework as swappable components. That is why taosmd is a separate pinned package with its own HTTP API rather than a module inside the agent loop.

The cost of that inversion is surface area. A bare server has one configuration file and one port. taOS carries an app catalog, a plugin catalog, a model manifest catalog, a web desktop, a cluster layer and a memory service. The README's own warning about untested manifests is the price of that breadth. If your requirement is a single model endpoint for a script you control, taOS adds components you will not use. If your requirement is that six agents on six frameworks share one memory and one channel, the bare server gives you nothing toward it.

## Maintenance, release cadence and AGPL-3.0 implications

The last push to the repository was on 2026-09-10, and the repository is not archived. Releases are frequent and still pre-1.0: v1.0.0-beta.52 on 2026-09-08, v1.0.0-beta.51 on 2026-09-07, and v1.0.0-beta.50 on 2026-08-21. The version string in pyproject.toml matches the beta.52 tag, so the package version and the release tag track each other.

That cadence has an operational consequence. Between beta.51 and beta.52 there is one day. If you pin taOS, you will be pinning a fast-moving target, and the pyproject.toml dependency caps (fastapi below 0.137, Python below 3.14, litellm's own range) show that upstream regressions have already forced pins. Upgrading means re-checking those caps, not just pulling a new tag.

The licence is AGPL-3.0, with the repository carrying both LICENSE and COMMERCIAL-LICENSE.md. AGPL-3.0 is a strong copyleft licence whose network clause is the part that catches people: if you modify taOS and let users interact with it over a network, the licence's terms attach to that deployment. The presence of a separate commercial licence file indicates the maintainer offers an alternative for cases where AGPL does not fit. Whether you need it depends on how you distribute or host your modified version. That is a question for your own counsel; the README does not spell out the commercial terms.

The README also mentions a self-hostable binary mirror and an air-gapped install path as part of the exit-ability claim. Neither is documented in the excerpt available, so treat them as things to confirm against the repository before you depend on them.

## Conclusion

Adopt taOS if you already own an Orange Pi, Raspberry Pi, Mac mini or spare x86 box and you want agent memory and chat to stay on that hardware under AGPL-3.0. Do not adopt it if you need a stable platform today, since the README labels it beta for testers and warns that some catalog manifests will fail to install. Before committing, verify that your hardware appears in the verified-installs table, confirm the Python interpreter is between 3.11 and 3.13, and read COMMERCIAL-LICENSE.md if AGPL-3.0 does not fit how you intend to distribute the software.

## FAQ

### What hardware does taOS run on?

The README lists Orange Pi, Raspberry Pi, Mac mini, gaming PC, old laptops, Apple Silicon via MLX, NVIDIA, AMD, Rockchip NPU and Android phones, and says several machines can be combined into a cluster. It also includes a verified-installs table, with an Orange Pi 5 Plus 16GB on Armbian listed as running the maintainer's stack daily. The README asks users who install elsewhere to open an issue with the install log so the table can be extended.

### Is taOS free and what licence does it use?

The repository is licensed AGPL-3.0 and contains a separate COMMERCIAL-LICENSE.md file. The README describes the project as open source with a self-hostable binary mirror and an air-gapped install path. It does not state pricing for the commercial licence.

### Why does the taOS installer fail with a litellm error on a new system?

pyproject.toml pins requires-python to >=3.11,<3.14 because litellm supports only >=3.10,<3.14. On a distribution where python3 defaults to 3.14, the venv build aborts with "No matching distribution found for litellm". The installer steers the venv to a supported interpreter, and the cap exists to make the constraint explicit to pip and uv.

## Sources

- [jaylfc/taOS on GitHub](https://github.com/jaylfc/taOS)
- [License: AGPL-3.0](https://github.com/jaylfc/taOS/blob/master/LICENSE)
- [Project website](https://taOS.my)
- [README](https://github.com/jaylfc/taOS/blob/master/README.md)
- [Releases](https://github.com/jaylfc/taOS/releases)

---

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