Skip to main content

Quick start

BatchX images are implemented as Docker images with additional requirements. In this example, you will import an already-built image into your environment from Docker Hub.

Install the CLI

As a preliminary step you will need to install the CLI if you haven't done it before.

Clone image

In this first step will get the image batchx@tutorial/hello-world (BatchX coordinates) into your environment.

Use the bx clone command to import the image as follows:

bx clone batchx@tutorial/hello-world

View image details

Once imported you can see the image listed in the image repository of your environment. Use the bx images command to list the images of your environment. You should obtain an output similar to the one below:

$ bx images
batchx@tutorial/hello-world:1.0.3 8 months ago 27.5 MB 0.00 $ BatchX Hello World tutorial

You can also, see the images details by running the bx imagecommand:

$ bx image batchx@tutorial/hello-world:1.0.3
Coordinates: batchx@tutorial/hello-world:1.0.3
Tags: tutorial
Author: BatchX
Imported on: Sun Jun 27 18:09:18 CEST 2021
Imported by: david
Minimum memory: 1.0 GB
GPUs: Not allowed
Image size: 27.5 MB
Versions: [1.0.3, 1.0.2, 1.0.1]
Perform a simple BatchX `hello world` execution.

# Context
This is one of BatchX [tutorial images](, intended for first time users who want to run their very first job in BatchX or those who are in the process of learning how to implement their own BatchX image.

# File Formats
### Inputs
To run this image the user has to provide his name as a `String` for the `yourName` input.

### Outputs
Once the image runs successfully it will return an output file `responseFile` with the following content:

Hello <your_name>. Welcome to BatchX!

# Example

### Submit job

bx submit batchx@tutorial/hello-world:1.0.3 '{"yourName":"Rocky Balboa"}'

# Links
- **BatchX Tutorials:**

"$schema": "",
"type": "object",
"additionalProperties": false,
"properties": {
"yourName": {
"type": "string",
"required": true,
"description": "Your name."
"$schema": "",
"type": "object",
"additionalProperties": false,
"properties": {
"responseFile": {
"required": true,
"type": "string",
"format": "file",
"description": "Hello World response file."

Run a job

You can now use bx run to run the image in the BatchX infrastructure.

Let's first try with an empty input to see what happens:

$ bx run batchx@tutorial/hello-world:1.0.3 '{}'
[batchx] [2020/04/28 18:50:42] Submitting job...
[batchx] [2020/04/28 18:50:42] Error INVALID_ARGUMENT: Input validation failed: [object has missing required properties (["yourName"])]

As you can see the input validation is failing, because the yourName field is marked as required in the input schema of the image manifest.

Let's run again with a proper input message:

$ bx run batchx@tutorial/hello-world:1.0.3 '{"yourName":"Michael Jordan"}'

Logs should start showing in your screen as soon as the job is submitted. These logs provide information of the job id, transitions between execution states and logs generated by the running container.

$ bx run tutorial/hello-world:1.0.0 '{"yourName":"Michael Jordan"}'
[batchx] [INFO] [2020/03/09 17:37:16] Submitting job...
[batchx] [INFO] [2020/03/09 17:37:18] Job submitted with id 1
[batchx] [INFO] [2020/03/09 17:37:18] Attaching to job 1
[batchx] [INFO] [2020/03/09 17:37:19] Job status: SUBMITTED
[batchx] [INFO] [2020/03/09 17:41:18] Job status: STARTING
[batchx] [INFO] [2020/03/09 17:41:18] Job status: DOWNLOADING_INPUT
[batchx] [INFO] [2020/03/09 17:41:19] Job status: RUNNING
[tutorial/hello-world:1.0.0] [2020/03/09 17:41:22] Environment:
[tutorial/hello-world:1.0.0] [2020/03/09 17:41:22] environ({'HOSTNAME': 'batchx-container', 'PYTHON_PIP_VERSION': '20.0.2', 'HOME': '/root', 'GPG_KEY': 'E3FF2839C048B25C084DEBE9B26995E310250568', 'PYTHON_GET_PIP_URL': '', 'PATH': '/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'BX_MEMORY': '1000', 'LANG': 'C.UTF-8', 'BX_GPUS': '0', 'PYTHON_VERSION': '3.8.1', 'BX_VCPUS': '1', 'PWD': '/batchx', 'PYTHON_GET_PIP_SHA256': '421ac1d44c0cf9730a088e337867d974b91bdce4ea2636099275071878cc189e'})
[batchx] [INFO] [2020/03/09 17:41:30] Job status: UPLOADING_OUTPUT
[batchx] [INFO] [2020/03/09 17:41:31] Job status: SUCCEEDED


If the compute environment had no previous activity the job might take a few minutes to start.

Inspect results

Each job generates a folder under /jobs in your BatchX file-system, which is persisted in the BatchX cloud. You can inspect its contents by running the bx treecommand:

$ bx tree -i jobs/1
├── [32 B] image.txt
├── input
│ ├── [29 B] input.json
│ └── [29 B] original-input.json
└── output
├── [60 B] output.json
└── response
└── [41 B] response.txt

The image we are using for this example writes its output to a file named response.txt. The last line of the log shows where this output was created. Use bx cat to inspect the contents of this file:

$ bx cat jobs/1/output/response/response.txt
Hello Michael Jordan. Welcome to BatchX!

Congratulations! You have successfully configured your BatchX account and executed a job.

Next steps

Now, you can dive deeper into the documentation:


or try more advanced tutorials: