PyNinja

Lightweight OS-agnostic service monitoring API

Python

Platform Supported

Platform

Deployments

Kick off

Recommendations

Install python 3.11 or above
Use a dedicated virtual environment

Install PyNinja

python -m pip install pyninja

Initiate - IDE

import pyninja


if __name__ == '__main__':
    pyninja.start()

Initiate - CLI

pyninja start

Use pyninja --help for usage instructions.

Environment Variables

Sourcing environment variables from an env file

By default, PyNinja will look for a .env file in the current working directory.

Basic API

APIKEY - API Key for authentication.
SWAGGER_UI_PARAMETERS - Dictionary of parameters to be included in the Swagger UI.
NINJA_HOST - Hostname for the API server.
NINJA_PORT - Port number for the API server.
HOST_PASSWORD - Password to authenticate sudo commands on the server. Applies only for POSIX systems.
OBSERVABILITY_SESSION - Session timeout for observability metrics.

Functional improvements

RATE_LIMIT - List of dictionaries with max_requests and seconds to apply as rate limit.
LOG_CONFIG - Logging configuration file path.

Remote execution and FileIO

REMOTE_EXECUTION - Boolean flag to enable remote execution.
API_SECRET - Secret access key for running commands on server remotely.
DATABASE - FilePath to store the auth database that handles the authentication errors.

⚠️ Warning: Enabling remote execution carries significant security risks. To enhance security, it is mandatory to use multifactor authentication (MFA) token.

Multifactor Authentication (MFA)

MFA_TIMEOUT - Timeout duration for MFA in seconds.
MFA_RESEND_DELAY - Resend duration for MFA in seconds. Cool off period before a new MFA can be requested.
Email
- GMAIL_USER - Gmail username for MFA.
- GMAIL_PASS - Gmail password for MFA.
- RECIPIENT - Recipient email address for MFA. Defaults to GMAIL_USER
Ntfy
- NTFY_URL - Ntfy server URL.
- NTFY_TOPIC - Subscribed ntfy topic.
Include NTFY_USERNAME and NTFY_PASSWORD if the topic is protected.
Telegram
- TELEGRAM_TOKEN - Telegram bot token.
- TELEGRAM_CHAT_ID - Telegram chat ID to send MFA.
Authenticator
- AUTHENTICATOR_APP - Authenticator app name. Defaults to PyNinja.
- AUTHENTICATOR_USER - Authenticator username. Defaults to thevickypedia.
- AUTHENTICATOR_TOKEN - MFA Authenticator token.
To generate a QR code for any authenticator application:

Code
```
import pyninja
pyninja.otp.generate_qr(show_qr=True)
```
CLI
```
pyninja --mfa
```
📓 Generating an authenticator token using PyNinja is the simplest ways to set up MFA authentication. However, the trade-off is that the token is short-lived. Each MFA passcode is only valid for 30 seconds.

Monitoring UI

MONITOR_USERNAME - Username to authenticate the monitoring page.
MONITOR_PASSWORD - Password to authenticate the monitoring page.
MONITOR_SESSION - Session timeout for the monitoring page.
DISK_REPORT - Boolean flag to enable disk report feature using PyUdisk.
MAX_CONNECTIONS - Maximum number of monitoring sessions allowed in parallel.
PROCESSES - List of process names to include in the monitor page.
SERVICES - List of service names to include in the monitor page.
SERVICE_LIB - Library path to retrieve service info.
SMART_LIB - Library path for S.M.A.R.T metrics using PyUdisk.
GPU_LIB - Library path to retrieve GPU names using PyArchitecture.
DISK_LIB - Library path to retrieve disk info using PyArchitecture.
PROCESSOR_LIB - Library path to retrieve processor name using PyArchitecture.

Certificates

CERTBOT_PATH - Path to the certbot binary for certificate management.
CERT_SCAN - Dictionary of key-value pairs threshold and schedule to set up certificate expiry monitoring.
- threshold - Expiry threshold in days to trigger alerts.
- schedule - Time in %H:%M format to run the certificate monitoring job daily.

macOS Specific Binaries

OSASCRIPT - Path to the osascript binary for macOS. Defaults to /usr/bin/osascript
MDLS - Path to the mdls binary for macOS. Defaults to /usr/bin/mdls
OPEN - Path to the open binary for macOS. Defaults to /usr/bin/open

Windows Specific Binaries

pwsh - Path to the pwsh binary for Windows. Defaults to C:\Program Files\PowerShell\7\pwsh.exe

📓 Certain environment variables like SERVICES and PROCESSS are case-sensitive

Refer samples directory for examples.

Coding Standards

Docstring format: Google
Styling conventions: PEP 8 and isort

Release Notes

Requirement

python -m pip install gitverse

Usage

gitverse-release reverse -f release_notes.rst -t 'Release Notes'

Linting

pre-commit will ensure linting, run pytest, generate runbook & release notes, and validate hyperlinks in ALL markdown files (including Wiki pages)

Requirement

python -m pip install sphinx pre-commit recommonmark

Usage

pre-commit run --all-files

Pypi Package

https://pypi.org/project/PyNinja/

Runbook

https://thevickypedia.github.io/PyNinja/

License & copyright

Licensed under the MIT License

Metadata

Release files for PyNinja 5.2.0

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

Built distribution (wheel)

Table of built distributions (wheels) for PyNinja 5.2.0
File	Interpreter	ABI	Platform	Reset
pyninja-5.2.0-py3-none-any.whl 109.9 kB Oct 6, 2026	Python 3	none	any	Details

Release files / pyninja-5.2.0-py3-none-any.whl

Download URL	pyninja-5.2.0-py3-none-any.whl
Size	109.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f3d47402b91c16e72b95cb8041436411311ef0d52ef0cec4af600192b651116b`
BLAKE2b-256 checksum How to use checksums	`a8340376eb240126c4bd28d394c5dd7dcb7268ebe779553f6cb6c07468f619e8`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.0rc1`