Skip to content
Klutch.sh Docs

Deploying an ActivityWatch App

Introduction

ActivityWatch is an open-source, cross-platform time-tracking and activity analytics tool that automatically logs how you spend time on your computer. It records application usage, website visits, and window titles, then visualizes the data through a web dashboard so you can understand and optimize your workflows without manual tracking.

Running ActivityWatch on Klutch.sh with a Dockerfile lets you centralize data from multiple devices, host your own privacy‑focused analytics backend, and access the web dashboard from anywhere. This guide walks you through creating a Docker-based ActivityWatch server, configuring persistent storage, pushing your project to GitHub, and deploying via the Klutch.sh dashboard at klutch.sh/app.

Prerequisites

Before deploying ActivityWatch on Klutch.sh, make sure you have:

  • A Klutch.sh account
  • A GitHub account (GitHub is the only supported git source)
  • Docker installed locally (optional but recommended for testing)
  • Basic familiarity with containerized apps and environment variables

Project Setup for ActivityWatch

1. Create a Project Directory

Create a dedicated directory for your ActivityWatch deployment:

Terminal window
mkdir activitywatch-klutch
cd activitywatch-klutch
git init

2. Understand the ActivityWatch Architecture

For a server deployment, you typically run:

  • Core ActivityWatch server (aw-server) – stores and exposes activity data over a HTTP API.
  • Web dashboard (aw-webui) – a web interface to explore and visualize your tracked data.

In this guide, you’ll build a container that bundles the ActivityWatch server and web UI, exposing the dashboard and API over HTTP on port 5600.

Creating a Dockerfile for ActivityWatch

Klutch.sh automatically detects a Dockerfile in the repository root and uses it for deployments. You don’t select Docker explicitly in the UI and you don’t configure a Dockerfile path—detection is fully automated.

Create a Dockerfile in the root of your project:

FROM python:3.12-slim


ENV DEBIAN_FRONTEND=noninteractive


WORKDIR /app


# Install system dependencies (if ActivityWatch or its watchers require them)
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      curl \
      ca-certificates \
      tzdata && \
    rm -rf /var/lib/apt/lists/*


# Install ActivityWatch via pip
RUN pip install --no-cache-dir "activitywatch[server,webui]"


# ActivityWatch data directory
ENV AW_DATA_DIR=/data
RUN mkdir -p /data && chown -R root:root /data


# Expose ActivityWatch web UI / API port
ENV PORT=5600
EXPOSE 5600


# Start the ActivityWatch server (includes the web UI)
CMD ["aw-server", "--host", "0.0.0.0", "--port", "5600"]

Dockerfile Notes

  • activitywatch[server,webui] installs the server and web UI packages in the container.
  • ActivityWatch stores its data in AW_DATA_DIR (set to /data), which you will back with a persistent volume on Klutch.sh.
  • The container listens on port 5600, which should be the internal port you configure when creating the app in the Klutch.sh dashboard.

Optional: Local Testing with Docker

You can validate your Docker image locally before deploying to Klutch.sh:

Terminal window
# Build the Docker image
docker build -t activitywatch-klutch .


# Run the container locally
docker run -d \
  --name activitywatch-test \
  -p 5600:5600 \
  -v "$(pwd)/aw-data:/data" \
  activitywatch-klutch

Then open http://localhost:5600 to access the ActivityWatch web dashboard.

For local, multi-container setups or advanced scenarios, you can use Docker Compose. Remember that Docker Compose is only for local development—Klutch.sh does not use Docker Compose for deployments.

Pushing Your ActivityWatch Project to GitHub

Once your Dockerfile and any supporting files are ready, push them to a GitHub repository:

Terminal window
git add .
git commit -m "Initial ActivityWatch Docker setup for Klutch.sh"
git branch -M main
git remote add origin https://github.com/your-username/activitywatch-klutch.git
git push -u origin main

Klutch.sh will use this repository as the source for your ActivityWatch deployment.

Creating an ActivityWatch App on Klutch.sh

With your repository in place, you can now create the app through the Klutch.sh dashboard.

Connect the GitHub Repository

  1. Sign in at klutch.sh/app.
  2. Go to Create Project and give your project a name, such as activitywatch-server.
  3. Navigate to Create App and:
    • Select GitHub as the git source.
    • Choose your ActivityWatch repository and the branch you want to deploy (for example, main).

Klutch.sh will automatically detect the Dockerfile in your repository root and use it to build and run the container.

Configure Traffic Type and Internal Port

  • Traffic Type: Select HTTP (the ActivityWatch dashboard and API are served over HTTP).
  • Internal Port: Set to 5600 to match the EXPOSE 5600 directive and PORT environment variable in your Dockerfile.

This configuration ensures incoming HTTP requests are correctly routed to the ActivityWatch web UI and API inside the container.

Environment Variables on Klutch.sh

ActivityWatch can work with a minimal environment configuration, but you may want to define:

  • AW_DATA_DIR – set to /data (matching your Dockerfile) to store data in a predictable, mountable directory.
  • TZ – timezone (for example, UTC or America/New_York) to ensure timestamps align with your expectations.

If you ever deploy a non-Docker version using Nixpacks instead, you can customize commands with environment variables:

  • BUILD_COMMAND – override the default build command Nixpacks uses.
  • START_COMMAND – override the default start command Nixpacks runs.

Set these environment variables in the Klutch.sh dashboard to control Nixpacks behavior when needed.

Attaching Persistent Volumes

Persistent storage is important for ActivityWatch so your historical activity data is not lost when you redeploy or restart the app.

In the app’s Storage/Volumes section:

  • ActivityWatch Data Volume
    • Mount path: /data
    • Size: Choose based on how much history you plan to keep (for example, 5 GiB, 10 GiB, or more for long-term tracking).

By mounting /data as a persistent volume, ActivityWatch can safely store its database and logs across deployments.

Sample Code: Querying ActivityWatch Data

Once ActivityWatch is deployed on Klutch.sh, you can access its HTTP API to build your own dashboards, integrations, or automations.

Assuming your app is deployed at https://example-app.klutch.sh, the API is available under /api/0/.

Example: Fetch Buckets with JavaScript

async function fetchBuckets() {
  const response = await fetch('https://example-app.klutch.sh/api/0/buckets', {
    headers: {
      Accept: 'application/json',
    },
  });


  if (!response.ok) {
    throw new Error(`Failed to fetch buckets: ${response.status}`);
  }


  return response.json();
}


fetchBuckets()
  .then((buckets) => {
    console.log('Available ActivityWatch buckets:', buckets);
  })
  .catch((error) => {
    console.error('Error fetching buckets', error);
  });

Example: Fetch Events for a Bucket (Python)

import requests


BASE_URL = "https://example-app.klutch.sh/api/0"
BUCKET_ID = "aw-watcher-window_your-machine-name"


response = requests.get(f"{BASE_URL}/buckets/{BUCKET_ID}/events")


if response.ok:
    events = response.json()
    print(f"Fetched {len(events)} events from bucket {BUCKET_ID}")
else:
    print("Error fetching events:", response.status_code, response.text)

You can adapt these examples to build custom reports, dashboards, or automations powered by the ActivityWatch API hosted on Klutch.sh.

Verifying Your Deployment

After deploying the app:

  1. Visit your deployment URL, for example:

    https://example-app.klutch.sh

  2. Confirm that:

    • The ActivityWatch web UI loads successfully.
    • No errors appear in the Klutch.sh logs related to ActivityWatch startup.
    • Data persists across container restarts, indicating the /data volume is working correctly.

If you encounter issues, double-check the internal port, traffic type, and volume mount path in the Klutch.sh dashboard.

Troubleshooting

The Web UI Is Not Accessible

  • Ensure the app’s Traffic Type is set to HTTP.
  • Verify that the internal port is 5600 and matches the Dockerfile.
  • Check the deployment logs in Klutch.sh for Python or ActivityWatch errors.

Data Does Not Persist After Redeploy

  • Confirm that a persistent volume is attached with mount path /data.
  • Ensure ActivityWatch is configured to use AW_DATA_DIR=/data.
  • Verify that the volume size is adequate and the container can write to the directory.

API Calls Fail from Clients

  • Verify that you are using the correct base URL (for example, https://example-app.klutch.sh/api/0).
  • Check that CORS or authentication configuration (if customized) allows your client to connect.
  • Inspect the ActivityWatch logs via the Klutch.sh dashboard for details.

Deploying an ActivityWatch app on Klutch.sh with a Dockerfile gives you a powerful, privacy‑respecting analytics backend that scales with your needs. With a straightforward Dockerfile, proper internal port configuration, and a persistent volume for /data, you can host your own centralized ActivityWatch instance and build custom dashboards and automations on top of its API—without giving up control of your activity data.