koa-shell v1.0.0
koa-shell
koa-shell is a configurable REST-based web server used to execute shell commands, bundled with a web application for convenience.
This can be used to remotely send commands to a computer running on the local network, e.g. one used to manage a smart home network or host a network drive. This can be done through the REST API directly or through the bundled web application.
koa-shell is intended to only be used from within the the local network. I would not recommend exposing this server to the Internet without additional security layers.
Usage
Install koa-shell with either of the following, depending on your preferred package manager:
yarn global add koa-shell
npm install --global koa-shell
Then use it like the following:
$ koa-shell --help
Usage: koa-shell [config.json path (default: config.json)]
$ cd ~/desired/config/json/directory
$ echo '{"name":"My Server","port":80,"commands":['\
> '{"id":"ping","description":"PONG","script":"echo PONG"},'\
> '{"id":"lights-on","description":"Turn on the lights","script":"lighton"}'\
> ']}' > config.json
$ koa-shell
Listening on port 80
$ # ...then in another terminal
$ curl -X POST http://localhost/api/commands/ping
{"success":true,"output":"PONG"}
Configuration
name
- Name of the server. Used for the web application's title.port
- Port to host the server on.commands
- Array of available commands to execute.id
- Unique identifier for the command. This is can only contain alphanumeric characters, hyphens, and underscores.description
- Text describing what this command achieves.script
- The script to be executed on the host.
REST Endpoints
GET /
Loads the web page shown in the screenshot above. This can be used from anything with a modern web browser, including mobile devices.
GET /api/config
Gets the config.json which is currently used by the server.
$ curl http://localhost/api/config
{"name":"My Server","port":80,"commands":[{"id":"ping","description":"PONG","scr
ipt":"echo PONG"},{"id":"lights-on","description":"Turns on the lights","script"
:"some-script"}]}
GET /api/commands
Gets information on all commands which can be run on the server.
$ curl http://localhost/api/commands
[{"id":"ping","description":"PONG","script":"echo PONG"},{"id":"lights-on","desc
ription":"Turns on the lights","script":"some-script"}]
GET /api/commands/{id}
Gets information on the command with the provided id.
$ curl http://localhost/api/commands/ping
{"id":"ping","description":"PONG","script":"echo PONG"}
POST /api/commands/{id}
Executes the command with the provided id.
$ curl -X POST http://localhost/api/commands/ping
{"success":true,"output":"PONG"}
Notes
- koa-shell can be imported as a library.
- You may want to use a process manager such as
runit
to manage the server.
5 years ago