How to setup taskwarrior 3.0 sync

Written: 2025-07-13, Last Updated: N/A

It took me a while to figure out how to setup this thing because there is almost no documentation on how to do it and the configuration options are very misleading to say the least, so here is a little tutorial on how to task syncing on taskwarrior 3.0.

Install the taskchampion service on your server

There are many ways to sync your tasks but the only one that didn't seem to be horrible was taskchampion. If you want to learn more about other ways to do this you can read the manual page with the command man task-sync.

I'm using NixOS so this was pretty trivial for me. I made the service accessible through a reverse proxy with nginx. If you don't know what NixOS is you can just ignore this part and find a wiki page on how to setup taskchampion on your distro. System flake excerpt services = { taskchampion-sync-server = { enable = true; allowClientIds = [ "85038910-8fe2-480d-b6cb-6e7fabc1fa44" # Personal ]; }; nginx = { enable = true; package = pkgs.nginxStable.override { openssl = pkgs.libressl; }; recommendedProxySettings = true; recommendedTlsSettings = true; virtualHosts."taskchampion.${domain}" = { addSSL = true; enableACME = true; locations."/" = { proxyPass = "http://127.0.0.1:${toString config.services.taskchampion-sync-server.port}"; }; }; }; }; We'll talk about what allowedClientIds means later.

Setting up your taskrc

Once we have the sync server up and running we need to configure the clients that will connect to it. For example I had to configure my laptop and desktop.

Knowing where your data is

By default taskwarrior will be an asshole and create the taskrc at ~/.taskrc, cluttering your home and giving you another problem to deal with in your life, which you never should have had to deal with in the first place.

Thankfully you can move it to ~/.config/task/taskrc without the usual 1-2 combo follow up problem of having to export global vars like TASK_CONFIG_HOME="$XDG_CONFIG_HOME/task/taskrc" and TASK_DATA_HOME="$XDG_DATA HOME/task".

Instead it goes for the unconventional approach of defining those dreaded global vars in the config file directly like so: ~/.config/task/taskrc excerpt data.location=~/.local/share/task hooks.location=~/.config/task/hooks Anyways, venting aside, this is important because you will most likely need to know where your task database is for the next part. Taskwarrior stores tasks in an sqlite database, which is a file. Even if you're not planning to sync your tasks you should know where your database so that you can easily back it up, and easily not delete it by accident like me when reinstalling your system 🥲.

Setting up sync

Next you have to configure the sync settings. Let me explain the non obvious settings.

client_id, unlike it's name would lead you to believe, is not a unique id for your device at all. It's a unique id for the task database you are syncing to the server, a better name for it would be database_id.
This means you should set this to the same id on all the devices you intend to sync the database too. You can use the uuidgen command for this.

encryption_secret is the key used to encrypt the database when sending it over the network. Don't share this with anyone. You can generate it with whatever you want, I just used bitwarden. I don't know what kind of encryption it's using so I went with a long key just in case. ~/.config/task/taskrc excerpt sync.server.url=https:\/\/taskchampion.leonardgomez.com sync.server.client_id=85038910-8fe2-480d-b6cb-6e7fabc1fa44 sync.encryption_secret=cTzG4DMSX7rS3xx%OhNcb2cXgED$hdS$zszQptUyVhYkqR3$LVPz3HioIn5*%m6IgxGF7m2zqRi*0Mma7uB%IUobfSTj%WJw1YL*tlE$mjG548F%OwWs3XaOX15pRh#z

Syncing your tasks

Once you have setup your taskrc with the same sync settings on all your devices you can sync the database by running task sync on your devices.

If you are successfully syncing your database with no error messages but the tasks aren't syncing, you've probably already synced your database with bad settings previously. I made the same mistake because I thought that client_id was a unique id to identify your devices and so I synced my db on multiple devices with different client ids. To fix this I suggest backing up your database and then running task export > test && task import test to clear the sync metadata. After this, syncing should work correctly again.