Skip to main content


The Shell Agent Component allows you to invoke individual shell commands on your robot remotely, and also to interact with your robot through a secure remote shell session (refer to Remote Shell Access).


The Shell Agent Component needs Agent Version 1.6+


To use the Shell component, your agent will need a section in its agent-settings.json file which enables the shell component, as shown below. For more information on how to configure the agent components, see Agent Configuration.

"components": [
"enabled": true,
"id": "shell",
"settings": {
"logLevel": 4

The shell component understands the following configuration parameters. Generally, you should not need to modify these settings:

enabledWhether to enable the shell component or not.false
nameHow this instance of the shell plugin should be named. In order for the remote shell feature of the Portal to work, there must be an instance named "shell", so changing this isn't recommended."shell"
logLevelThe logging verbosity: 1 - very quiet, 6 - very talkative.4
enableInteractiveShellsWhether to enable support for the remote shell feature in the portal while the component is enabled. This can be disabled separately to help limit access to your robot.true
shellSessionCommandThe command which the agent runs to begin a new interactive shell session.Platform dependent. On Linux: /usr/bin/env bash -c "read -p \"$HOSTNAME login: \" username ; su -l $username ; true"
serviceCommandTemplateA template which the agent applies to commands which are individually run using run() service. This ensures that commands you enter run in a convenient environment.Platform dependent. On Linux: /usr/bin/env bash -c "cd / ; ${$cmd}"
serviceCommandTemplateTimeoutBecause the serviceCommandTemplate can potentially be used to execute arbitrary JavaScript, a timeout can be applied to the templating operation."250ms"

Data Model

The shell component makes available a single Service named run, which can be invoked to execute a single shell command on the robot:

The service request takes the shell command to be executed as a string, and returns a single string response containing the data which the shell command printed to stdout. Long running commands will not output any response data until after the shell command has exited.

The requested command is templated prior to execution; this makes the service more convenient, because commands are executed in a consistent environment. By default on Linux hosts, the specified command will be run in the root (/) directory on the host.


The entered shell command will be executed as the rocos-agent user; make sure you consider the permissions the command will be run with.