Cozy 2 (will be deprecated in 2017)

The full Cozy stack and the server-side code of the applications are writtent in Node.js


Cozy v2 use Node.js and CouchDB as our main technologies.

Node JS

Node.js is a great and modern engine with a huge community of module creators. It has evolved along with the GitHub’s Open-Source popularization and is now wide-spread in the Web industry. Aside from being heavily maintained, it remains fun to extend and play with.


CouchDB is surely less-known, but definitely reliable. As a proper Erlang program, it has proven its strength and stability. A consistent, well-documented API, plus wonderful replication capabilities: the recipe of what we love of a database engine.

Getting Started

This section is a quick tutorial showing the different steps to start using Cozy as a development environment, making a simple app, and interact with your data.

Introduction to Cozy Cloud architecture

Before writing code, let’s have an overview of the Cozy Cloud architecture. The platform is made of 3 main components:

The Cozy Cloud architecture is detailed in a specific part.

Set up the Development Environment

Since Cozy is made from several pieces, we wrapped it into an easy-to-use Virtual Machine, so you don’t clutter your local system. This also means you can use the operating system you like! Well, there are obviously issues on Windows, so we will assume here that you use a GNU/Linux system or Mac OS X.

The environment is made of two parts: the Virtual Machine itself - a fully installed Cozy platform - and a local Node.js tool called cozy-dev which will help you getting started and deploying your app to your Cozy.

1. Install Git

On GNU/Linux, just install Git with your package manager

apt-get install git

On Mac OS, download the software here:

# To check if Git is installed
git --version

The first step is obviously to install the development dependencies. Git is the SCM we use at Cozy, and if you don’t know how to use it yet, don’t worry: we will give example commands in the following tutorial.

2. Install Node.js

On Debian GNU/Linux Jessie, one of the proper version of Node.js (0.10.29) is available in the official repositories

apt-get install nodejs nodejs-legacy npm

On other GNU/Linux systems, you can install Node.js manually by following instructions from

On Mac OS X, simply download the package, and install it

# To check the Node.js version
node --version

Installing Node.js on your local environment is necessary to run your app and use cozy-dev. Cozy runs well on Node.js v0.10 and Node.js 4.3, and you should install one of those versions.

You can find detailed instructions of installation on the official page.

3. Install VirtualBox and Vagrant

VirtualBox is used to emulate a full Operating System in a Virtual Machine. You can download it from The Virtualbox website. Make sure you have the latest version installed!

Vagrant is a Command-Line Interface to interact with VirtualBox and handle development environment easily. You can download it from The Vagrant website. Make sure you have the latest version installed!

4. Install cozy-dev

# Use the -g option to install system-wide
sudo npm install -g cozy-dev

As mentioned above, cozy-dev is a set of tools aiming to help you managing your app deployment and your development environment. It is recommended to install it system-wide.

The full documentation of cozy-dev can be found below on the related section.

5. Download and start the environment

# Create a development directory
mkdir cozy && cd cozy

# Download the environment
cozy-dev vm:init

# Start the environment
cozy-dev vm:start

# Check that the environment is properly started
cozy-dev vm:status

# Update the environment (strongly recommended)
cozy-dev vm:update

Use cozy-dev to initialize the environment. It is recommended to update it at the end because we do not necessarily maintain the raw image in an up-to-date state, as a new version of Cozy can be released every couple of weeks ☺

Write your own application

From this point onward, you have a choice to make:

Client-side application

If you want to make a simple app that only manipulates data inside the Cozy (no sharing, no accessing an external API), head over to the Client-side apps section.

Node.js application

If you want to make a powerful app using node.js, which manipulates files, accesses remote APIs or allows access to a cozy visitor with complex rules, go to the Node.js app.

Understanding the platform

Architecture and Components

Understanding how the platform is built is essential to be able to work with it.

The following figure displays the different parts of Cozy, that we are going to describe.

Cozy platform

Cozy is made of three main components: a persistent layer, the Data System, the personal Platform as a service and the platform interface.

The Data System

Gihub repository

Personal data is at the core of Cozy, therefore the Data System is the central piece of Cozy where all your data is safely stored and ready to be used.

The Data System is a unified API which consists of: - the database itself, CouchDB, where all your personal data and Cozy data is stored as document, each document having a type depending on the data it contains (a contact, an email, a setting) - binaries, stored in CouchDB too, that in particular allow to authenticate and authorize requests made by Cozy so that resources (apps for example) can only access the document types they are allowed to access - the indexer

It is important to emphasize here that the Data System owns the data, and decides whether the requests made by the Cozy platform are allowed or not.

You can find the complete API and details about the Data System on the dedicated cookbook.

The pPaas

Github repository

The personal Platform as a service, or pPaas, is an execution environment for applications collaborating around personal data. It consists mainly of the Controller, which installs, runs, updates and removes applications within Cozy. You can call the Controller using the Home, which is itself an application installed by the Controller. There is also a command line interface, cozy-monitor, that allows you to call the Controller if you have root privileges on your server.

Making the most of the Data System using applications

The Controller therefore manages applications. These applications will store their data in the Data System. As we have seen, the Data System, not the application, owns the data. Therefore, when installing or updating an application, the user will be prompted to grant the application access to certain document types. This paradigm enables easy and straightforward collaboration between the applications: granting access to the “Contact” document type to both the Contacts application and the Emails one will allow to send an message in Emails to someone the user will have informed the contact details in Contacts. And this is a common, nearly boring example, but it can be done with any document type and any data!

Moreover, uninstalling or breaking an application will not erase your data, you will be able to recover it.

The platform interface

The platform interface consists of the Home (Gihub repository) and the Proxy (Gihub repository).

As we have seen above, Home is an interface to the Controller which allows the user to manage applications in Cozy.

Up to now, we have seen that the Data System owns the data, that the Controller can manage applications and that applications can interact with data in the Data System. How can the user access all this data? The Proxy will enable it, and is the last part of the Cozy platform. It handles authentication and authorization in Cozy. It manages registration, login, logout and password reset. It also handles all the routing of Cozy (to send the right request to the right application).

If you want to learn more about authentication and authorization in Cozy, there is a dedicated cookbook on the subject.

What you should remember

As a developer, you are going to create an application that will be run by Cozy’s pPaaS. That application will access the data through the Data System. Also, you won’t have to bother with user authentication and authorization because it is all handled by the Proxy.

Keep in mind you’re developing for a personal environment. It might be something you are not used to at first. It changes the relationship to data we had until now!

With these three presentations, you have a clear view on the architecture of the Cozy platform, and we will now details a bit more several subjects.

Authentication and permissions

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Encryption management

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.


Konnectors is an application that allows small module of code to retrieve data from the outside world like invoices, activity tracker, or whatever you want. It is actively developed and maintained by the community, and generally a good way to start coding for Cozy: you write a piece of application, not a complete application.

You can find the documentation to write a connector on the repository’s wiki.

Sharing data between Cozy

We’ve been working on a protocol to share data between Cozy. It’s still a work in progress, but the relevant documentation can be found here.


You can find the old documentation here.

Data System API

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.


We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Cozy Browser SDK

It’s the same as cozy-db, except for the browser so you can directly interact with the data-system from there. You will find the documentation here.

Devices API

If you want to build an application that is not run by Cozy, like a mobile or a desktop application, you can use the Devices API to manage authentication. You will find the documentation here.

Cozy Development Environment

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Cozy Desktop

If you’d like to get technical documentation on cozy-desktop, you can find it here.

Controller API

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

You can also check the configuration documentation if you’d like to understand how to play with it.

Main document types

All Cozy apps produce many data as JSON document that can be reused in your own application. The main document types available are the following ones:

Doc Type Main Fields
BankOperation title, date, amount
Bill type, vendor, date, amount
BloodPressure systolic, diastolic
Bookmark title, url, tag
Commit sha, parent, tree, url, author, email, message, additions, deletions, files
Contact datapoints, n, fn, org, title, bday, department
Event start, end, description, place, rrule
File name, path, class, lastModification, creationDate, size, mime, checksum
Folder name, path, lastModification, creationDate
Email headers, from, to, cc, bcc, replyTo, subject, text, html, date, attachments, inReplyTo
Note title, content, creationDate, lastModificationDate
Photo title, description, orientation, binary
Sleep deepSleepDuration, lightSleepDuration, sleepDuration
Steps distance, steps
UseTracker dateStart, dateEnd, duration, app
Weight weight, leanWeight, fatWeight
Tasky creationDate, completionDate, description, tags