{"id":21178502,"url":"https://github.com/cyrof/remotewakeserver","last_synced_at":"2026-05-22T05:03:39.025Z","repository":{"id":241322512,"uuid":"804971608","full_name":"Cyrof/RemoteWakeServer","owner":"Cyrof","description":"This project provides a Wake-on-LAN (WoL) HTTP server with two scripts: main.py to send WoL packets and server.py to handle HTTP requests. The server can be deployed using Docker, with environment variables for the MAC address and broadcast IP specified in the Docker run command or Docker Compose. Ideal for remote server management.","archived":false,"fork":false,"pushed_at":"2024-05-27T14:59:04.000Z","size":8,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-21T11:45:09.920Z","etag":null,"topics":["docker","python","wake-on-lan"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cyrof.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-23T16:19:32.000Z","updated_at":"2024-12-02T18:49:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"c3df32ef-8775-4be0-ab8b-79141eabe76c","html_url":"https://github.com/Cyrof/RemoteWakeServer","commit_stats":null,"previous_names":["cyrof/remotewakeserver"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FRemoteWakeServer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FRemoteWakeServer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FRemoteWakeServer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FRemoteWakeServer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cyrof","download_url":"https://codeload.github.com/Cyrof/RemoteWakeServer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243629220,"owners_count":20322015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","python","wake-on-lan"],"created_at":"2024-11-20T17:21:49.555Z","updated_at":"2026-05-22T05:03:39.019Z","avatar_url":"https://github.com/Cyrof.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wake-on-LAN HTTP Server\n\nA lightweight Wake-on-Lan (WoL) HTTP API and web UI, designed for homelab and Kubernetes (k3s) environments.\n\nIt allows you to securely send WoL magic packet via:\n\n- a simple web UI (button click)\n- HTTP API requests\n\nTypical use case:\n\n\u003e VPN into home -\u003e open internal URL -\u003e click \"Wake PC\" -\u003e RDP / Parsec in\n\n## Features\n\n- FastAPI-based HTTP API\n- Simple built-in web UI\n- Token-based authentication (optional but recommended)\n- Multiple devices support (by name or MAC)\n- Docker \u0026 Kubernetes friendly\n- Multi-arch images (amd64 / arm64)\n- Works great behind VPN (WireGuard / Pi-hole DNS)\n\n## How It Works\n\n1. Client sends an HTTP request (or clicks a button)\n2. Server validates an optional auth token\n3. Server sends a Wake-on-LAN magic packet via UDP broadcast\n4. Target machine powers on\n    \u003e For best reliability in Kubernetes, run this service with `hostNetwork: true` so broadcast packets reach you LAN correctly.\n\n## Configuration\n\nAll configuration is done via environment variables.\n\n### Required / Common Variables\n\n| Variable        | Description                      | Example          |\n| --------------- | -------------------------------- | ---------------- |\n| `WOL_BROADCAST` | Broadcast IP for your LAN        | `192.168.68.255` |\n| `WOL_PORT`      | UDP port for WoL (default: 9)    | `9`              |\n| `WOL_TOKEN`     | Optional auth token              | `supersecret`    |\n| `WOL_DEVICES`   | JSON map of device names to MACs | see below        |\n\n### Example `WOL_DEVICES`\n\n```json\n{\n    \"pc\": {\n        \"mac\": \"AA:BB:CC:DD:EE:FF\"\n    },\n    \"nas\": {\n        \"mac\": \"11:22:33:44:55:66\"\n    }\n}\n```\n\n## Running with Docker\n\n### Pull the image\n\n```sh\ndocker pull cyrof/remotewakeserver:latest\n```\n\n## Run the container\n\n```sh\ndocker run -d \\\n    -p 8000:8000 \\\n    -e WOL_BROADCAST=192.168.68.255 \\\n    -e WOL_TOKEN=supersecret \\\n    -e WOL_DEVICES='{\"pc\":{\"mac\":\"AA:BB:CC:DD:EE:FF\"}}' \\\n    cyrof/remotewakeserver:latest\n```\n\nThen open:\n\n```arduino\nhttp://localhost:8000\n```\n\n## API Usage\n\n### Health Check\n\n```sh\ncurl http://localhost:8000/healthz\n```\n\nResponse:\n\n```json\n{ \"ok\": true }\n```\n\n### List Devices\n\n```sh\ncurl -H \"X-Auth-Token: supersecret\" \\\n    http://localhsot:8000/api/devices\n```\n\nResponse:\n\n```json\n[\"pc\", \"nas\"]\n```\n\n### Wake a Device by Name\n\n```sh\ncurl -X POST http://localhost:8000/api/wake \\\n    -H \"Content-Type: application/json\" \\\n    -H \"X-Auth-Token: supersecret\" \\\n    -d '{\"name\":\"pc\"}'\n```\n\n### Wake a Device by MAC\n\n```sh\ncurl -X POST http://localhost:8000/api/wake \\\n    -H \"Content-Type: application/json\" \\\n    -H \"X-Auth-Token: supersecret\" \\\n    -d '{\"mac\":\"AA:BB:CC:DD:EE:FF\"}'\n```\n\n## Web UI\n\nVisiting `/` serves a simple HTML page with:\n\n- Token input\n- One \"Wake\" button per configured device\n\nPerfect for phone / tablet usage over VPN.\n\n## Kubernetes / k3s Notes\n\nRecommended settings:\n\n- Run with `hostNetwork: true`\n- Expose via ingress or internal Service\n- Store `WOL_TOKEN` in a Secret\n- Map a friendly domain via Pi-hole DNS (e.g., `wol.home.arpa`)\n\n## Project Structure\n\n```text\n.\n├── app\n│   ├── api.py\n│   ├── __init__.py\n│   ├── settings.py\n│   └── wol.py\n├── Dockerfile\n├── LICENSE\n├── pyproject.toml\n├── README.md\n└── uv.lock\n```\n\n## Development\n\n### Local run (with uv)\n\n```sh\nuv sync\nuv run uvicorn app.api:app --host 0.0.0.0 --port 8000\n```\n\n## Security Notes\n\n- Designed for internal / VPN use\n- Token auth prevent accidental or unauthorised wake requests\n- No public exposure recommended\n\n## Contributing\n\nFeel free to contribute to this project by forking this reopsitory and creating a pull request with your changes.\n\n## Issues\n\nIf you encounter any issues of have suggestions for improvements, please open an issue in the repository\n\n## License\n\nThis project is licensed under the [MIT license](https://github.com/Cyrof/RemoteWakeServer/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrof%2Fremotewakeserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyrof%2Fremotewakeserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrof%2Fremotewakeserver/lists"}