Cozy is a personal server hosting applications that allow collect and manipulate all your personal data.

There are two kind of applications:

In this tutorial, you’ll learn how to write a client application and a connector.


Several layers can be distinguished. From inside to outside:

One of our motto is « Cozy is Simple, Versatile, Yours ». This applies to our architecture:


The server

The server consist of a single process. We call it the Cozy stack. It provides services through a REST API that allow to:

The server also allow to access the database replication API, allowing to sync documents between the server and local databases, for example in mobile clients.

Two authentication methods are available:

The server is in charge of serving the Web applications users have installed from the application store.

The database

CouchDB is a document database. Everything, from user data to server settings, is stored inside typed documents, identified by an unique id.

Two request methods are allowed: map-reduce or Mango, a specific query language.

Every document has a doctype, and we keep an index of the definition of every doctype.

Binary data are stored outside the database. Depending on the server configuration, they may be stored on a file system or a dedicated object storage like swift.

The datasystem layer inside the Cozy stack is in charge of controlling access rights on documents and binaries. It allows fine gained access control, on a whole doctype or on a set of documents.

The applications

The server provide services to applications:

Application store

An application registry lists every available applications, and their characteristics. Each application can:


Each application uses its own sub-domain name, so it gets sandboxed inside the browser: other application are not able to steal it access token and access its data.

We use Content Security Policy to control what the application is allowed to do. For example, Web applications running inside Cozy are not allowed to send requests to other websites. This allow a strict control over applications, preventing them to leak your data.