Table of contents

This document was written in november and december 2016.


This document explains the architecture and process allowing a cozy instance owner to register to its cozy instance.

Compatibility with the current developments on cozy onboarding is a goal : The following documents has been consulted for this proposal

Instance creation

Creating an instance is done through CLI or through the (future) partner farm manager system. Some settings can be pre-defined on instance creation. (doc).

The CLI also allows to specify which source to use for onboarding and home applications. The defaults will be hosted on

After creation, an instance has a registerToken generated randomly.

Onboarding steps

This document and the cozy-stack are only concerned with login and passphrase registering step which are important for security.

All other steps are handled by the onboarding application.

The onboarding application SHOULD therefore provide the following features

This makes cozy-stack simple and safer while allowing behaviour modification for several install types by picking the correct onboarding application / branch.

This makes it easier to add more onboarding steps and have them run on already-installed cozy: On next login after onboarding application update, it will ask the user.


When an user attempts to access the root of its instance ( or an application (, and she is not logged-in, she is redirected :

After login, the user is always redirected to the onboarding application. It is the onboarding application responsibility to check if registering is complete and reredirect to home.


See settings.

Flow Example

cozy-stack instances add --locale fr

The instance is created

    "domain": "",
    "locale": "fr"