Cozy-Stack is the backend server that powers the Cozy platform, enabling users to self-host and unify their web services—like files, contacts, notes, and third-party apps—within a single private space. It eliminates vendor lock-in by giving users full control over their data, with no profiling or external tracking. Built in Go and built atop CouchDB, it serves web applications, manages authentication, and enables real-time data sync across devices and services.
Technically, Cozy-Stack provides a REST API for document management, OAuth2 and session-based authentication, job scheduling with sandboxed connectors (using nsjail), database replication via PouchDB, and real-time communication through WebSockets. It supports deployment via Docker or direct binary installation and integrates with services like Nextcloud, Bitwarden, and Office suites.
What You Get
- REST API for Document Management - Create, update, and delete documents in a CouchDB-backed data system with Mango queries and PouchDB compatibility for client-side sync.
- OAuth2 and Session-Based Authentication - Securely authenticate users via web sessions and third-party OAuth2 clients for apps and mobile devices.
- Sandboxed Jobs and Connectors - Run third-party data importers (konnecteurs) in isolated environments using nsjail to safely import data from services like Gmail, Dropbox, or Twitter.
- Realtime Synchronization - Enable live data sync between server and mobile/desktop clients using WebSocket-based realtime API and CouchDB replication.
- Virtual File System (VFS) - Manage files with metadata, references, and permissions, supporting non-synchronized directories and integration with cloud storage providers.
- Collaborative Editing - Real-time collaborative editing of notes and Office documents via integrated /notes and /office endpoints with live updates.
- Admin API and Instance Management - Programmatically create, backup, and manage multiple Cozy instances via command-line tools and HTTP admin endpoints.
- Sharing and Permissions System - Granular sharing of files, folders, and data between users with configurable access levels and shared drives.
Common Use Cases
- Running a private cloud for personal data - A privacy-conscious user hosts Cozy on a Raspberry Pi to unify their files, contacts, and emails without relying on Google or Dropbox.
- Building a self-hosted productivity suite - A small team deploys Cozy to host collaborative notes, Office documents, and file sharing with end-to-end encryption and no external tracking.
- Syncing data across devices securely - A developer uses Cozy’s PouchDB replication to sync contacts and files between their Linux desktop and Android phone without cloud intermediaries.
- Integrating third-party data sources safely - A sysadmin configures sandboxed konnectors to automatically import bank statements from online banking portals into a private ledger app.
Under The Hood
Architecture
- Monolithic Go application designed for simplicity in deployment, with tightly integrated components for API, file system, and database operations
- Modular CLI built with Cobra, isolating operational concerns like configuration, key generation, and server startup into distinct subcommands
- Configuration system dynamically injects environment variables via Go templates, enabling seamless cross-environment deployment
- Service-layer abstractions in core packages (config, crypto, keyring) provide clear separation of concerns without formal dependency injection containers
- Centralized HTTP server setup with unified client abstractions for both instance and admin APIs, reducing code duplication
Tech Stack
- Go backend leveraging standard library HTTP server with configuration driven by environment variables and templates
- CouchDB as the primary document store with built-in TLS and URL-based connection handling
- Frontend assets embedded directly into the binary via statik, eliminating external asset dependencies
- Build and linting pipeline orchestrated through Makefile with static analysis and unit testing automation
- JavaScript tooling stack including ESLint, Prettier, and SVGO to maintain frontend code quality and optimize assets
- Automated dependency updates via Renovate with gomodTidy hooks and Transifex integration for internationalization
Code Quality
- Extensive test coverage spanning unit, integration, and system-level scenarios with comprehensive assertions and environment isolation
- Clear package boundaries for client, web, model, and job components, promoting encapsulation and testability
- Robust error handling with standardized HTTP codes, custom error types, and precise validation of edge cases
- Consistent Go idioms in naming, with descriptive functions and test helpers that enhance readability and maintainability
- Strong type safety enforced through strict struct definitions, JSON tags, and typed constants to prevent runtime errors
- Comprehensive linting and CI-integrated testing that ensure reproducible builds and reliable test execution
What Makes It Unique
- Native end-to-end encryption with built-in key management, ensuring data remains encrypted at rest and in transit without external dependencies
- Self-hosted admin tools for passphrase and key management, empowering users with full control over their security posture
- Decentralized data ownership model that prioritizes local hosting and portable data formats
- Unified platform integrating file storage, applications, and APIs into a single cohesive system, avoiding microservice complexity
- Extensible konnector system that extends encryption and security guarantees to third-party data sync operations
- Domain-centric instance isolation enabling multi-tenancy through logical separation rather than shared database complexity