Compute Sessions


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

Listing sessions

List the session owned by you with various status filters. The most recently status-changed sessions are listed first. To prevent overloading the server, the result is limited to the first 10 sessions and it provides a separate --all option to paginate further sessions. ps

The ps command is an alias of the following admin session list command. If you have the administrator privilege, you can list sessions owned by other users by adding --access-key option here. admin session list

Both commands offer options to set the status filter as follows. For other options, please consult the output of --help.


Included Session Status

(no option)






Both commands offer options to specify which fields of sessions should be printed as follows.


Included Session Fields

(no option)

Session ID, Owner, Image, Type,

Status, Status Info, Last updated, and Result.


Session ID.


Session ID, Owner, Image, Type,

Status, Status Info, Last updated, Result,

Tag, Created At, Occupied Resource, Used Memory (MiB),

Max Used Memory (MiB), and CPU Using (%).

-f, --format

Specified fields by user.


Fields for -f/--format option can be displayed by specifying comma-separated parameters.

Available parameters for this option are: id, status, status_info, created_at, last_updated, result, image, type, task_id, tag, occupied_slots, used_memory, max_used_memory, cpu_using.

For example: admin session --format id,status,cpu_using

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. 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 ./ file, using the shell command specified in the --exec option. run --rm --exec 'python arg1 arg2' \
           python:3.6-ubuntu18.04 ./

Please note that your run command may hang up for a very long time due to queueing when the cluster resource is not sufficiently available.

To avoid indefinite waiting, you may add --enqueue-only to return immediately after posting the session creation request.


When using --enqueue-only, the codes are NOT executed and relevant options are ignored. This makes the run command to the same of the start command.

Or, you may use --max-wait option to limit the maximum waiting time. If the session starts within the given --max-wait seconds, it works normally, but if not, it returns without code execution like when used --enqueue-only.

To watch what is happening behind the scene until the session starts, try events <sessionID> to receive the lifecycle events such as its scheduling and preparation steps.

Running sessions with accelerators

Use one or more -r options to specify resource requirements when using run and start commands.

For instance, the following command spawns a Python TensorFlow session using a half of virtual GPU device, 4 CPU cores, and 8 GiB of the main memory to execute ./ file inside it. run --rm \
           -r cpu=4 -r mem=8g -r cuda.shares=2 \
           python-tensorflow:1.12-py36 ./

Terminating or cancelling 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 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. rm <sessionID> [<sessionID>...]

If you terminate PENDING sessions which are not scheduled yet, they are cancelled.