pip install posthumous
Copy

git clone https://github.com/queelius/posthumous.git
cd posthumous
pip install -e ".[dev]"
Copy

pip install -e ".[dev]"
pytest                          # Run all tests (448 tests, 98% coverage)
Copy

# 1. Initialize a new node — generates TOTP secret and shows QR code
posthumous init --node-name laptop

# 2. Scan the QR code with your authenticator app

# 3. Start the daemon
posthumous run

# 4. Check in periodically
posthumous checkin
# or use the short alias
phm checkin
Copy

notifications:
  default:
    - "ntfy://my-topic"
  urgent:
    - "ntfy://my-topic"
    - "mailto://user:pass@smtp.gmail.com?to=contact@example.com"
  family:
    - "tgram://bot_token/chat_id"
Copy

actions:
  on_warning:
    - notify: default
      message: "Check-in needed. {days_left} days remaining."
  on_grace:
    - notify: urgent
      message: "URGENT: Posthumous triggers in {hours_left} hours."
  on_trigger:
    - notify: urgent
      message: "Posthumous has activated."
    - script: "scripts/on_trigger.py"
Copy

post_trigger:
  - name: "annual_letter"
    when: "every year on trigger"
    script: "scripts/annual_letter.py"

  - name: "birthday_message"
    when: "every March 15"
    notify: default
    message: "Happy birthday. Thinking of you always."

  - name: "weekly_check"
    when: "every week after trigger"
    script: "scripts/weekly_maintenance.py"

  - name: "one_time_upload"
    when: "trigger + 1 day"
    script: "scripts/upload_files.py"
Copy

node_name: "laptop"
secret_key: "JBSWY3DPEHPK3PXP"
listen: "0.0.0.0:8420"
api_token: "my-automation-token-here"

checkin_interval: 7 days
warning_start: 8 days
grace_start: 12 days
trigger_at: 14 days

peers:
  - https://backup-server.home:8420
  - https://vps.example.com:8420

notifications:
  default:
    - "ntfy://posthumous-alerts"
  urgent:
    - "ntfy://posthumous-alerts"
    - "mailto://user:pass@smtp.gmail.com?to=family@example.com"

actions:
  on_warning:
    - notify: default
      message: "Check-in needed. {days_left} days remaining before trigger."
  on_grace:
    - notify: urgent
      message: "URGENT: Posthumous triggers in {hours_left} hours."
  on_trigger:
    - notify: urgent
      message: "Posthumous has activated for node {node_name}."
    - script: "scripts/on_trigger.py"

post_trigger:
  - name: "annual_letter"
    when: "every year on trigger"
    script: "scripts/annual_letter.py"
  - name: "birthday_message"
    when: "every March 15"
    notify: default
    message: "Happy birthday. Thinking of you always."
  - name: "immediate_upload"
    when: "trigger"
    script: "scripts/upload_encrypted.py"
Copy

ARMED ──timeout──► WARNING ──timeout──► GRACE ──timeout──► TRIGGERED
  ▲                   │                   │                    │
  └───── check-in ────┴───── check-in ────┘                    │
                                                               ▼
                                                          (scheduler runs forever)
Copy

"trigger"                    # At trigger time
"trigger + 3 days"           # 3 days after trigger
"trigger + 1 hour"           # 1 hour after trigger
Copy

"every day after trigger"    # Daily from trigger
"every week after trigger"   # Weekly from trigger
"every month after trigger"  # Monthly from trigger
"every 30 days after trigger" # Custom interval
Copy

"every year on trigger"      # Annual trigger anniversary
Copy

"2030-01-01"                 # Specific date
Copy

"every December 25"          # Yearly on Christmas
"every March 15"             # Yearly on date
"every March 15 - 7 days"   # 7 days before March 15 each year
Copy

notifications:
  alerts:
    - "ntfy://my-private-topic"
    - "ntfy://user:pass@ntfy.example.com/topic"
Copy

notifications:
  email:
    - "mailto://user:pass@smtp.gmail.com?to=recipient@example.com"
    - "mailto://user:pass@smtp.gmail.com?to=person1@example.com,person2@example.com"
Copy

notifications:
  slack:
    - "slack://TokenA/TokenB/TokenC/#channel"
Copy

notifications:
  discord:
    - "discord://webhook_id/webhook_token/"
Copy

notifications:
  telegram:
    - "tgram://bot_token/chat_id"
Copy

notifications:
  gotify:
    - "gotify://hostname/token"
Copy

notifications:
  pushbullet:
    - "pbul://access_token"
Copy

{
  "event": "trigger",
  "trigger_time": "2026-02-10T14:30:00+00:00",
  "node_name": "laptop",
  "status": "triggered",
  "last_checkin": "2026-01-27T09:15:00+00:00",
  "schedule_item": null,
  "extra": {}
}
Copy

#!/usr/bin/env python3
"""Upload encrypted files when triggered."""

import json
import os
import subprocess

def main():
    context_file = os.environ.get("POSTHUMOUS_CONTEXT_FILE")
    if context_file:
        with open(context_file) as f:
            context = json.load(f)

    event = os.environ.get("POSTHUMOUS_EVENT")
    node = os.environ.get("POSTHUMOUS_NODE")

    if event == "trigger":
        # Upload encrypted archive to cloud storage
        subprocess.run(["rclone", "copy", "/encrypted/vault", "remote:backup/"])
        print(f"Vault uploaded from {node}")

    return 0

if __name__ == "__main__":
    exit(main())
Copy

# With TOTP code
curl -X POST http://localhost:8420/checkin \
  -H "Content-Type: application/json" \
  -d '{"totp": "123456"}'

# With API token
curl -X POST http://localhost:8420/checkin \
  -H "Content-Type: application/json" \
  -d '{"token": "my-api-token"}'
Copy

{
  "success": true,
  "status": "armed",
  "next_deadline": "2026-02-24T14:30:00+00:00"
}
Copy

curl http://localhost:8420/status
Copy

{
  "node_name": "laptop",
  "status": "armed",
  "last_checkin": "2026-02-10T14:30:00+00:00",
  "trigger_time": null,
  "time_remaining": {
    "until_warning": 172800.0,
    "until_grace": 518400.0,
    "until_trigger": 691200.0
  }
}
Copy

curl http://localhost:8420/health
Copy

# On the first node
posthumous init --node-name primary

# On additional nodes — join with the shared secret
posthumous init --node-name backup --join https://primary:8420
# Enter the secret from the primary node when prompted
Copy

signature = HMAC-SHA256(secret_key, "checkin:<timestamp>")
signature = HMAC-SHA256(secret_key, "trigger:<timestamp>")
signature = HMAC-SHA256(secret_key, "scheduled:<item_name>:<period>")
Copy

posthumous [OPTIONS] COMMAND

Options:
  --version          Show version
  -v, --verbose      Enable debug logging
  -c, --config PATH  Custom config file path

Commands:
  init                Initialize a new node
    --node-name TEXT  Node name (required)
    --join URL        Join existing federation

  config              Configuration management
    path              Show file locations
    show              Print config (secret redacted)
    validate          Check config for errors
    edit              Open in $EDITOR, validate on close

  run                 Start the daemon
    -d, --daemon      Background mode (not yet implemented)

  checkin             Check in to reset timer
    -t, --token TEXT  Use API token instead of TOTP

  status              Show current status and time remaining

  peers               Show peer status

  test-notify         Send test notifications
    -c, --channel     Test specific channel (default: all)

  test-trigger        Dry-run trigger actions

  export PATH         Export state and config to YAML
  import PATH         Import state from YAML backup
Copy

posthumous import backup.yaml
Copy

[Unit]
Description=Posthumous Deadman Switch
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/usr/local/bin/posthumous run
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
Copy

sudo systemctl enable posthumous
sudo systemctl start posthumous
sudo systemctl status posthumous
Copy