Cozy Stack

Cozy Stack is the open-source backend server powering the Cozy platform, a personal cloud environment that puts you in control of your own data. Developed by Twake Workplace and distributed under AGPLv3, it enables individuals and small teams to self-host a unified workspace where files, contacts, notes, banking data, and productivity apps coexist in a single private instance — free from profiling, vendor lock-in, or cloud dependency.

At its core, the stack is a single Go binary that speaks REST, manages CouchDB document storage, runs sandboxed jobs (called konnectors) for third-party data importation, and synchronizes data in real time across devices via PouchDB replication and WebSockets. Every user gets their own subdomain-isolated instance, and the admin API makes it straightforward to provision, backup, and migrate those instances programmatically.

Cozy Stack also ships with built-in integrations for collaborative document editing via OnlyOffice, a Bitwarden-compatible password vault API, NextCloud-compatible file sharing, OpenID Connect for federated login, and even a RAG-backed AI chat endpoint. This breadth makes it unusual among self-hosted tools — it is genuinely an application platform, not just a file server.

Deployment is straightforward for technically comfortable users: a single binary, a CouchDB 3 instance, a reverse proxy, and a SMTP relay. Docker images and Debian packages are provided. The project has over a decade of active development with more than 12,000 commits, 130+ releases, and a cadence of roughly two releases per month.

What You Get

• Virtual File System with Full Metadata - Store, version, and organize files with rich metadata, tags, and directory permissions; supports non-synchronized directories and integration with Swift or local storage backends.
• Sandboxed Konnector Job Runner - Execute third-party data importers (konnectors) in isolated nsjail sandboxes to safely pull bank statements, social media exports, and utility bills from external services.
• Real-Time Data Sync via PouchDB Replication - Synchronize documents between the server and mobile or desktop clients using CouchDB’s built-in replication protocol, enabling offline-first apps without custom sync logic.
• OAuth2 App Ecosystem and App Store - Install, update, and manage web applications from the Cozy registry; each app is sandboxed by permissions, runs on its own subdomain, and authenticates via OAuth2 sessions.
• Collaborative Notes and Office Document Editing - Real-time collaborative editing of Markdown notes (using ProseMirror) and Office documents via embedded OnlyOffice integration with live cursor updates.
• Bitwarden-Compatible Password Vault API - Built-in Bitwarden protocol implementation lets users store and sync passwords using any Bitwarden-compatible client against their own private Cozy instance.
• Fine-Grained Sharing and Permissions Engine - Share files, folders, albums, and arbitrary documents with other Cozy users or external parties using a declarative permission model with configurable read/write scopes.
• Multi-Instance Admin API - Programmatically create, configure, backup, export, and delete Cozy instances via a dedicated HTTP admin API and companion CLI, enabling hosting providers to automate provisioning.

Common Use Cases

• Personal private cloud replacing Google Drive - A privacy-conscious individual installs Cozy Stack on a VPS to self-host their files, contacts, and calendar without any third-party data access or advertising profiling.
• Automated financial data aggregation - A household uses konnectors to automatically pull bank statements, insurance documents, and utility invoices into a private Cozy instance for centralized budgeting without sharing credentials with a SaaS.
• Self-hosted team collaboration platform - A small remote team deploys Cozy to share documents, collaborate on notes in real time, and manage a shared password vault without exposing data to external providers.
• Mobile-first offline-capable app platform - A developer builds a mobile app backed by Cozy’s PouchDB replication API, getting offline sync, conflict resolution, and user authentication for free without writing a custom backend.
• Hosting provider multi-tenant deployment - A web hosting company uses the admin API to programmatically provision isolated Cozy instances for customers, each with their own subdomain, storage quota, and application set.

Under The Hood

Architecture Cozy Stack follows a deliberate monolithic design — a single Go process with clearly bounded internal packages rather than microservices. The web layer uses Echo v4 for routing, with each functional domain (files, sharing, jobs, notes, bitwarden, AI) organized into its own web sub-package that registers its routes centrally in routing.go. The model layer mirrors this structure, with packages like model/vfs, model/job, model/sharing, and model/rag encapsulating domain logic independently of the HTTP layer. Instance isolation is achieved through per-tenant CouchDB databases addressed via a prefixer.Prefixer abstraction, allowing the same model code to operate across multiple user instances without any shared mutable state. The job subsystem uses a Broker interface with in-memory and Redis-backed implementations, enabling horizontal scaling without architectural changes.

Tech Stack The backend is written entirely in Go (90%+ of codebase) using Echo v4 as the HTTP framework, CouchDB 3 as the document store accessed via a custom Go CouchDB client with Mango query support, and Redis for distributed job queuing and rate limiting. Authentication uses JWT tokens (golang-jwt/jwt v5) for OAuth2 flows and session-based cookies for web app users. File storage supports local filesystem, OpenStack Swift, and in-memory backends interchangeably. The collaborative editing stack embeds ProseMirror-Go for Markdown note CRDTs and delegates Office document editing to an external OnlyOffice server. Frontend assets are compiled and embedded into the binary via statik, and internationalization is handled through GNU gettext .po files managed with Transifex. A RAG-backed AI endpoint proxies to a configurable LLM service for AI chat within the platform.

Code Quality The codebase shows extensive test coverage with over 150 _test.go files spanning unit, integration, and HTTP-level tests using gavv/httpexpect. Error handling is explicit and typed — custom error types with JSON:API-compliant HTTP error responses are consistently used across the web layer. The Go idioms are clean and consistent: well-named exported types, descriptive function names, and _test.go helper packages that make integration tests readable. CI runs on GitHub Actions with a dedicated lint step and the Go Report Card shows high code quality scores. Dependency management uses Go modules with Renovate for automated updates and gomod tidy verification, keeping the dependency graph current.

What Makes It Unique Cozy Stack stands out by being a full application platform rather than a single-purpose tool — it combines file storage, contact sync, note editing, password management, financial data aggregation, and AI chat behind a single binary with a unified permission model. The konnector sandboxing system using nsjail to safely execute third-party data importers is architecturally distinctive: it lets users import data from external services without exposing credentials to those services. The Bitwarden-compatible API implementation means users get a battle-tested password manager UX (using existing clients) against their own private server. The per-instance CouchDB architecture combined with PouchDB replication enables genuinely offline-capable mobile apps without any custom sync protocol.

Self-Hosting

Cozy Stack is licensed under the GNU Affero General Public License version 3 (AGPLv3). This is a strong copyleft license with a network-use clause: if you modify the stack and run it as a service accessible over a network, you must publish your modifications under the same license. For organizations using the software internally without offering it as a service to others, standard AGPL obligations are manageable. Commercial use is permitted, but any SaaS deployment built on a modified stack requires sharing those modifications publicly.

Running Cozy Stack yourself requires meaningful infrastructure: a CouchDB 3 cluster, a reverse proxy (nginx, Caddy, or HAProxy), a SMTP relay for email, ImageMagick for thumbnail generation, and optionally Redis for distributed job queuing and an OpenStack Swift cluster for scalable file storage. The stack is stateless itself — all persistent state lives in CouchDB and the filesystem or Swift — which simplifies horizontal scaling but means you are fully responsible for CouchDB replication, backup, and disaster recovery. The Debian packages and Docker images reduce initial setup friction, but long-term operations (CouchDB upgrades, certificate renewal, storage scaling, schema migrations) require ongoing engineering attention. Documentation covers self-hosting basics but assumes Linux and sysadmin competence.

Cozy.io, the commercial managed hosting offered by Twake Workplace, adds dedicated support, automated backups, high availability infrastructure, managed upgrades, and a customer portal. Self-hosters gain full data sovereignty and no per-user fees, but give up SLA guarantees, professional support channels, and the operational simplicity of a managed service. For small personal deployments the trade-off strongly favors self-hosting; for organizations where uptime guarantees matter, the managed tier is worth evaluating.