Created: 2012-03-23 20:53
Updated: 2019-02-24 07:22
License: agpl-3.0

Cozy Proxy

Cozy Proxy redirects requests properly to the right application of the Cozy platform depending on given path. It also handles authentication to the Cozy for users and devices.


We assume here that the Cozy platform is correctly installed on your server.

Type this command to install the proxy module:

$ cozy-monitor install proxy


You can contribute to the Cozy Proxy in many ways:

  • Pick up an issue and solve it.
  • Translate it in a new language.
  • Improve the session management.

Listen on https

It is recommended to run Cozy Proxy behind a reverse proxy like nginx. The reverse proxy does the SSL/TLS stuff in that case. But if you want to run Cozy Proxy with no reverse proxy (low memory server for example), you can set the following env variables:

SSL_CRT_PATH=/path/to/server.crt  # /etc/cozy/server.crt by default
SSL_KEY_PATH=/path/to/server.key  # /etc/cozy/server.key by default

To use this when the whole Cozy stack is running, you can add this variables into the Controller configuration file, /etc/cozy/controller.json, as explained into the documentation. Just add the following lines into this file:

"env": {
  "proxy": {
    "PORT": 443,
    "USE_SSL": true,
    "SSL_CRT_PATH": "/path/to/server.crt",
    "SSL_KEY_PATH": "/path/to/server.key"


The Cozy proxy has a default timeout of 120 seconds. If an application doesn't anwser in 120 seconds, the Proxy will close the connection. If your server is slow, you may want to increase this timeout. Just edit server.js inside the build directory of your proxy (usually /usr/local/cozy/apps/proxy/node_modules/cozy-proxy/build/server) and add server.timeout = 0 juste after return americano.start(options, function(err, app, server) {.


To be hacked, the Cozy Proxy dev environment requires that a CouchDB instance and a Cozy Data System instance are running. Then you can start the Cozy Proxy this way:

$ git clone
$ cd cozy-proxy
$ npm install
$ npm run watch

To hack cozy-proxy using the cozy vagrant

  • Forward cozy-home application port from the virtual machine: :forwarded_port, guest: 9103, host: 9103 in file Vagrantfile (if the virtual machine is already up, you can apply this change with vagrant reload)
  • On your computer, go to your cozy-proxy folder cd your-cozy-proxy-folder
  • Run npm install
  • Once install is done, launch cozy-proxy PORT=9555 HOST="" npm run watch (You may use another port)
  • You can now access the hacked proxy on http://localhost:9555 with your navigator


Build Status

To run tests, type the following command into the Cozy Proxy folder:

$ npm run test

Note: a running data-system is required for the tests.

Contribute with Transifex

Transifex can be used the same way as git. It can push or pull translations. The config file in the .tx repository configure the way Transifex is working : it will get the json files from the locales repository. If you want to learn more about how to use this tool, I'll invite you to check this tutorial.


Cozy Proxy is developed by Cozy Cloud and distributed under the AGPL v3 license.

What is Cozy?

Cozy Logo

Cozy is a platform that brings all your web services in the same private space. With it, your web apps and your devices can share data easily, providing you with a new experience. You can install Cozy on your own hardware where no one profiles you.


You can reach the Cozy Community by:

  • Chatting with us on IRC #cozycloud on
  • Posting on our Forum
  • Posting issues on the Github repos
  • Mentioning us on Twitter
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more