Please consult the detailed usage in the help of each command (use -h or --help argument to display the manual).

Listing currently running sessions

backend.ai ps

This command is actually an alias of the following command:

backend.ai admin sessions

Running simple sessions

The following command spawns a Python session and executes the code passed as -c argument immediately. --rm option states that the client automatically terminates the session after execution finishes.

backend.ai run --rm -c 'print("hello world")' python:3.6-ubuntu18.04


By default, you need to specify language with full version tag like python:3.6-ubuntu18.04. Depending on the Backend.AI admin’s language alias settings, this can be shortened just as python. If you want to know defined language aliases, contact the admin of Backend.AI server.

The following command spawns a Python session and executes the code passed as ./myscript.py file, using the shell command specified in the --exec option.

backend.ai run --rm --exec 'python myscript.py arg1 arg2' \
           python:3.6-ubuntu18.04 ./myscript.py

Running sessions with accelerators

The following command spawns a Python TensorFlow session using a half of virtual GPU device and executes ./mygpucode.py file inside it.

backend.ai run --rm -r gpu=0.5 \
           python-tensorflow:1.12-py36 ./mygpucode.py

Terminating running sessions

Without --rm option, your session remains alive for a configured amount of idle timeout (default is 30 minutes). You can see such sessions using the backend.ai ps command. Use the following command to manually terminate them via their session IDs. You may specifcy multiple session IDs to terminate them at once.

backend.ai rm <sessionID>

Starting a session and connecting to its Jupyter Notebook

The following command first spawns a Python session named “mysession” without running any code immediately, and then executes a local proxy which connects to the “jupyter” service running inside the session via the local TCP port 9900. The start command shows application services provided by the created compute session so that you can choose one in the subsequent app command.

backend.ai start -t mysession python
backend.ai app -p 9900 mysession jupyter

Once executed, the app command waits for the user to open the displayed address using appropriate application. For the jupyter service, use your favorite web browser just like the way you use Jupyter Notebooks. To stop the app command, press Ctrl+C or send the SIGINT signal.

Running sessions with vfolders

The following command creates a virtual folder named “mydata1”, and then uploads ./bigdata.csv file into it.

backend.ai vfolder create mydata1
backend.ai vfolder upload mydata1 ./bigdata.csv

The following command spawns a Python session where the virtual folder “mydata1” is mounted. The execution options are omitted in this example. Then, it downloads ./bigresult.txt file (generated by your code) from the “mydata1” virtual folder.

backend.ai run --rm -m mydata1 python:3.6-ubuntu18.04 ...
backend.ai vfolder download mydata1 ./bigresult.txt

In your code, you may access the virtual folder via /home/work/mydata1 (where the default current working directory is /home/work) just like a normal directory.

Running parallel experiment sessions