Skip to content

🏃 Runner

A utility service to manage safe execution of remote scripts / commands. User launches this from commandline and let the utility manage the commands to be executed.

The runner utility runs as a service and provides REST API interface to safely execute remote commands. Multiple runners can be active simultaneously on one computer. The commands are sent via the REST API and are executed on the computer with active runner.

⚠ Thanks for trying out this software. This software is in early stages of development and is not recommended for production use. Each released package will have a working API and matching documentation in this README. However, there will be breaking changes in the API across each release until the package reaches version 1.0.0.

⬇ Install

NPM Registry

The package is available on npmjs.

Install the package with the following command:

1
sudo npm install -g @into-cps-association/runner

Github Registry

The package is available in Github packages registry.

Set the registry and install the package with the following commands

1
2
sudo npm config set @into-cps-association:registry https://npm.pkg.github.com
sudo npm install -g @into-cps-association/runner

The npm install command asks for username and password. The username is your Github username and the password is your Github personal access token. In order for the npm to download the package, your personal access token needs to have read:packages scope.

⚙ Configure

The utility requires config specified in YAML format. The template configuration file is:

1
2
port: 5000
location: 'script' #directory location of scripts

It is suggested that the configuration file be named as runner.yaml and placed in the directory in which the runner microservice is run.

The location refers to the relative location of the scripts directory with respect to the location of runner.yaml file.

However, there is no limitation on either the configuration filename or the location. The path to runner.yaml can either be relative or absolute path. However, the location path is always relative path with respect to the path of runner.yaml file.

🖊 Create Commands

The runner requires commands / scripts to be run. These need to be placed in the location specified in runner.yaml file. The location must be relative to the directory in which the runner microservice is being run.

🚀 Use

Display help.

1
2
3
4
5
6
7
8
$runner -h
Usage: runner [options]

Remote code execution for humans

Options:
  -c --config <string>  runner config file specified in yaml format (default: "runner.yaml")
  -h --help             display help

The config option is not mandatory. If it is not used, runner looks for runner.yaml in the directory from which it is being run. Once launched, the utility runs at the port specified in runner.yaml file.

1
2
3
runner  #use runner.yaml of the present working directory
runner -c FILE-PATH       #absolute or relative path to config file
runner --config FILE-PATH #absolute or relative path to config file

If launched on one computer, you can access the same at http://localhost:<port>.

Access to the service on network is available at http://<ip or hostname>:<port>/.

Application Programming Interface (API)

Three REST API methods are active. The route paths and the responses given for these two sources are:

REST API Route HTTP Method Return Value Comment
localhost:port POST Returns the execution status of command Executes the command provided. Each invocation appends to array of commands executed so far.
localhost:port GET Returns the execution status of the last command sent via POST request.
localhost:port/history GET Returns the array of POST requests received so far.

POST Request to /

Executes a command. The command name given here must exist in location directory.

1
2
3
4
5
6
7
8
POST / HTTP/1.1
Host: foo.com
Content-Type: application/json
Content-Length: 388

{
  "name": "<command-name>"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
Connection: close
Content-Length: 134
Content-Type: application/json; charset=utf-8
Date: Tue, 09 Apr 2024 08:51:11 GMT
Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
X-Powered-By: Express

{
  "status": "success"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
Connection: close
Content-Length: 28
Content-Type: application/json; charset=utf-8
Date: Tue, 09 Apr 2024 08:51:11 GMT
Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
X-Powered-By: Express

{
  "status": "invalid command"
}

GET Request to /

Shows the status of the command last executed.

1
2
3
4
5
6
7
8
GET / HTTP/1.1
Host: foo.com
Content-Type: application/json
Content-Length: 388

{
  "name": "<command-name>"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Connection: close
Content-Length: 134
Content-Type: application/json; charset=utf-8
Date: Tue, 09 Apr 2024 08:51:11 GMT
Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
X-Powered-By: Express

{
  "name": "<command-name>",
  "status": "valid",
  "logs": {
    "stdout": "<output log of command>",
    "stderr": "<error log of command>"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Connection: close
Content-Length: 70
Content-Type: application/json; charset=utf-8
Date: Tue, 09 Apr 2024 08:51:11 GMT
Etag: W/"86-ja15r8P5HJu72JcROfBTV4sAn2I"
X-Powered-By: Express

{
  "name": "<command-name",
  "status": "invalid",
  "logs": {
    "stdout": "",
    "stderr": ""
  }
}

GET Request to /history

Returns the array of POST requests received so far. Both valid and invalid commands are recorded in the history.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[
  {
    "name": "valid command"
  },
  {
    "name": "valid command"
  },
  {
    "name": "invalid command"
  }
]