RESTful shell for your server without shell access

python, rest, utility
pip install py3-rest-shell==0.3


The RESTful shell (with Python3 support)

This is a RESTful shell that gives you command line access to a server that does not provide another means of shell access. If you are limited to an API to interact with your server, this tool may work for you.


  • Shell access to a server that does not offer shell access.
  • Run commands remotely without using the system’s built in authentication system.
  • Not malware. You already have permission to execute code on the server.
  • Interactive shell lets you scroll through history.
  • Authentication and SSL encryption.
  • Readline support.


Installation is easy with pip, but you may need some OpenSSL development header files:

pip install git+


There are two components, the server and the client.

The server is written in Python using Flask and is the application that you upload to your server for execution. Once it’s running, the API will be available at the specified port.

To connect to the API you can use the client, also written in Python. Supply the URL endpoint and you will be prompted to start entering commands.


To start the server, use rest-shell with the server option and supply the URL for your endpoint. You will want to set the TOKEN environment variable for authentication purposes. For example:

TOKEN=hackme rest-shell --server localhost:8080


To connect to the API with the command line client, use rest-shell and supply the URL for your endpoint. You will also need to set the TOKEN environment variable here to match the server, otherwise you won’t get access. For example:

TOKEN=hackme rest-shell localhost:8080
Welcome to the RESTful shell!
[https://trey@localhost:8080] df -h /boot
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       228M   43M  173M  20% /boot
[https://trey@localhost:8080] uptime
23:00:07 up 6 days,  6:16,  6 users,  load average: 0.15, 0.19, 0.14
[https://trey@localhost:8080] ps
  989 pts/2    00:00:00 bash
 5386 pts/2    00:00:00 rest-shell
 6084 pts/2    00:00:00 sh
 6085 pts/2    00:00:00 ps
[https://trey@localhost:8080] python -V 2>&1 | toilet -f smmono9
▗▄▄      ▗  ▐                ▄▄     ▗▄▄▖    ▗▄▄
▐ ▝▌▗ ▗ ▗▟▄ ▐▗▖  ▄▖ ▗▗▖     ▝ ▝▌      ▐▘    ▐    ▗
▐▄▟▘▝▖▞  ▐  ▐▘▐ ▐▘▜ ▐▘▐       ▗▘      ▞     ▝▀▚▖ ▐
▐    ▙▌  ▐  ▐ ▐ ▐ ▐ ▐ ▐      ▗▘      ▗▘        ▌▀▜▀▘
▐    ▜   ▝▄ ▐ ▐ ▝▙▛ ▐ ▐     ▗▙▄▖ ▐   ▞   ▐  ▝▄▟▘ ▐
[https://trey@localhost:8080] exit


Currently only JSON is supported.

Execute command

The /execute location provides the ability to execute a command. A sample request would look like:

    "command": "uname -sr"

A sample response would look like:

    "output": "Linux 3.10-1-amd64\n",
    "status": 0

Headers required are:

  • Content-Type, set to “application/json”
  • X-Auth-Token, set to the value for TOKEN specified on the server

With the endpoint at https://localhost:8080/execute, an example using cURL would look like:

curl -s -k -H 'Content-Type: application/json' -H 'X-Auth-Token: hackme' -d '{"command": "uname -sr"}' https://localhost:8080/execute

An example using HTTPie:

echo '{"command": "uname -sr"}' | http --verify=no https://localhost:8080/execute X-Auth-Token:hackme