Hammerhead Connector

Dreeve imports anything dropped into its watch/ folder. Getting your Hammerhead activities into that folder is what the Hammerhead (Karoo) Connector does: it periodically fetches workout activities from the Hammerhead Dashboard API, downloads the original .fit files, and drops them in. No manual exports.

Hammerhead Dashboard → connector → watch/ → Dreeve imports it

The connector is a separate container from its own repository, dreeveapp/dreeve-hammerhead-connector. It is not part of Dreeve itself, it only writes files into the folder you already mount.

Important

The Hammerhead API requires an OAuth 2.0 application. You will need to create a free developer application on Hammerhead’s Dashboard to obtain a Client ID and Client Secret before setting up the connector. Read Hammerhead’s Creating a Developer Account guide first.

Setup

1. Register for your Hammerhead Partner API Setup

1. Enable your developer setting by loging into your normal Hammerhead Dashboard account here: https://dashboard.hammerhead.io/partner/signup
2. At the Partner API Setup page, enter the required details:

• App Name: Dreeve Hammerhead Connector
• Description: Activity downloader for ingest into Dreeve
• Logo: download the logo.svg from https://github.com/dreeveapp/dreeve/blob/master/public/assets/images and add this to this the Partner API Setup screen
• Accept the license agreement
• Click Continue

3. At the API Settings page https://dashboard.hammerhead.io/settings#api_settings, make note of your Client id and Client Secret, you’ll need these later for the Environment Variables. DO NOT share these values with anyone else.
4. Update the Redirect Urls to be http://localhost:8080/callback
5. Ignore all other sections of the page.
6. Edits have been auto-saved, you can now close the Hammerhead Dashboard tab.

2. Add the container

Add this alongside the app and daemon services in your docker-compose.yml:

docker-compose.yml

  # Pulls workouts out of Hammerhead Dashboard into the watch folder.
  hammerhead-connector:
    image: ghcr.io/dreeveapp/dreeve-hammerhead-connector:latest
    container_name: dreeve-hammerhead-connector
    restart: unless-stopped
    env_file: ./.env
    volumes:
      # The same ./watch folder the app and daemon mount.
      - ./watch:/data/dreeve/watch
      - ./hammerhead/state:/data/hammerhead/state
      - ./hammerhead/tokens:/data/hammerhead/tokens
    networks:
      - dreeve-network

3. Configure it

Add to your .env:

.env

# Hammerhead Connector Environment Variables
HAMMERHEAD_CLIENT_ID=your-client-id
HAMMERHEAD_CLIENT_SECRET=your-client-secret
# Interval (seconds) to check for new activities.  Default 30 mins (1800 seconds)
HAMMERHEAD_POLL_INTERVAL=1800

4. One-Time Run / Initialisation

Before you can make full use of the Hammerhead Connector to download your activities / FIT files, you’ll need to complete the OAuth workflow that generates a token for the connector to use.

> docker compose run --rm hammerhead-connector setup http://localhost:8080/callback

What happens:

1. The terminal prints a long https://api.hammerhead.io/... URL. Copy the whole thing into your regular web browser.
2. Log in to Hammerhead if asked, and approve access.
3. Hammerhead redirects your browser to http://localhost:8080/callback?code=SOMETHING&state=.... Nothing is actually listening on port 8080, so the page itself will fail to load — that’s expected. What you need is in the address bar: copy just the value after code= and before the next &.
4. Back in the terminal, it’s waiting with a prompt: Paste the code query param from the redirect URL: — paste that value and press Enter.

This exchanges the code for an access/refresh token pair, saved to /data/hammerhead/tokens/tokens.json in the container (i.e. ./hammerhead/tokens/tokens.json on the host). That file is your login for every future run — you won’t need to repeat this step unless you delete it or revoke access.

5. Start it

> docker compose up -d

Important

Important: If you’re added the Hammerhead Connector to an existing Dreeve setup, or need to edit any of the environment variables, just like Dreeve, the .env file is read when the container is created. After changing it, run docker compose up -d --force-recreate.

6. Monitoring the service

To see events / logs generated by the Hammerhead Connector, issue the following command into your Docker Host’s terminal

> docker compose logs -f hammerhead-connector

How sync works

• The first time that the service runs, it will initiate a download of every activity already present in your Hammerhead Dashbaord. From that point, the service remembers that date of the last activity that it synced and only downloads new activities since that date, stores that new date and repeats.
• If there’s ever a need to initial a full re-download of all activities, delete the sync_state.json file stored in ./hammerhead/state/. The Dreeve App has inbuild activity duplication protection and will autmatically ignore anything in the ./watch folder that is already in its database.
• Since the Dreeve Daemon that is monitoring the ./watch folder does not know if a .fit file is fully downloaded, the Hammerhead Connector uses Atomic file delivery, writing to a temporary (.part) file before renameing to .fit after the download is successful. This prevents Dreeve from parsing partial files.

Persistent storage layout

On the host (wherever docker-compose.yml lives), the connector expects:

• Directorywatch/ FIT files land here; point Dreeve at this folder

  • …
• Directoryhammerhead

  • Directorystate

    • sync_state.json which activities are already downloaded
  • Directorytokens

    • tokens.json OAuth access/refresh tokens