Habitica Self-Hosted

Last reviewed Aug 26, 2026 · 831 words

Habitica is the rare open-source web app where I tell most people not to self-host it. The hosted service at habitica.com is free for everything that matters, the code is the same GPL-3.0 code you would run yourself, and the thing that makes Habitica work, the social pressure of a party and the guild challenges, does not come across to a private instance with 3 users. Self-hosting is the right call for a specific person: someone who wants the mechanics without an account on a public service, and who is comfortable building a Node.js application from source.

What the hosted service gives away for free

The whole game loop is free upstream: habits, dailies, to-dos, the avatar, gear, pets, quests, parties and challenges. The paid subscription buys cosmetic gems and some convenience, not features. So the usual self-hosting argument, "the free tier is crippled", does not apply. What you gain by hosting is data locality (your task list and its history live on your disk), the ability to grant yourself every gem and pet as an admin, and no dependence on the company continuing to exist. What you give up is the part that made Habitica popular: strangers to quest with. Be honest about which of those you value before continuing.

The stack: Node, MongoDB, and a long first build

The repository ships a docker-compose.yml that brings up 3 containers: a MongoDB instance, the API server on port 3000, and the Vue client. The first build compiles the front end with webpack and takes long enough that people assume it hung; on a modest VPS it is many minutes, and you will want the 1 GB minimum in the catalogue treated as a floor for the running system, with more during the build. Configuration lives in a config.json copied from config.json.example, and the two values that matter are BASE_URL, which must be the exact public URL or links in emails and the client point at the wrong place, and NODE_DB_URI for Mongo. Set BASE_URL before the first user registers. The difficulty rating of "Hard" is earned less by any single step than by the accumulation of build tooling, a database with its own upgrade rules, and an upstream that is developed for its own production environment rather than for other people's deployments.

The mobile apps point at habitica.com, and that is the deal-breaker

This is the part the "Mobile apps" highlight does not spell out. The official Android and iOS apps are open source, but they are built with the production API URL baked in. To use them against your instance you must clone the app repositories, change the server address, and build and sign them yourself, then sideload on Android or go through a developer account on iOS. Most self-hosters end up using the web client on their phone instead, which works but loses push reminders and the native feel. If your reason for wanting Habitica is the phone experience, a private instance will disappoint you.

Keep it private, and read the licence

Habitica's licence is GPL-3.0 with additional terms, and the project is clear that self-hosted instances are for private, non-commercial use and should not present themselves as Habitica to the public; the artwork and name are the project's. A personal or household instance is fine. Running one for a club, a class or a company is where I would read the terms carefully rather than take my summary for it. Do not expose the instance to the internet unless you have a reason; it is a 2013-era Express application that evolved under one team's production assumptions, and behind a VPN like Tailscale you avoid the whole question of hardening it.

Lighter ways to get most of the value

If what you want is a task manager you own, Vikunja does lists, kanban, Gantt and recurring tasks in a single Go binary with a fraction of the setup, and the project management category has a dozen more. If the gamification is the point, the honest answer is that nothing self-hostable does it as well as Habitica does, which is exactly why the hosted service is the sensible default. The Todoist alternatives page walks through the non-game options if you are leaving a commercial to-do app.

What I'd do

Use habitica.com and export my data now and then. Self-host only if I have a firm privacy reason, I am happy with the web client on my phone, and I enjoy the kind of afternoon that involves a webpack build. In that case: compose file from the repository, BASE_URL set before anyone registers, MongoDB dumped nightly with mongodump to an off-box location, instance reachable over Tailscale only, and no expectation of updates arriving on a schedule that suits me.