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
- LangGraph / LangChain:
NedCallbackHandler - CrewAI:
kickoff(crew, ...) - OpenAI Agents SDK:
NedRunHooks - Claude Agent SDK:
NedHooks
Verifying callbacks
from nedwatch import verify_signature
if not verify_signature(signing_secret, request.headers, await request.body()):
return Response(status_code=401)
Links
- Docs: https://ned.watch/integrations/python
- API and callback contract: https://ned.watch/skill.md
- Node version:
npm i @nedwatch/ned-watch - MCP server:
uvx ned-watch-mcp, or remotehttps://api.ned.watch/mcp - Contact: ned@ned.watch
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.