Backend.AI Client Library for Python
Branch: master
Clone or download
achimnol Send heartbeat pings for every 30 seconds
* To keep the sessions with app service connected.
Latest commit 274c324 Feb 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
setup.cfg Update flake8 and coding style compliance Nov 5, 2018


Backend.AI Client

PyPI version Python Versions SDK Documentation Build Status (Linux) Build Status (Windows) Code Coverage

The official API client library for Backend.AI


You should set the access key and secret key as environment variables to use the API. Grab your keypair from or your cluster admin.

On Linux/macOS, create a shell script as and run it before using the command:

export BACKEND_ENDPOINT=https://my-precious-cluster

On Windows, create a batch file as my-backend-ai.bat and run it before using the command:

chcp 65001
set BACKEND_ENDPOINT=https://my-precious-cluster

Note that it switches to the UTF-8 codepage for correct display of special characters used in the console logs.

Command-line Interface command is the entry point of all sub commands. (Alternatively you can use a verbosely long version: python -m ai.backend.client.cli)

Highlight: run command

To run the code specified in the command line directly, use -c option to pass the code string (like a shell).

$ run python -c "print('hello world')"
∙ Client session token: d3694dda6e5a9f1e5c718e07bba291a9
✔ Kernel (ID: zuF1OzMIhFknyjUl7Apbvg) is ready.
hello world

You can even run a C code on-the-fly. (Note that we put a dollar sign before the single-quoted code argument so that the shell to interpret '\n' as actual newlines.)

$ run c -c $'#include <stdio.h>\nint main() {printf("hello world\\n");}'
∙ Client session token: abc06ee5e03fce60c51148c6d2dd6126
✔ Kernel (ID: d1YXvee-uAJTx4AKYyeksA) is ready.
hello world

For larger programs, you may upload multiple files and then build & execute them. The below is a simple example to run a sample C program.

$ git clone c-example
Cloning into 'c-example'...
Unpacking objects: 100% (5/5), done.
$ cd c-example
$ run c main.c mylib.c mylib.h
∙ Client session token: 1c352a572bc751a81d1f812186093c47
✔ Kernel (ID: kJ6CgWR7Tz3_v2WsDHOwLQ) is ready.
✔ Uploading done.
✔ Build finished.
myvalue is 42
your name? LABLUP
hello, LABLUP!

Please refer the --help manual provided by the run command.

You may use a shortcut command lcc and lpython instead of typing the full Python module path like:

$ lcc main.c mylib.c mylib.h

Since the client version 1.1.5, the sessions are no longer automatically cleaned up. To do that, add --rm option to the run command, like Docker CLI.

Highlight: ps and terminate command

You can see the list of currently running sessions using your API keypair.

$ ps
Session ID    Lang/runtime              Tag    Created At                        Terminated At    Status      CPU Cores    CPU Used (ms)    Total Memory (MiB)    Used Memory (MiB)    GPU Cores
------------  ------------------------  -----  --------------------------------  ---------------  --------  -----------  ---------------  --------------------  -------------------  -----------
88ee10a027    lablup/python:3.6-ubuntu         2018-12-11T03:53:14.802206+00:00                   RUNNING             1            16314                  1024                 39.2            0
fce7830826    lablup/python:3.6-ubuntu         2018-12-11T03:50:10.150740+00:00                   RUNNING             1            15391                  1024                 39.2            0

If you set -t option in the run command, it will be used as the session ID—you may use it to assign a human-readable, easy-to-type alias for your sessions. These session IDs can be reused after the current session using the same ID terminates.

To terminate a session, you can use terminate or rm command.

$ terminate 5baafb2136029228ca9d873e1f2b4f6a
✔ Done.

Highlight: proxy command

To use API development tools such as GraphiQL for the admin API, run an insecure local API proxy. This will attach all the necessary authorization headers to your vanilla HTTP API requests.

$ proxy
∙ Starting an insecure API proxy at http://localhost:8084

More commands?

Please run --help to see more commands.

Troubleshooting (FAQ)

  • There are error reports related to simplejson with Anaconda on Windows. This package no longer depends on simplejson since v1.0.5, so you may uninstall it safely since Python 3.5+ offers almost identical json module in the standard library.

    If you really need to keep the simplejson package, uninstall the existing simplejson package manually and try reinstallation of it by downloading a pre-built binary wheel from here.