Use cases

A day on PushWard

One homelab, one day of pushes. Pick a time to see which service sends what, which way it comes in, and how it lands on the iPhone.

Workday script

Start the workday with one tap

At 7:00 a small script asks on the Lock Screen. Tapping Start answers it, and the card turns into an eight-hour countdown.

REST API
Live Activity

How it's wired

workday.sh

# 07:00 from cron or launchd
curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "slug": "approval-request",
      "name": "Workday"
    }'

curl -X PATCH https://api.pushward.app/activities/approval-request \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
      "state": "ongoing",
      "content": {
        "template": "approval",
        "state": "Start your workday?",
        "source": "Script",
        "icon": "calendar",
        "accent_color": "blue",
        "details": [
          {
            "label": "Calendar",
            "value": "3 meetings, first at 9:30"
          }
        ],
        "options": [
          {
            "id": "start",
            "title": "Start",
            "style": "primary"
          },
          {
            "id": "later",
            "title": "Later",
            "style": "secondary"
          }
        ]
      }
    }'

Read the guide

Find your setup

The same flows, grouped by who would run them. Open one to see its config.

Homelab

Servers, monitors, downloads and backups that report in on their own.

Gatus Relay webhook

Know when a site goes down, and when it's back

How it's wired

gatus/config.yaml

alerting:
  custom:
    url: "https://relay.pushward.app/gatus"
    method: "POST"
    headers:
      Content-Type: "application/json"
      Authorization: "Bearer hlk_YOUR_KEY"
    # body: see the Gatus entry in the Relay guide

Read the guide

Unraid Unraid plugin

Night jobs on the NAS
How it's wired
Plugins > Install Plugin

https://github.com/mac-lucky/pushward-unraid-plugin/raw/main/pushward-unraid.plg
Read the guide

SABnzbd Docker bridge

Downloads with speed and time left

How it's wired

compose.yaml

services:
  pushward-sabnzbd:
    image: ghcr.io/mac-lucky/pushward-sabnzbd:latest
    environment:
      PUSHWARD_URL: https://api.pushward.app
      PUSHWARD_API_KEY: hlk_YOUR_KEY
      PUSHWARD_SABNZBD_URL: http://sabnzbd:8080/api
      PUSHWARD_SABNZBD_API_KEY: your-sabnzbd-api-key
    restart: unless-stopped

Read the guide

Backrest Relay webhook

Backups that report in
How it's wired
Backrest > Hooks > Shoutrrr

generic+https://relay.pushward.app/backrest?@authorization=Bearer+hlk_YOUR_KEY&contenttype=application/json
Read the guide
Komodo Relay webhook

Container alerts from Komodo
How it's wired
Komodo > Alerter > Custom

https://pushward:[[PUSHWARD_KEY]]@relay.pushward.app/komodo
Read the guide

Developers and CI

Builds, deploys and alerts on the Lock Screen, from any forge.

GitHub Actions Docker bridge

Watch CI jobs step by step

How it's wired

compose.yaml

services:
  pushward-github:
    image: ghcr.io/mac-lucky/pushward-github:latest
    environment:
      PUSHWARD_URL: https://api.pushward.app
      PUSHWARD_API_KEY: hlk_YOUR_KEY
      PUSHWARD_GITHUB_TOKEN: github_pat_YOUR_TOKEN
      PUSHWARD_GITHUB_OWNER: your-username
    restart: unless-stopped

Read the guide

Argo CD Relay webhook

Follow a deploy from sync to healthy

How it's wired

argocd-notifications-cm.yaml

data:
  service.webhook.pushward: |
    url: https://relay.pushward.app/argocd
    headers:
    - name: Authorization
      value: Bearer $pushward-key
  # plus the sync-running / sync-succeeded / deployed
  # templates and triggers from the Argo CD guide

Read the guide

Forgejo Actions CLI

Report from any CI with the CLI

How it's wired

.forgejo/workflows/release.yml

env:
  PUSHWARD_API_TOKEN: ${{ secrets.PUSHWARD_API_TOKEN }}
steps:
  - run: pushward activity start release --name "Release v2.4.0" --template steps --step 1/3 --step-labels Build,Test,Ship --text Building
  - run: make build
  - run: pushward activity update release --step 2/3 --text Testing && make test
  - run: pushward activity update release --step 3/3 --text Shipping && make publish
  - run: pushward activity end release --status success

Read the guide

Grafana Grafana plugin

Alerts that carry their own chart

How it's wired

grafana.ini

[plugins]
allow_loading_unsigned_plugins = pushward-alerts-app

# Then Apps > PushWard: paste the key, pick alert rules
# for timelines and PromQL queries for widgets.

Read the guide

Smart home

Printers, appliances and reminders from around the house.

Bambu Lab Docker bridge

Follow a 3D print layer by layer

How it's wired

compose.yaml

services:
  pushward-bambulab:
    image: ghcr.io/mac-lucky/pushward-bambulab:latest
    environment:
      PUSHWARD_URL: https://api.pushward.app
      PUSHWARD_API_KEY: hlk_YOUR_KEY
      PUSHWARD_BAMBULAB_HOST: your-printer-ip
      PUSHWARD_BAMBULAB_ACCESS_CODE: your-access-code
      PUSHWARD_BAMBULAB_SERIAL: your-printer-serial
    restart: unless-stopped

Read the guide

Home Assistant HACS integration

Reminders and room temperatures

How it's wired

Home Assistant

HACS > search "PushWard" > Download > restart
Settings > Devices & Services > Add Integration > PushWard

PushWard > Add tracked to-do list   todo.reminders
PushWard > Add tracked widget        sensor.living_room_temperature, ...

Read the guide

Home Assistant HACS integration

Any entity as a Live Activity
How it's wired
Home Assistant

Settings > Devices & Services > PushWard > Add tracked entity sensor.dishwasher_status
Read the guide

AI agents

Agents that keep you posted and ask before they act.

Self-hosted AI agent MCP server

Let an agent ask before it acts

How it's wired

MCP

# Connect the agent once
claude mcp add --transport http pushward https://mcp.pushward.app/mcp

# What it calls before it orders
create_activity      approval card "Place the grocery order?"  [Approve] [Not now]
wait_for_answer      blocks until a button is tapped -> "approve"
create_notification  "Order placed"

Read the guide

Self-hosted AI agent MCP server

Recurring reminders an agent sets up

How it's wired

MCP

# "Remind me every Friday at 16:00 to do the weekly review"
create_scheduled_notification  cron "0 16 * * 5"  "Weekly review"

Read the guide

Personal dashboards

Your own numbers and routines on the Home Screen and Lock Screen.

Workday script REST API

Start the workday with one tap

How it's wired

workday.sh

# 07:00 from cron or launchd
curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "slug": "approval-request",
      "name": "Workday"
    }'

curl -X PATCH https://api.pushward.app/activities/approval-request \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
      "state": "ongoing",
      "content": {
        "template": "approval",
        "state": "Start your workday?",
        "source": "Script",
        "icon": "calendar",
        "accent_color": "blue",
        "details": [
          {
            "label": "Calendar",
            "value": "3 meetings, first at 9:30"
          }
        ],
        "options": [
          {
            "id": "start",
            "title": "Start",
            "style": "primary"
          },
          {
            "id": "later",
            "title": "Later",
            "style": "secondary"
          }
        ]
      }
    }'

Read the guide

Budget app REST API

Your budget on the Home Screen

How it's wired

budget-sync.sh

curl -X POST https://api.pushward.app/widgets \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "slug": "budget-trend",
      "name": "Spending",
      "content": {
        "template": "trend",
        "icon": "chart.line.uptrend.xyaxis",
        "label": "Budget used",
        "subtitle": "October",
        "value": 68,
        "unit": "%",
        "min_value": 0,
        "points": [
          4,
          9,
          12,
          18,
          21,
          27,
          30,
          34,
          41,
          44,
          49,
          53,
          58,
          61,
          64,
          68
        ],
        "trend": "up",
        "accent_color": "mint"
      }
    }'

Read the guide

Mac scripts REST API

Scripts on your Mac

How it's wired

ai-limits.sh

# every 30 minutes from launchd
curl -X POST https://api.pushward.app/widgets \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "slug": "ai-limits",
      "name": "AI usage",
      "content": {
        "template": "stat_list",
        "icon": "sparkles",
        "label": "AI usage",
        "accent_color": "purple",
        "stat_rows": [
          {
            "label": "Work account",
            "value": "5h 38% · 7d 61%"
          },
          {
            "label": "Personal",
            "value": "5h 0% · 7d 12%"
          }
        ]
      }
    }'

Read the guide

Eight ways in

Every flow on this page uses one of these. Most take a few minutes to set up.

Wire up your first service

Get an integration key in the app, pick one of the ways in above, and your first card is on the Lock Screen a few minutes later.

Get Started Playground