cozy-stack: the single server behind the Cozy personal cloud

One process, many installed applications

The platform is described first, and the server second, which is the right order for understanding it.

Cozy is a platform that brings all your web services into the same private space, so your web apps and your devices can share data easily. You can install Cozy on your own hardware where no one profiles you.

The Cozy-Stack is the core server of that platform, and it consists of a single process. Its job is to serve the web applications users have installed from the application store.

That framing explains a lot about the design. There is no per-application server, no runtime where each app gets its own process, and no container orchestration in the middle. A user installs an app, and the app is served by the same binary, talking to the same API, with its data in the same database.

It also explains the unusual shape of the API. Because every app is a client of the same server, the server is the only place where users, sessions, permissions and documents are reconciled, so the API has to be generic enough to serve applications nobody at the project has written. The full documentation is on a separate site, and the readme points to it for both the stack and the platform.

The language is Go, the module path is the cozy one, and the licence is AGPL v3, which is the licence a self-hosted platform that others extend should carry.

What the REST API actually exposes

The readme lists the API surface as a list, and it is short enough to read in one go.

The first capability is to create, update and delete documents inside the database. The second is to authenticate users and client applications. The third is to send emails. The fourth is to launch jobs on the server, and the readme explains that connectors that import data from remote websites are some sort of jobs. Jobs can be one time tasks such as sending a message, or periodic tasks.

The list ends with an ellipsis, which is the honest way to present an API that grew with a platform rather than being designed in one pass.

The database itself is a CouchDB style document store, and the topic list carries couchdb and the cozy-v3 API version, which tells you that the storage model is documents with revisions rather than tables with rows. That choice is what makes the replication API possible.

And that replication API is the piece that matters most for the platform's purpose. The readme says the Cozy-Stack allows access to the database replication API, allowing documents to be synced between the server and local databases, for example in mobile clients. So the server is not just a web backend, it is a sync endpoint, and a phone running the Cozy applications keeps a local copy of the documents and reconciles with the server.

That is the technical core of the personal cloud idea. Your mail, your files and your photos live in one store under your control, and every device holds a replica of what it needs.

Connectors are jobs, and jobs run sandboxed

The job system is where the interesting security engineering sits, and the readme is explicit about it.

Jobs can be one time tasks or periodic tasks, and the connectors that import data from remote websites are a kind of job. Then comes the sentence that matters: some jobs, like the connectors, that require executing third party code on the server side, are sandboxed, and the tool used for that is nsjail.

That is the whole threat model in one clause. A connector is a piece of code that somebody else wrote, which reaches out to a remote site on your behalf and writes the result into your database. Running that inside the stack process would mean any connector compromise is a compromise of the platform and of every user's data on that instance. Sandboxing it means a connector is confined to what the jail allows.

nsjail runs the connector in a jail that limits what it can see and do. It is the same class of tool used to run untrusted build steps in CI, which is exactly the problem shape here.

The periodic jobs are scheduled with a cron library, and the whole point of the job abstraction is that the stack does not need to know what a given job does, only that it runs, on a schedule, with a result.

For a self-hosted installation, the practical consequence is that you need a kernel that supports the isolation primitives, and you need to decide how much you trust the connectors you install from the application store.

Two authentication models, chosen by where the app runs

The readme names two authentication methods, and the reason for the split is the deployment model.

Web applications running on the server get a session token when the user logs in. OAuth2 is used for other applications.

That is a clean division. An app served by the stack is same-origin with the stack, so it can hold a session and act on the user's behalf without a redirect dance. An app that runs somewhere else, on a phone or on another domain, needs the standard OAuth2 flow, with the stack acting as the authorisation server.

The dependency list confirms the shape of that implementation. There is a JWT library at version 5, and a one-time password library for second factor support, and a websocket library, which is what the real time notifications to a running application would use.

There is also a wide set of supporting services, and the dependency list is the best documentation of what the stack actually does. There is a Redis client, a RabbitMQ client, a MinIO client for object storage, a CouchDB style storage layer, a Docker client, an Apple push notification client, a Prometheus client for metrics, a maxmind database reader for geo lookups, an SMTP mail library, a Brotli compressor, an Open Graph parser, a JSON graph library, a file type detector, a user agent parser, a duration formatter, a cron scheduler, a lockfile helper, a websocket server library, an HTTP test library, and a translation library.

The mix tells the story: this is a platform that talks to CouchDB and Redis, queues work in RabbitMQ, stores files in an object store, sends mail through SMTP, pushes to mobile devices, and serves a web application store.

Running it locally in two commands

The Makefile has a developer workflow that is worth reading, because it shows the shape of a running instance.

The install target compiles the code and installs the binary in the Go bin directory:

@go install

The run target starts the stack for local development, and the flags tell you what a development instance needs:

@go run . serve --mailhog --fs-url=file://localhost${PWD}/storage --konnectors-cmd ${PWD}/scripts/konnector-dev-run.sh

MailHog is a mail catcher, so outgoing mail is captured locally instead of being sent. The file storage URL points at a local directory rather than an object store. And the connectors command points at a shell script in the scripts directory, which is how a connector is run in development instead of from the sandboxed job runner.

The second command is what creates an instance, and it is a long one because an instance carries a lot of configuration:

@cozy-stack instances add cozy.localhost:8080 --passphrase cozy --apps home,store,drive,photos,settings,contacts,notes,passwords,dataproxy --email [email protected] --locale fr --public-name Claude --context-name dev

That creates an instance on a local host name and port, with a passphrase, a list of applications to install, an admin email, a locale, a public name and a context name. The application list is the default Cozy set, and seeing them named in a command line makes the platform concrete: home, a store, a drive, photos, settings, contacts, notes, passwords and a data proxy.

For a real installation the readme points at the install guide and the configuration documentation, and the repository holds a configuration example file, a debian packaging directory, a client directory, a web directory, a model directory, a worker directory, a command directory and a tests directory, along with a Transifex configuration for translations and a Renovate configuration for dependency updates.

Maintenance, licence and where the community is

The release history shows a steady cadence on a 1.6 line, with 1.6.62 on 2026-09-29, 1.6.63 on 2026-09-30 and 1.6.64 on 2026-10-13, and the last push was on 2026-10-15. So the code is moving, and it is moving on a patch line rather than in a series of major versions, which is what you want from a server that other people's applications run against.

The licence is AGPL v3, and the readme says Cozy is developed by Twake Workplace. That combination deserves a thought for anyone planning to run a modified instance and offer it to others: the AGPL's network clause means that users interacting with your modified stack over a network are entitled to the corresponding source. For a personal instance that is a non-issue. For a service built on a modified stack, it is the thing to look at before anything else.

The community channels are the usual set: an IRC channel on Libera.Chat, a forum, the GitHub issue trackers across the organisation's repositories, and a Twitter account.

The tooling tells you what a professional codebase looks like in practice. The Makefile enables undefined variable warnings and disables builtin rules, it has a lint target that installs a pinned golangci-lint version from a file rather than whatever is on the machine, a separate JavaScript lint target for the assets and the connector test files, a pretty target using prettier with specific formatting options, and an SVG optimisation target for the icon and image assets. The Go module requires Go 1.25, the CI badge is on the repository, and the package has a Go reference badge on the module documentation site.

Editorial conclusion

cozy-stack suits a team or an individual who wants to run a personal data platform where the applications, the devices and the data live under their own control rather than in someone else's account, and who is prepared to operate a single Go binary with a database behind it. It is a poor fit if you want a hosted app for end users, since the whole point is that you install it yourself, and it is a poor fit if you cannot run sandboxed jobs, because the connectors are where much of the value sits. Before you deploy it, read the install guide and the configuration documentation, decide how you will run the database and the file storage, and confirm that nsjail is available, since the connector jobs are sandboxed with it.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. linagora/cozy-stack on GitHub
3. Project website
4. README
5. Releases