How do I install and update the agent on Linux?

The Linux agent comes as a .deb and as an .rpm. Each package carries everything the agent needs to run, so there is no runtime to install first, and each one registers Worktivity's update channel while it installs, so later versions arrive through the package manager you already use.

Which package do you need

• The .deb is for Debian, Ubuntu and the distributions built on them.
• The .rpm is for Fedora, RHEL and the distributions built on them.

Both come in two architectures. If you are not sure which one your computer is, run uname -m in a terminal. It prints x86_64 on an ordinary desktop or laptop, which means the amd64 .deb or the x86_64 .rpm. It prints aarch64 on an ARM machine, which means the arm64 .deb or the aarch64 .rpm.

Download it

All four packages are on the download page. The file name carries the version number, so it changes with every release. The commands below are written with <version> where that number goes: type the exact name of the file you downloaded instead. In a terminal you can type the first few letters and press Tab, and the shell completes the rest for you.

Install it

Open a terminal in the folder the file landed in, which is usually Downloads. On Debian or Ubuntu:

cd ~/Downloads
sudo apt install ./worktivity-<version>-amd64.deb

On Fedora or RHEL:

cd ~/Downloads
sudo dnf install ./worktivity-<version>-x86_64.rpm

The ./ at the front is not decoration, and leaving it off is the most common way this goes wrong. An argument with no slash in it is read as the name of a package to look up in the repositories the machine knows about. Written without it, the command goes hunting for a package called worktivity-<version>-amd64.deb, finds nothing, and reports that no such package exists, even though the file is sitting right there. The ./ is what makes it a path to a file on disk.

If the install stops because a dependency cannot be found, the package index on the machine is out of date. Refresh it and run the install again:

sudo apt update

Why apt and dnf, and not dpkg -i or rpm -i

Those two commands unpack the file, and that is all they do: neither of them resolves dependencies. With dpkg -i, a missing dependency leaves the package half configured rather than installed, and you have to run sudo apt --fix-broken install afterwards to finish what it started.

There is a second reason, and it is the quieter one. The package recommends two extras: libsecret-tools and xdg-desktop-portal. apt installs recommended packages by default; dpkg does not know what a recommendation is. Without libsecret-tools the agent cannot put its session token in your desktop keyring and falls back to a file with restricted permissions instead, which is weaker than intended. The app says so on screen when it happens, but you would rather it did not happen.

First launch

Installing the package starts nothing. No service is enabled, nothing runs in the background, and nothing is added to your session. The agent runs when you run it.

1. Open Worktivity from your applications menu.
2. Enter the e-mail address and password of your Worktivity account and press Log in.
3. Press Clock in when you start working.

If you want the agent to come up with your desktop, open Settings in the app and turn on Start with the desktop session. The app writes that entry itself, when you ask it to. The package never writes it for you.

Updates

While it installs, the package registers Worktivity's own repository on the machine. That is what makes the next version reachable at all: without it, a package downloaded from a website is a dead end, because nothing records where the file came from and the machine would sit on that version until somebody fetched a newer file by hand.

From then on the agent updates like anything else on the machine. On Debian or Ubuntu:

sudo apt update
sudo apt upgrade

On Fedora or RHEL:

sudo dnf upgrade

There is no Check for updates button in the Linux app, and the app never downloads a new version by itself. The package manager is the only way one arrives. To see which version you are running, open the app and look at the top of the sign-in screen, where the version is printed.

Whether updates arrive without you asking depends on the machine, not on Worktivity. The package switches no automatic upgrade on. On a Debian or Ubuntu machine that already runs unattended upgrades, the package adds Worktivity to the list of sources that mechanism is allowed to consider, so agent updates start arriving alongside the rest; delete /etc/apt/apt.conf.d/51worktivity-unattended to keep them manual. On a Fedora or RHEL machine that already runs dnf-automatic, the repository is picked up like any other enabled one. A machine that does not update itself today will not start doing so because Worktivity was installed.

One note for administrators holding a fleet on a chosen version: on a machine that runs unattended upgrades, installing an older version is undone by the next nightly run, which sees a newer candidate and upgrades straight back. Pin it as well:

sudo apt-mark hold worktivity-agent

and sudo apt-mark unhold worktivity-agent when updates should resume.

openSUSE is a partial case

The .rpm installs on openSUSE with zypper and the agent runs. Automatic updates do not work there, and it is worth knowing before you install rather than after. The package writes its repository definition into /etc/yum.repos.d, and zypper does not read that directory. So on openSUSE every new version has to be downloaded and installed by hand, exactly the way the first one was.

Removing it

sudo apt remove worktivity-agent

sudo dnf remove worktivity-agent

What stays behind either way is everything under your home directory. The package never put it there and does not take it away:

• ~/.config/worktivity holds your settings.
• ~/.local/share/worktivity holds records that have not reached the server yet. Delete it only when you know that queue is empty, because what is in there is working time that exists nowhere else.
• ~/.local/state/worktivity holds the clock state and the logs, which are recreatable.
• ~/.config/autostart/worktivity-agent.desktop is there only if you turned Start with the desktop session on. Turning that setting off before you uninstall removes it; otherwise delete the file.

On Debian and Ubuntu, apt remove also keeps the update source and its signing key, because those count as configuration. sudo apt purge worktivity-agent removes them too. On Fedora and RHEL, removing the package leaves Worktivity's signing key trusted in the rpm database; it vouches for packages signed with that key and for nothing else.

Which app belongs on which computer is in the desktop app comparison. Updating on Windows and macOS works differently and is covered in how to update the desktop app. What happens to your records while the machine has no connection is in what happens if your computer goes offline.