Installation Guide

Download the Latest Release

1. Visit the Releases Page.
2. Pick the .zip file for your platform:
   • 🖥️ Windows/Linux Agent: Lightweight agents to sync data.
   • ☁️ Aw-Sync-Center: The central Prometheus-Grafana setup.
   • 📦 Aw-Sync-Suite: Includes everything in one bundle.
3. Extract the contents of the selected .zip file(s) into your desired directory.

Deploy aw-sync-center

If you downloaded Aw-Sync-Suite or Aw-Sync-Center:

1. Navigate to the aw-sync-center directory:

   cd aw-sync-center

2. Start the cloud components (Prometheus and Grafana) using Docker Compose:

   docker-compose -f docker-compose-default.yaml up -d

This command launches all necessary services for centralized data collection and visualization.

Note

To secure Prometheus endpoints with Bearer token authentication, follow the instructions here.

Configure and Run aw-sync-agent

If you downloaded Aw-Sync-Suite or Windows/Linux Agent, follow these steps:

1. Navigate to the place where agent is located:
   • Aw-Sync-Suite: aw-sync-suite/aw-sync-agent/windows or aw-sync-suite/aw-sync-agent/linux
   • Windows Agent: aw-sync-agent-{version}-windows-86_64/windows
   • Linux Agent: aw-sync-agent-{version}-linux-86_64/linux
2. Open and configure the aw-sync-settings.yaml file located in config folder:
   • Specify the Prometheus and ActivityWatch endpoints.
   • Adjust other settings and plugins if needed.

Tip

Before starting the agent you can run the agent with the flag -testConfig to see your agent configurations, filters, and categories.

Run the Agent

You can run aw-sync-agent in one of the following ways:

1. Standalone Mode

Run the executable directly. Note that the terminal must remain open during the operation:

• Windows:

  .\aw-sync-agent.exe  

• Linux/macOS:

  ./aw-sync-agent  

2. System Service Mode

Run the agent as a background service for continuous syncing.

• Windows:
  • Open the terminal as an administrator before creating the service and run:

    .\aw-sync-agent.exe -service  

• Linux:
  • Create a service by running:

    ./aw-sync-agent -service  

3. Dockerized Mode

Use Docker to containerize and run the agent:

docker run -d \
  --name aw-sync-agent \
  --restart unless-stopped \
  --network host \
  -e ACTIVITY_WATCH_URL=<Your_ActivityWatch_Url> \
  -e PROMETHEUS_URL=<Your_Prometheus_Url> \
  phrp5/aw-sync-agent:latest

Important

If you intend to use the aw-sync-settings.yaml for the Docker configuration, be sure to replace the existing file located at /opt/config/aw-sync-settings.yaml with your own configuration file.

Tip

• Find the latest Docker images here.
• Example Docker Compose setups are available here.
• For detailed configuration options, check this guide.
• For detailed plugins options, check this guide

Visualize in Grafana

1. Open Grafana in your browser.
2. Add Prometheus as a data source.
3. Import the pre-built dashboard (available here) to start visualize the ActivityWatch data.

Warning

Querying an entire year or more in Grafana is a very heavy operation and will likely take some time to load.

Now you're all set! You can efficiently monitor multiple ActivityWatch instances and visualize your data in Grafana. Enjoy exploring your activity data and leveraging insights to enhance your productivity!