Python-LocalAPI 🚀

A highly flexible, configuration-driven local API bridging automated tasks, scripts, and webhooks securely across your network.

Stop worrying about building new web servers every time you write a script. Just map your local .py, .bat, .vbs, or .sh files in a JSON config, and Python-LocalAPI instantly exposes them as secure REST API endpoints.

🌟 Features

• Cross-Platform Compatibility: Runs flawlessly on both Windows Native and Linux/Docker.
• Fire-and-Forget Background Tasks: Trigger heavy orchestration scripts silently in the background without holding up your webhook response.
• Dynamic Argument Injection: Pass payload variables directly from your POST request safely into your command line arguments using {{placeholders}}.
• Self-Healing Socket Management: The app automatically finds and kills zombie processes holding onto its required port before starting.
• Built-in Security: Restrict execution using simple X-Token headers and customizable IP Allow-lists.
• Log Rotation: Neatly categorizes logs into a discrete /logs subfolder, ensuring your directory stays clean while managing file rotation automatically.

---

🛠️ Quick Start

1. Installation

Clone the repository and install the requirements (Requires Python 3.9+).

git clone https://github.com/NickWinston123/Python-LocalAPI.git
cd Python-LocalAPI
pip install -r requirements.txt

2. Setup Configuration

Copy the example configuration files and add your specifics.

cp .env.example .env
cp actions.json.example actions.json

3. Run the Server

Simply execute the script. It will self-heal its assigned port and initialize.

python LocalAPI.py

(If running via Docker/Uvicorn directly, you can also launch via: uvicorn LocalAPI:app --host 0.0.0.0 --port 8787)

---

🛡️ Windows Background Service & Watchdog

For Windows users, this repo includes a built-in background launcher and health-checker.

Instead of keeping a terminal window open forever, simply double-click run.bat.

1. It silently checks if the API is running on port 8787.
2. If it's down, it launches LocalAPI.py completely hidden in the background.
3. If it crashes, clicking run.bat again will instantly revive it.

Watchdog logs are automatically generated in logs/localapi_watchdog.log.

---

⚙️ Configuration File (actions.json)

All routing logic is driven by actions.json. You define "actions" which map a URL path to a local executable. The system seamlessly handles both Linux/Docker and Windows environments.

Example Configuration:

"actions": {
  "linux-discord-relay": {
    "exe": "python",
    "cwd": "/app",
    "args":[
      "scripts/discord_sender.py",
      "--msg", "{{msg}}"
    ],
    "timeout_seconds": 10,
    "capture_output": true
  },
  
  "windows-background-task": {
    "exe": "C:\\path\\to\\pythonw.exe",
    "cwd": "C:\\path\\to\\working\\directory",
    "args":[
      "tts_manager.py",
      "--text", "{{text_raw}}"
    ],
    "timeout_seconds": 600,
    "capture_output": true,
    "background": true
  }
}

Triggering the actions above automatically maps a JSON POST payload containing msg or text_raw directly into the command line execution.

---

📦 What your Webhook Receives (Payload format)

Whenever a script is triggered via the API, make a POST request to http://<YOUR_IP>:8787/run/<action_name>.

Request (JSON Body)

Provide dynamic arguments inside the params object:

{
  "params": {
    "msg": "Server backup completed successfully!"
  },
  "dry_run": false
}

Response (JSON)

The API returns a clean JSON summary of the execution:

{
  "ok": true,
  "action": "linux-discord-relay",
  "background": false,
  "returncode": 0,
  "stdout_tail": "Message sent to Discord.",
  "stderr_tail": "",
  "request_id": "8a3b11cf",
  "cmd":["python", "scripts/discord_sender.py", "--msg", "Server backup completed successfully!"],
  "cwd": "/app"
}

---

🔒 Security Header

If LAN_API_TOKEN is set in your .env file, the bot strictly enforces authorization. Ensure your request includes this as a custom header:

X-Token: your_secret_here