# Eclaire: A Self-Hosted AI Assistant for Tasks, Notes, Documents and Bookmarks

> Eclaire bundles local models, OCR, bookmark archiving and an OpenAI-compatible API into a single self-hosted container. It is pre-release software with breaking changes, and the README tells you not to put it on the public internet.

**eclaire-labs/eclaire** — Local-first, open-source AI assistant for your data. Unify tasks, notes, docs, photos, and bookmarks. Private, self-hosted, and extensible via APIs.

- Repository: https://github.com/eclaire-labs/eclaire
- Website: https://eclaire.co
- Stars: 922 · Forks: 98
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/eclaire-labs-eclaire

## The problem Eclaire targets: your data is in six places and none of them can see the others

Tasks live in one app, notes in another, PDFs in a downloads folder, bookmarks in a browser, photos on a phone. Asking a question that spans them means opening each one. Hosted assistants can read across services, but only by sending the content to someone else's servers, which is the wrong trade for medical scans, contracts or personal journals.

Eclaire is aimed at that gap. The README frames it as assembling existing building blocks into a complete product rather than shipping another framework: "There are are lot of existing frameworks and libraries enabling various AI capabilities; few deliver a complete product allowing users to get things done." The intended user is someone who already runs a home server or a workstation with a GPU, is comfortable with Docker Compose and environment files, and would rather spend an evening on setup than hand a third party a corpus of personal documents. The repository topics name the same scope: personal-knowledge-management, self-hosted, privacy, on-device-ai.

The scope is deliberately broad. Asset types listed in the README include tasks, notes, documents in PDF, DOCX, PPTX, XLSX, ODT, Markdown, RTF, Pages, Numbers and Keynote, images in JPG, PNG, SVG, WebP, HEIC, AVIF, GIF, BMP and TIFF, plus bookmarks. A narrower tool that only indexes a notes folder solves a smaller problem and asks less of you.

## Architecture: one container, a database queue, and model servers that stay on the host

The repository is a pnpm monorepo, version 0.7.0 in package.json, with apps/ and packages/ directories and a root compose.yaml. The v0.6.0 release notes describe the shift that defines the current shape: frontend, backend and workers can run in a single container, the frontend moved from Next.js to Vite with TanStack Router, and job processing can use Postgres or SQLite instead of Redis.

Runtime wiring is derived from one variable. The compose file sets ECLAIRE_RUNTIME: container, ECLAIRE_HOME: /app and PORT: 3000, and the comment above it says "schema.ts derives all other defaults from this." That means hostnames and ports are computed rather than hand-written, which removes a common source of broken .env files but also means the runtime variable is the thing to check first when something cannot reach the database.

Model servers are deliberately outside the container. The compose file states that LLM backends run on the host because they need GPU access, and the app reaches them through host.docker.internal, which is added via extra_hosts. Backends listed in the README are llama.cpp, vLLM, mlx-lm/mlx-vlm, LM Studio and Ollama, all through an OpenAI-compatible API. The queue backend is chosen separately from the database: QUEUE_BACKEND accepts sqlite or postgres, and the .env.example notes that the sqlite queue requires SERVICE_ROLE=all together with DATABASE_TYPE=sqlite. That constraint is easy to miss and will produce a confusing failure if you mix a sqlite queue with a Postgres database.

## Installing Eclaire with setup.sh and Docker Compose

The README points at a one-command setup.sh flow introduced in v0.6.0, and setup.sh sits at the repository root. The .env.example header says the script generates secrets and prepares the file for use. The three secrets it fills are BETTER_AUTH_SECRET, MASTER_ENCRYPTION_KEY and API_KEY_HMAC_KEY_V1, and the file notes they can also be generated by hand with openssl rand -hex 32.

After setup, the compose file's usage block gives the self-hosted command. Run it from the repository root, where compose.yaml and the generated .env live:

```bash
docker compose up -d
```

The service publishes ${HOST_PORT:-3000} on the host, so the default address is http://localhost:3000 unless you set HOST_PORT. Two bind mounts are declared: ./data to /app/data and ./config to /app/config. Those directories are your instance state, which is why the README's upgrade warning about backing up data applies to them.

For development against a local Postgres, the compose header gives a different invocation that starts only the database and the document-processing service:

```bash
docker compose -f compose.yaml -f compose.dev.yaml up -d postgres docling
```

A first real use follows the sample use cases. Save a bookmark, let Eclaire fetch it and produce readable and PDF versions, then ask the assistant to summarize it. The README also describes asking the AI to find or summarize information across your data and scheduling automations such as a Monday-morning task summary. Chat is reachable from web, mobile and Telegram, and the API is documented at eclaire.co/docs/api with session tokens or API keys.

## Where Eclaire is the wrong tool

The README's own notices are the strongest limitation section in the repository. Eclaire is described as pre-release and under active development, with frequent updates, breaking changes and evolving APIs and configuration. That is not boilerplate hedging: the v0.6.0 notes list a frontend framework migration, a new deployment model and a new database option in a single release. If you need a stable configuration surface that will not move under you, this is not it yet.

The security notice is equally direct. It says not to expose Eclaire directly to the public internet and that the project is not hardened for direct exposure, recommending Tailscale, Cloudflare Tunnels or a reverse proxy with authentication. Treat the container as a service that belongs on a private network.

The queue constraint is a real failure mode rather than a preference. Because the sqlite queue requires SERVICE_ROLE=all and DATABASE_TYPE=sqlite, choosing SQLite for simplicity and then pointing at an external Postgres, or splitting services while keeping the sqlite queue, produces a configuration the .env.example does not support. The last push to the repository was on 2026-05-14, and the most recent release listed is v0.6.3 from 2026-03-06, so the release tags lag the repository state; check the CHANGELOG rather than assuming the newest commit is packaged.

## How Eclaire differs from Ollama plus a note-taking app

The obvious alternative is to run Ollama or LM Studio for inference and keep a separate notes application, wiring them together yourself. Eclaire uses those same backends, so the model quality is not the difference. The difference is everything around inference: document conversion across office formats, OCR for images, bookmark fetching with special handling for GitHub and Reddit metadata, generated readable and PDF versions of pages, tagging, pinning, due dates, and an assistant with tools to search data, open content, resolve tasks and create notes.

That is a real trade. A separate notes app plus Ollama keeps each piece replaceable and each upgrade independent. Eclaire asks you to accept its data model and its release cadence in exchange for cross-asset retrieval and tool calling that work without glue code. If your corpus is one folder of Markdown files, the glue is small and the alternative wins. If it spans scanned documents, phone photos and saved web pages, the glue is the project.

A second comparison is the hosted assistant you already pay for. It will be more polished and need no GPU. It will also require uploading the content. For a recipe collection that is fine; for identity documents and health records the README's privacy framing is the whole argument.

## Licence, upgrade cost and what pre-release actually means here

The repository is MIT licensed, and package.json carries "license": "MIT" for the monorepo. MIT permits commercial use, modification and redistribution with the copyright notice and licence text retained. It provides no warranty, which matters for a project that stores your personal documents. This is a description of the licence text, not legal advice; read LICENSE and SECURITY.md yourself before deploying anything you would not want to lose.

The upgrade cost is the part to weigh honestly. The README asks you to back up data regularly and review release notes carefully before upgrading. Three releases appear between January and March 2026, and the v0.6.0 notes describe changes to deployment topology, the frontend stack and the database layer. Upgrades are therefore not a pull-and-restart operation in the general case. Pin the image tag through ECLAIRE_VERSION rather than tracking latest, read CHANGELOG.md before moving, and keep the ./data and ./config directories under whatever backup you already run.

Development requires Node ^24.0.0 and pnpm 11.0.1 per package.json, with scripts for setup:dev, dev, build and test:unit. The repository also ships AGENTS.md and CLAUDE.md, which suggests AI-assisted contribution is an expected workflow rather than an afterthought.

## Conclusion

Adopt Eclaire if you want one self-hosted place where a local model can read your notes, documents, photos and bookmarks, and you are willing to run it behind a VPN or an authenticating reverse proxy. Do not adopt it if you need a stable API surface or a documented upgrade path: the README labels it pre-release, warns of breaking changes, and asks you to back up data before upgrading. Verify two things before you commit: whether your GPU stack is reachable at host.docker.internal from the container, and whether the version tag you pin in ECLAIRE_VERSION actually exists on ghcr.io.

## FAQ

### How do I install Eclaire?

Run setup.sh from the repository root to generate the secrets and prepare the .env file, then start the stack with docker compose up -d. The service is published on port 3000 by default, or on whatever you set HOST_PORT to.

### Does Eclaire run entirely locally?

The README states that by default all AI models run locally and all data is stored locally, and the compose file notes that LLM backends run on the host rather than in containers because they need GPU access. The container reaches them through host.docker.internal.

### Which model backends does Eclaire support?

The README lists llama.cpp, vLLM, mlx-lm/mlx-vlm, LM Studio and Ollama, all connected through the standard OpenAI-compatible API. Model families named include Qwen, Gemma, DeepSeek, Mistral and Kimi.

### Can Eclaire use SQLite instead of Postgres?

Yes. DATABASE_TYPE accepts sqlite, pglite or postgres, and QUEUE_BACKEND accepts sqlite or postgres. The .env.example notes that the sqlite queue requires SERVICE_ROLE=all together with DATABASE_TYPE=sqlite.

### Can I expose Eclaire to the internet?

The README explicitly warns against it, saying the project is not hardened for direct exposure. It recommends placing it behind Tailscale, Cloudflare Tunnels or a reverse proxy with authentication.

## Sources

- [eclaire-labs/eclaire on GitHub](https://github.com/eclaire-labs/eclaire)
- [License: MIT](https://github.com/eclaire-labs/eclaire/blob/main/LICENSE)
- [Project website](https://eclaire.co)
- [README](https://github.com/eclaire-labs/eclaire/blob/main/README.md)
- [Releases](https://github.com/eclaire-labs/eclaire/releases)

---

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