Deadlock API Ingest

A lightweight background tool that monitors your Steam HTTP cache for Deadlock game replay files and automatically submits match metadata to the Deadlock API. This helps build a comprehensive database of Deadlock matches for the community.

How It Works

The application scans Steam's local HTTP cache directory (Steam/appcache/httpcache/) for Deadlock replay URLs (.meta.bz2 and .dem.bz2 files). When it finds replay file references, it extracts the match IDs and salts, then submits them to the Deadlock API at api.deadlock-api.com. This allows the API to fetch and process match data from Valve's servers.

Key Features:

• 🔒 Privacy-focused: Only reads Steam's local cache files
• ⚡ Lightweight: Minimal CPU and memory usage
• 🔄 Automatic: Continuously monitors for new matches as you play
• 📦 Runs without admin: Application runs with standard user permissions (admin only needed for auto-start setup on Windows)

Resources

• DeepWiki Documentation

Quick Installation

Windows (PowerShell)

Run this command in PowerShell:

irm https://raw.githubusercontent.com/deadlock-api/deadlock-api-ingest/master/install-windows.ps1 | iex

Or download and run manually:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/deadlock-api/deadlock-api-ingest/master/install-windows.ps1" -OutFile "install-windows.ps1"
.\install-windows.ps1

⚠️ Auto-Start Permissions: If you want the application to start automatically on system boot, you'll need to run PowerShell as Administrator. However, the application itself runs without admin privileges - you only need admin rights to create the scheduled task for auto-start. If you run the installer without admin rights, you can still install and run the application manually.

Linux (Bash)

Run this command:

curl -fsSL https://raw.githubusercontent.com/deadlock-api/deadlock-api-ingest/master/install-linux.sh | bash

Or download and run manually:

wget https://raw.githubusercontent.com/deadlock-api/deadlock-api-ingest/master/install-linux.sh
chmod +x install-linux.sh
./install-linux.sh

Note: The installation scripts automatically download the latest release binaries from GitHub and set up the application to run on user login. The application installs to your user directory and does not require elevated privileges.

Docker

Run the pre-built Docker image:

docker run -d --restart unless-stopped \
  -v ~/.steam/steam/appcache/httpcache:/root/.steam/steam/appcache/httpcache \
  ghcr.io/deadlock-api/deadlock-api-ingest:latest

Note: The command above mounts the default Steam cache directory on Linux (~/.steam/steam). If your Steam installation is in a different location, please adjust the path accordingly.

NixOS

Option 1: Using the NixOS Module (Recommended)

Add this flake to your NixOS configuration:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    deadlock-api-ingest.url = "github:deadlock-api/deadlock-api-ingest";
  };

  outputs = { self, nixpkgs, deadlock-api-ingest, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        # Import the module
        deadlock-api-ingest.nixosModules.default
        
        # Configure the service
        {
          services.deadlock-api-ingest = {
            enable = true;
            # IMPORTANT: Set this to the user who has Steam installed
            user = "your-steam-username";
            group = "users";
          };
        }
      ];
    };
  };
}

Important: Replace "your-steam-username" with your actual username that has Steam installed.

Then rebuild your system:

sudo nixos-rebuild switch --flake .#your-hostname

The service will automatically start and run in the background, monitoring your Steam cache.

Option 2: Run Directly

You can also run it directly without installing:

nix run github:deadlock-api/deadlock-api-ingest

Option 3: User Service (Manual)

For a user-level systemd service without the NixOS module:

# In your home-manager or systemd user services
systemd.user.services.deadlock-api-ingest = {
  Unit = {
    Description = "Deadlock API Ingest Service";
    After = [ "graphical-session.target" ];
  };

  Service = {
    ExecStart = "${pkgs.deadlock-api-ingest}/bin/deadlock-api-ingest";
    Restart = "on-failure";
    RestartSec = "10s";
  };

  Install = {
    WantedBy = [ "default.target" ];
  };
};

Then enable: systemctl --user enable --now deadlock-api-ingest

Uninstallation

Windows

& "$env:LOCALAPPDATA\deadlock-api-ingest\uninstall-windows.ps1"

Or navigate to %LOCALAPPDATA%\deadlock-api-ingest\ and double-click uninstall-windows.ps1.

Older Versions:

irm https://raw.githubusercontent.com/deadlock-api/deadlock-api-ingest/master/uninstall-windows.ps1 | iex

Linux

Run the local uninstall script:

~/.local/share/deadlock-api-ingest/uninstall-linux.sh

Older Versions:

curl -fsSL https://raw.githubusercontent.com/deadlock-api/deadlock-api-ingest/master/uninstall-linux.sh | bash

Note: The installer automatically copies the uninstall script to the installation directory for offline use.

Automated Releases

This project uses automated releases that are created on every push to the master branch. The GitHub Actions workflow:

1. Builds cross-platform binaries for Windows and Linux
2. Generates semantic versions based on commit count and SHA
3. Creates GitHub releases with properly named assets:
   • deadlock-api-ingest-windows-latest.exe - Windows executable
   • deadlock-api-ingest-ubuntu-latest - Linux executable
4. Provides installation instructions in each release

The installation scripts automatically fetch the latest release, so you always get the most up-to-date version.

Manual Installation

If you prefer to install manually, you can download the appropriate binary from the releases page and set it up as a service yourself.

Windows Manual Setup

1. Download deadlock-api-ingest-windows-latest.exe
2. Place it in %LOCALAPPDATA%\deadlock-api-ingest\
3. Create a scheduled task to run on user login (no admin required)

Linux Manual Setup

1. Download deadlock-api-ingest-ubuntu-latest
2. Place it in ~/.local/share/deadlock-api-ingest/ or ~/.local/bin/
3. Make it executable: chmod +x deadlock-api-ingest
4. Create a systemd user service file in ~/.config/systemd/user/

Privacy & Security

• Only reads Steam's local cache files
• Only extracts match IDs and salts from replay file URLs
• No Personal Data: Does not access, store, or transmit any personal information or game data
• Read-Only Access: Only reads from Steam's cache directory - never modifies files
• Open Source: Full source code is available for review and audit

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues, please open an issue on the GitHub repository