Skip to content

Getting started with Babylon 5

In this guide you'll learn how to install Babylon 5, run Babylon commands, and experiment with the tool.

Get Babylon from source

Requirements

  • 🐍 Python 3.10+
  • 📦 Pip 22.2+
  • 🌱 Git (latest version)

We will go through the process of getting a version of Babylon before the installation.

Get sources from git

You can download the latest version of Babylon using git clone command

Latest Version

git clone git@github.com:Cosmo-Tech/Babylon.git babylon
cd babylon

Get the specific version from git

If you want a specific version of Babylon (e.g. 3.0.0)

Specific Version

git clone -b 3.0.0 git@github.com:Cosmo-Tech/Babylon.git babylon
cd babylon

Install Babylon

You can install Babylon globally on your system:

Example

python3 -m venv ~/babylonenv
source ~/babylonenv/bin/activate
pip install .

Alternatively, follow these steps if you want to install Babylon in development mode:

Example

python3 -m venv ~/babylonenv
source ~/babylonenv/bin/activate
pip install -e .

Now that you have a fully functional installation of Babylon, you can check the next steps and learn how to start running commands.

Setup Babylon

Babylon use a Vault service as its source of configuration and provides a group of commands that can be used.

The first thing to do in order to check if Babylon is working properly: 

babylon --help

Environment Variable

The Vault service requires multiple environment variables before interacting with Babylon CLI. Contact your Babylon admin to get your service URI and token values.

Important

You can retrieve those values directly from the cluster. See 👉 Retrieve Vault URL and Token.

Set the following environment variables with the proper values:

Example

export BABYLON_ORG_NAME="vault_org_name" # cosmotech
export BABYLON_TOKEN="vault_root_token"  # hvs.CLxxxxxxxxxxxxxxx
export BABYLON_SERVICE="vault_url"       # https://example.api.cosmotech.com

Configuration

At this point, you need to define three variables to run Babylon commands.

Variable Description Example
context_id Project name (string of your choice, no special characters) project1
platform_id Platform ID (e.g., dev, staging, prod) dev
state_id State name (string of your choice, no special characters) state1

⚠️ Variable Constraints

  • context_id and state_id can be any string of your choice, but they must contain no special characters.

  • If you are on Linux, you can generate a new UUID with uuidgen:

    sudo apt update
sudo apt install uuid-runtime -y
# run uuidgen command 
uuidgen | cut -c1-8
# Example output:
0475231d-3c7c-4505-af38-558041240d3d

  • platform_id represents the platform identifier (e.g., dev, staging, ...).
    ⚠️ It must be the same platform_id you used when initializing the Vault configuration.

To initialize Babylon with these values, run:

babylon namespace use -c <context_id> -p <platform_id> -s <state_id>

Generated Configuration

  • This command creates a file called namespace.yaml
  • Location: ~/.config/cosmotech/babylon/namespace.yaml
  • It contains the current context for your deployment.

What’s New in Babylon v5

New namespace commands

Running the following command displays the updated namespace commands:

Example

> babylon namespace --help
Usage: babylon namespace [OPTIONS] COMMAND [ARGS]...

  Babylon namespace

Options:
  --help  Show this message and exit.

Commands:
  get-contexts  Display the currently active namespace
  get-states    Display all states in your local machine
  use           Switch to a specific namespace or create a new one

Using these commands, you can check the currently active namespace.
Additionally, with get-states, you can list all states available on our local machine. Here are some examples:

Example

> babylon namespace get-contexts  
CURRENT  CONTEXT                            TENANT        STATE ID                              
*        sphinx-dev  sphinx  1184d4e3-b9de-4c10-a8f0-db8101e4c1e0 

# or use get-states

> babylon namespace get-states 
INFO   2025-10-23 22:27:31,230 |  state.dev.sphinx.c9b011db-93d9-42f2-a603-8766ffee5aee.yaml
INFO   2025-10-23 22:27:31,232 |  state.prod.sphinx.d4ab0004-a10c-4b98-8fb0-f4176725e0db.yaml
INFO   2025-10-23 22:27:31,233 |  state.staging.sphinx.9646a17d-4b87-445f-adee-980ac8fd912h.yaml

Keycloak Authentication

Keycloak Auth

  • Starting with vesion 5, Babylon uses Keycloak as the authentication system to authenticate with the API and execute commands to create a Cosmotech API object.
  • A new client, cosmotech-babylon-client, is created in Keycloak for this purpose.

New babylon init commnad

After setting the context with the namespace use command you can now easily initialize your project with a basic structure using the babylon init command.
Here’s an example:

Examples

> babylon init --help
Usage: babylon init [OPTIONS]

Create a Babylon project structure using YAML templates.

Options:
--project-folder TEXT  Name of the project folder to create (default:'project').
--variables-file TEXT  Name of the variables file (default:'variables.yaml').
--help  Show this message and exit.

 > babylon init
 INFO     2025-10-24 09:54:53,853 | 
        [babylon] Project successfully initialized at: ~/CosmoTech/DevOps/babylon_v5_dir/test-babylon/project

  .
  ├── babylon.error
  ├── babylon.log
  ├── project
  │   ├── Dataset.yaml
  │   ├── Organization.yaml
  │   ├── Runner.yaml
  │   ├── Solution.yaml
  │   └── Workspace.yaml
  └── variables.yaml

Now, you can get started with running Babylon commands.
All the required YAML files for the resources you need to deploy in v5 are provided as templates.
You can customize and modify them based on your specific needs.

New group for handling runner and run objects

Important

In v5, there is no longer a Connector object, and Scenario / ScenarioRun have been replaced by Runner and Run. For more information refer to the Cosmo Tech platform release notes.

Meta About Endpoint

You can now see which API version you are using with the following command:

about

babylon api about

{
  "version": {
    "full": "5.0.0-beta5-7ebc87cb",
    "release": "5.0.0-beta5",
    "major": 5,
    "minor": 0,
    "patch": 0,
    "label": "beta5",
    "build": "7ebc87cb"
  }
}

Commands for Testing

For more details on how to test, see 👉 Examples.

Commands

babylon apply --organization project/  

babylon apply --solution project/

babylon apply --workspace project/ 

babylon apply --runner project/

Note

You can use the --var-file option to specify a particular variables.yaml file.