{"id":15676500,"url":"https://github.com/sahilchaddha/unix-remotecontrol","last_synced_at":"2025-05-07T14:22:16.297Z","repository":{"id":57386664,"uuid":"123221207","full_name":"sahilchaddha/unix-remotecontrol","owner":"sahilchaddha","description":"Remote Control Over HTTP API - Unix Power Commands - Shutdown, Restart etc For Homebridge Apple HomeKit Appliance Protocol (IOT)","archived":false,"fork":false,"pushed_at":"2018-05-15T02:25:56.000Z","size":7999,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-07T14:21:56.526Z","etag":null,"topics":["express","homebridge","homekit","iot","iot-platform","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sahilchaddha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-28T03:04:32.000Z","updated_at":"2024-05-31T08:35:18.000Z","dependencies_parsed_at":"2022-09-11T07:12:14.615Z","dependency_job_id":null,"html_url":"https://github.com/sahilchaddha/unix-remotecontrol","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahilchaddha%2Funix-remotecontrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahilchaddha%2Funix-remotecontrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahilchaddha%2Funix-remotecontrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahilchaddha%2Funix-remotecontrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sahilchaddha","download_url":"https://codeload.github.com/sahilchaddha/unix-remotecontrol/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252892692,"owners_count":21820689,"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":["express","homebridge","homekit","iot","iot-platform","nodejs"],"created_at":"2024-10-03T16:02:20.255Z","updated_at":"2025-05-07T14:22:16.245Z","avatar_url":"https://github.com/sahilchaddha.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unix Remote Control (IOT) \n\n[![NPM](https://nodei.co/npm/unix-remotecontrol.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/unix-remotecontrol/)\n\n\n[![Build Status](https://travis-ci.org/sahilchaddha/unix-remotecontrol.svg?branch=master)](https://travis-ci.org/sahilchaddha/unix-remotecontrol)\n[![npm](https://img.shields.io/npm/dm/unix-remotecontrol.svg)](https://www.npmjs.com/package/unix-remotecontrol)\n[![npm](https://img.shields.io/npm/v/unix-remotecontrol.svg)](https://www.npmjs.com/package/unix-remotecontrol)\n[![GitHub release](https://img.shields.io/github/release/sahilchaddha/unix-remotecontrol.svg)](https://github.com/sahilchaddha/unix-remotecontrol)\n[![GitHub issues](https://img.shields.io/github/issues/sahilchaddha/unix-remotecontrol.svg)](https://github.com/sahilchaddha/unix-remotecontrol)\n[![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/sahilchaddha/unix-remotecontrol.svg)](https://github.com/sahilchaddha/unix-remotecontrol)\n\n\n\n\n\n\nRuns Scripts on Mac/Linux remotely.\n\n## Why :\n\nI was setting up homebridge (iOS HomeKit Accesory Protocol) on my rasberryPi and after hooking up my IR Blaster, RF Transmitter and other wake-on-lan devices. I wanted my always-on OSX Laptop to also be remotely controlled by my iOS Device. So i ended up writing up a small plugin for [Homebridge](https://github.com/nfarina/homebridge) [plugin](https://github.com/sahilchaddha/homebridge-unixcontrol). \n\nI use this to play itunes, search google and bookmark search results, restart my system, get room temperature using MBP in-build Temp Sensor and adjust airconditioning accordingly, monitor my ec-2 instance stats, sync Spotify Playlist etc.\n\nHomebridge Plugin =\u003e [homebridge-unixcontrol](https://github.com/sahilchaddha/homebridge-unixcontrol)\n\n## How it Works :\n\nThis library is directly injected into homebridge with a plugin wrapper =\u003e [homebridge-unixcontrol](https://github.com/sahilchaddha/homebridge-unixcontrol)\n\nThe plugin queries the system using HTTP API and run shell scripts. The shell requires sudo access to shutdown/reboot the system. More commands can be easily be injected. Feel free to PR.\n\nYou can ask Siri to execute commands : \n\n`Hey Siri, Shutdown my laptop`\n\n`Hey Siri, play iTunes Playlist`\n\n`Hey Siri, Good Morning ! // Plays Music, Backups OSX, Search for Google Alerts, Turns Off Air Conditioner`\n\n`Hey Siri, Capture Laptop Webcam`\n\n`Hey Siri, Who's using my laptop`\n\n## Todo :\n\n- [ ] Add Linux Support\n- [ ] Add Windows Support\n- [ ] Refactor With Promises\n- [ ] Replace HTTP API with socket connection.\n- [ ] Implement a working Example\n- [ ] Security Concerns\n\n\n## Installation :\n\n```\n $ npm install -g unix-remotecontrol\n```\n\n### Starting Server :\n\n```\n $ unixremote\n```\n\n### Running Forever\n\n```\n $ npm install -g forever\n $ git clone https://github.com/sahilchaddha/unix-remoteControl.git \u0026\u0026 cd unix-remoteControl\n $ forever start src/server.js\n```\n\n## Configuration :\n\nConfiguration containing sudo password, port number, logLevel \u0026 sessionToken are stored in `environment.js` in root/src.\n\nTo Open Configuration for global module : \n\n```\n $ unixremote --config\n```\n\nSample Configuration :\n\n``` \n//environment.js\nvar env = {\n    port: '3000',\n    pass: 'lol', //sudo password TODO: Secure\n    logLevel: 'info',\n    sessionToken: 'f64f2940-fae4-11e7-8c5f-ef356f279131'\n}\n\nmodule.exports = env\n```\n\n### Config Parameters\n\n\n| Fields             | Description                                           |\n|--------------------|-------------------------------------------------------|\n| port               | Port Number to run HTTP Server.                       |\n| pass               | System Sudo Password                                  |\n| logLevel           | Log Level (debug, info, error)                        |\n| sessionToken       | Random Session Token for API Authentication.          |\n\n\n**NOTE**: `sessionToken` needs to be set as Request Header `token`\n\n\n## Usage :\n\nAfter Running the server, You can request\n\n`localhost:portNumber/commandType/command`\n\ne.g.\n\n\n\n```\nPOST localhost:3000/power/shutdown\n    {\n        \"time\": 10\n    }\n```\n\n\n```\ncurl --header \"token: f64f2940-fae4-11e7-8c5f-ef356f27913\" -X POST localhost:3000/power/logout\n\ncurl --header \"token: f64f2940-fae4-11e7-8c5f-ef356f27913\" \"Content-Type: application/json\" -X POST -d '{\"time\":10}' localhost:3000/power/restart \n\ncurl --header \"token: f64f2940-fae4-11e7-8c5f-ef356f27913\" \"Content-Type: application/json\" -X POST -d '{\"destination\":\"AppleMusic\"}' localhost:3000/music/syncSpotify\n```\n\n## Sample Scripts/Commands : \n\n### Power Command Type \n\nUsage:- \n\n`localhost:3000/power/displaySleep`\n\n```\nPOST localhost:3000/power/restart\n    {\n        \"time\": 10\n    }\n```\n\n| Command             | Method | Description                                           | Params | Sudo |\n|--------------------|---------|-------------------------------------------------------|----------| ----- |\n| /ping      | GET | Pings to get server state (on/off)         | None       | false |\n| /halt           | POST | Shutdowns immediately \u0026 forcibly (Can cause data loss)                          | None      | true |\n| /shutdown              | POST | Shut downs the system                                 | `time` (minutes) : Delays Shutdown in minutes       | true |\n| /restart           | POST | Restarts the system | `time` (minutes) : Delays Shutdown in minutes      | true |\n| /logout         | POST | Logs Out the user (OSX Only)                                  | None      | false |\n| /sleep         | POST | Turns the System to Sleep                       | None       | false |\n| /displaySleep        | POST | Turns the Display to Sleep                      | None       | false |\n| /cancelShutdown        | POST | Cancels Scheduled Shutdown/Restart Task                      | None       | true |\n\n### System Stats Command Type \n\nUsage:- \n\n`localhost:3000/systemStats/temperature`\n\n`localhost:3000/systemStats/ram`\n\n| Command             | Method | Description                                           | Params | Sudo |\n|--------------------|---------|-------------------------------------------------------|----------| ----- |\n| /temperature      | GET | Returns current Temperature of CPU         | None       | false |\n| /cpuLoad           | GET | Returns current CPU Load                          | None      | false |\n| /ram               | GET | Returns current Ram Status                                 | None       | false |\n| /storage           | GET | Returns current Storage Stats | None      | false |\n| /battery         | GET | Returns current Battery Information                                  | None      | false |\n\n### Browser Command Type \n\nUsage:- \n\n`localhost:3000/browser/googleChromeReset `\n\n| Command             | Method | Description                                           | Params | Sudo |\n|--------------------|---------|-------------------------------------------------------|----------| ----- |\n| /googleChromeReset      | POST | Clear all data of google chrome and reset         | None       | false |\n| /safariClearHistory      | POST | Clear histroy of safari        | None       | false |\n\n**NOTE**: For safariClearHistory you will have to add terminal or whatever command line tool you are using should be added in System Preferences -\u003e Security \u0026 Privacy -\u003e Privacy -\u003e Accessibility. When you run this command for the first time there will a prompt to add command line tool in Accessibility.\n\n### Wi-fi Command Type \n\nUsage:- \n\n`localhost:3000/wifi/on `\n\n| Command             | Method | Description                                           | Params | Sudo |\n|--------------------|---------|-------------------------------------------------------|----------| ----- |\n| /status      | GET | Returns Wifi Enabled/Disabled Status (OS X Only)       | None       | false |\n| /on      | POST | Turn on wifi (OS X Only)        | None       | false |\n| /off      | POST | Turn off wifi (OS X Only)       | None       | false |\n| /connect      | POST | Connect to wifi (OS X Only)       | `name`: wifi name, `password`: wifi password       | false |\n\n### Bluetooth Command Type \n\nUsage:- \n\n`localhost:3000/bluetooth/status `\n\n| Command             | Method | Description                                           | Params | Sudo |\n|--------------------|---------|-------------------------------------------------------|----------| ----- |\n| /status      | GET | Returns Bluetooth Enabled/Disabled Status (OS X Only)       | None       | false |\n| /on      | POST | Turn on Bluetooth (OS X Only)        | None       | false |\n| /off      | POST | Turn off Bluetooth (OS X Only)       | None       | false |\n| /showPairingAlert      | POST | Show pairing alert or pair with any BLE enabled device (OS X Only)     |  `deviceName`: Bluetooth name of device with percentage encoding       | false |\n| /toggle        | POST | Toggle device bluetooth connection (OS X Only)     |  `deviceName`: Bluetooth name of device with percentage encoding       | false |\n\n**NOTE**: [blueutil](https://github.com/imsrc21/blueutil) is added as a depedancy for Bluetooth Connections. It will be automatically installed during `npm install`. Its added as postInstall Script in `package.json`. If for some reason installation of blueutil fails, you can manually install blueutil `brew install blueutil`\n\n### System Spy Command Type \n\nUsage:- \n\n`localhost:3000/systemSpy/screenshot`\n\n`localhost:3000/systemSpy/camRecord`\n\n```\nlocalhost:3000/systemSpy/alert\n    {\n        \"message\": \"Heeeyyy !!! Hooooo !!!\"\n    }\n```\n\n```\nlocalhost:3000/systemSpy/notify\n    {\n        \"title\": \"heyyy\",\n        \"message\": \"hooo\"\n    }\n```\n\n| Command             | Method | Description                                           | Params | Sudo |\n|--------------------|---------|-------------------------------------------------------|----------| ----- |\n| /screenshot      | POST | Screenshots Current Screen, Saves \u0026 returns image (OSX Only)         | None       | false |\n| /webcamCapture      | POST | Clicks Camera Still, Saves \u0026 returns image (OSX Only)         | None       | false |\n| /screenRecord           | POST | Starts Screen Recording (OSX Only)                          | `time` (In Minutes): Start recording for specific time.  Here time is optional if you want to run this command forever than do not pass any arguments      | false |\n| /camRecord               | POST | Starts Camera Recording (OSX Only)                                 | `time` (In Minutes): Start recording for specific time.  Here time is optional if you want to run this command forever than do not pass any arguments       | false |\n| /alert           | POST | Shows Alert to User | `message`: Message to Show Alert      | false |\n| /notify           | POST | Shows Notification to User | `title`: Title For Notification, `message`: Message      | false |\n| /isRecording         | GET | Returns Recording Status (OSX Only)                                  | `type` : `screen` or `cam` type of recording      | false |\n\n### Music Command Type \n\nUsage:- \n\n`localhost:3000/music/itunesPlaylist`\n\n```\nlocalhost:3000/music/setVolume\n    {\n        \"volume\": 10\n    }\n```\n\n| Command             | Method | Description                                           | Params | Sudo |\n|--------------------|---------|-------------------------------------------------------|----------| ----- |\n| /youtubePlaylist      | POST | Opens Youtube \u0026 Starts Playing Playlist defined in `environment.js` (OSX Only)         | None       | false |\n| /itunesPlaylist      | POST | Opens iTunes \u0026 Starts Playing Playlist defined in `environment.js` (OSX Only)         | None       | false |\n| /setVolume           | POST | Sets New Volume (OSX Only)                          | `volume`: volume to be set. Should be between 0 to 10      | false |\n| /getVolume               | GET | Returns Current Volume (OSX Only)                                 | None       | false |\n| /mute           | POST | Mutes the System (OSX Only)                          | None      | false |\n| /unmute               | POST | UnMutes the System (OSX Only)                                 | None       | false |\n| /isMuted           | GET | Returns Mute Status (OSX Only)                          | None      | false |\n\n\n### Todo Scripts :\n- [ ] Remote System Backup\n- [ ] Remote System Format (Need extra OSX Device to test. :P )\n\n\n## Writing Custom Scripts :\n\nCloning the Repo : \n\n```\n $ git clone https://github.com/sahilchaddha/unix-remoteControl.git \u0026\u0026 cd unix-remoteControl\n $ node src/server.js\n or\n $ npm start\n```\n\nCreating Your Router :\n\nYou can create your custom router inside `Routes` folder.\n\n```\n//DummyRouter.js\nvar router = require('express').Router() // Create New Router\nvar commandService = require('../Services/CommandService.js')\n\nrouter.get('/hello', function (req, res) {\n  res.send('Hello')\n  // Run Your npm commands\n  // or call Shell Scripts using Command Service\n\n    commandService.execute('dummy', 'sayHello', options, function(){})\n})\n\nmodule.exports = router\n```\n\nAdding your Router to Valid Routes :\n\nAdd your custom router inside `routes.js`\n\n```\nvar powerRouter = require('./Routes/PowerRouter.js')\nvar dummyRouter = require('./Routes/DummyRouter.js')\n\nvar routes = [\n    {\n        url: '/power',\n        routerClass: powerRouter\n    },\n    {\n        url: '/dummy',\n        routerClass: dummyRouter\n    }\n]\n\nmodule.exports = routes\n```\n\nAdding Your Shell Scripts :\n\nYou can use Command Service to execute commands : \n\nTo add Commands, you can inject your commands inside `Commands/commands.js`\n\n```\nvar dummyCommands = {\n    sayHello: {\n        command: ['say', 'hello'],\n        sudo: false // Set as true if command need sudo access\n    }\n}\n\nmodule.exports = {\n    // power: powerCommands,\n    dummy: dummyCommands\n}\n```\n\n\n### Apple Scripts\n\nApple scripts in format `.scpt` are to be injected inside `AppleScripts` folder.\n\nYou can add command inside `commands.js` \n\n```\nvar dummyCommands = {\n    sayHello: {\n        command: ['say', 'hello'],\n        sudo: false // Set as true if command need sudo access\n    },\n    runAppleScript: {\n        command: ['osascript', 'src/Commands/AppleScripts/dummyAS.scpt'],\n        sudo: false\n    }\n}\n\nmodule.exports = {\n    // power: powerCommands,\n    dummy: dummyCommands\n}\n```\n\n\n## Homebridge on Raspberry Pi :\n\n### Homebridge Configuration : \n\nWIP\n\n### On Pi : \n\n```\n$ ssh pi@192.168.1.2 // Your Pi Local Address\n$ npm install -g homebridge\n$ npm install -g homebridge-unixcontrol\n\n// Configure Homebridge config.json\n```\n\n### On Unix System (For Remote Access) : \n\n```\n$ npm install -g unix-remotecontrol\n$ unixremote --config //Setup Your Configuration\n$ unixremote\n```\n\n\n## Credits : \nSahil Chaddha (mail@sahilchaddha.com)\n\nSumit Chudasama (imsrc21@gmail.com)\n\n## Reference :\n\n- [HashinKit](https://github.com/shogo4405/HaishinKit.swift)\n\n- [BlueUtil](https://github.com/toy/blueutil)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsahilchaddha%2Funix-remotecontrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsahilchaddha%2Funix-remotecontrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsahilchaddha%2Funix-remotecontrol/lists"}