Skip to main content

Python

Know when your Python agent or job silently stops.

from nedwatch import Ned                       # pip install ned-watch, and set NED_CALLBACK_URL
@Ned().deadman("nightly-sync", every="1h")     # Ned fires if this hasn't finished cleanly for an hour
def sync(): ...

ned-watch has no dependencies (it uses urllib). If httpx is installed, the async calls use it. Python 3.9 and up.

Setup

pip install ned-watch
export NED_CALLBACK_URL=https://your-agent.example/hooks/ned

That's all. The first time a watch is used, the client creates your agent, saves the agent key to ~/.config/ned-watch/state.json (mode 0600, never printed), registers the watch with condition.arm so the clock starts right away.

Variable Meaning
NED_CALLBACK_URL where Ned POSTs signed fire / clear messages (required to register a watch)
NED_AGENT_KEY your key, to use the same agent on another machine (else read from the state file)
NED_API / NED_REGION API base, or eu for https://api-eu.ned.watch
NED_STATE state file path
NED_REF the tag sent as X-Ned-Ref when your agent is created (default: the framework detected, else python)
NED_WATCH_NAME default watch name (else the script's file name)

Deadman: "fire if this stops succeeding"

from nedwatch import Ned

ned = Ned()

@ned.deadman("nightly-sync", every="1h")        # every: "90s", "20m", "1h", "1h30m", "1d", or seconds
def sync():
    ...                                         # a return checks in; an exception doesn't

Or check in yourself, for example at the end of each loop of a long-running agent:

heartbeat = ned.deadman("research-agent", every="10m")
while True:
    do_one_task()
    heartbeat.checkin()

grace= sets a different deadline from every (for example every="1h", grace="90m").

Overrun: "fire if this is still running"

with ned.run("etl", max="20m"):
    load_everything()

run() starts an overrun run on entry and finishes it on a clean exit. If the block is still running 20 minutes after it started, Ned fires once; if it finishes late, he sends clear with late: true and the runtime.

Add every= to get both in one go: the overrun catches hangs, the deadman catches failures and missed schedules.

with ned.run("etl", max="20m", every="1d"):
    load_everything()

What happens when the block raises:

on_error= effect
"report" (default) finish the run with status: "failed" and a short error (exception class + first line, credentials redacted, at most 200 chars): Ned fires at once and clears on the next clean run. No deadman check-in.
"leave_open" never finish a failed run (Ned fires when max passes)
"finish" finish it as if it succeeded (the failure is not reported)

ned.run(...) also works as a decorator (a new run per call) and with async with.

Async

The decorator and run() work on async def functions and with async with. Direct calls have a versions: await ned.acheckin(...), await ned.astart(...), await ned.afinish(...), await ned.aget(...).

@ned.deadman("poller", every="5m")
async def poll(): ...

async with ned.run("crawl", max="1h"):
    await crawl()

Direct calls

ned.checkin("nightly-sync")                    # by name (registered by this client), or by id "w_..."
ned.checkin("w_0123456789ab", signing_secret=...)
ned.start(overrun, run_id="2026-10-05")        # run_id makes retries safe
ned.finish(overrun, run_id="2026-10-05")       # failed=True, error="..." reports a crash
ned.get("w_...")  ned.watches()  ned.cancel("w_...")  ned.balance()
ned.register("http", target="https://example.com/health", interval_s=300)   # any watch type, as is

Errors are NedError (with .status and .detail); a missing callback URL or secret is NedConfigError. The decorator and run() never raise for a Ned problem unless you made the client with Ned(strict=True).

Command line

nedwatch setup --name nightly-sync --every 1h [--max 30m]   # make the watch(es) and do the first check-in
nedwatch checkin nightly-sync                               # put at the end of a job
ned-run --name backup --max 30m --every 1d -- ./backup.sh  # wrap any command (see cron)
nedwatch doctor [--create]                                  # key, connectivity, a real test callback
nedwatch status

uvx ned-watch <command> runs the same CLI without installing anything. Secrets stay in the state file; setup --show-secrets prints them as env lines if you need them elsewhere.

Frameworks

Verifying callbacks

from nedwatch import verify_signature
if not verify_signature(signing_secret, request.headers, await request.body()):
    return Response(status_code=401)

MIT licensed.

Metadata

Release files for ned-watch 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ned-watch 0.1.0
File Size Uploaded Provenance Actions
ned_watch-0.1.0.tar.gz 30.5 kB With provenance Details for ned_watch-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ned-watch 0.1.0
File Interpreter ABI Platform Actions
ned_watch-0.1.0-py3-none-any.whl Python 3 none any Details for ned_watch-0.1.0-py3-none-any.whl

Total release size: 62.8 kB

Release files / ned_watch-0.1.0.tar.gz

Download URL ned_watch-0.1.0.tar.gz
Size 30.5 kB
Tags Source
SHA-256 checksum
How to use checksums
fe2df843cd6d953855ab1f7ac194e6aa25f3d8017e6654c106431ca93e207dfe
BLAKE2b-256 checksum
How to use checksums
c8581a58bbd5b1147e76d8e2560baa5795b788cf27ae4fffa1769f47b93946ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

Release files / ned_watch-0.1.0-py3-none-any.whl

Download URL ned_watch-0.1.0-py3-none-any.whl
Size 32.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
50f842b35732f2a89f5d138ef074432ef0c93cbd16c9c0ddb0cbee41f64a2d25
BLAKE2b-256 checksum
How to use checksums
5186de585eb36174a8881ec79685d67c0a92fae108c63321ecd98939277bb3d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

Security for ned-watch 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ned_watch-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page