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.2

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.2
File Size Uploaded Provenance Actions
ned_watch-0.1.2.tar.gz 33.1 kB With provenance Details for ned_watch-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 67.0 kB

Release files / ned_watch-0.1.2.tar.gz

Download URL ned_watch-0.1.2.tar.gz
Size 33.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3d668f05e4910d09c697722541a92a25a51016abaf9a618bdf6177c9ba8af3c1
BLAKE2b-256 checksum
How to use checksums
7cf28977fea90a6932a385ac1690526b5685f1009bfddd068677fe313ab83fc0
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 8, 2026.

Transparency log

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

Download URL ned_watch-0.1.2-py3-none-any.whl
Size 33.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28b498d032d9a1cd86c30edf5e15eb4c55d6db3e0af3416a314ada17024ec091
BLAKE2b-256 checksum
How to use checksums
29be9f84c72ebc7424e10b9b3c30ade15e9cb07b3a11e2015cdd14352a23e492
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 8, 2026.

Transparency log

Security for ned-watch 0.1.2

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.2.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 8, 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