Getting started#

In this section, we give a quick introduction to writing and running Union workflows.

Gather your credentials#

After your administrator has onboarded you to Union, you should have the following at hand:

  • Your Union credentials.

  • The URL of your Union instance. We will refer to this as <union-host-url> below.

Log into Union#

Navigate to the web console at <union-host-url> and log in with your credentials. Once you have logged in you should see the Union console. This is where you will be able to see your workflow executions and and manage your projects:

Union console

Set up your Python environment#

Set up a Python virtual environment with conda, venv or a similar tool.

Python 3.8 or higher is required. Python 3.11 is the current recommended version.

Install conda using Miniconda, then run the following to create a new Python environment:

$ conda create -n union-env python=3.11
$ conda activate union-env

Install Python 3.11 from your package manager or from, then run the following to create a virtual environment:

$ python -m venv .venv
$ source .venv/bin/activate

Install the unionai package#

After setting up your virtual environment and activating it, install the unionai Python package:

pip install -U 'unionai[byoc]'
pip install -U "unionai[byoc]"


The [byoc] extra package includes configuration defaults specific to Union BYOC that differ from those needed for Serverless.

This will install:

Set up configuration for the unionai CLI#

To run and register tasks, workflows, and launch plans from your local machine to your Union instance, you will need to create a Union connection configuration file that contains your Union host domain. Your Union host domain is the part of your <union-host-url> after the https://. For example, if your <union-host-url> is, then your Union host domain is We will refer to this as <union-host-domain> below.

Create you configuration file at ~/.unionai/config.yaml as below, with <union-host-domain> substituted appropriately. Note that there are two host values to substitute and the resulting URLs are prefixed with dns:/// (with three slashes):

    host: dns:///<union-host-domain>
    insecure: true
    type: Pkce
  endpoint: dns:///<union-host-domain>
  insecure: true
  authType: Pkce

By default, the unionai CLI will look for a configuration file at ~/.unionai/config.yaml. You can override this behavior to specify a different configuration file by setting the UNIONAI_CONFIG environment variable:

export UNIONAI_CONFIG=~/.my-config-location/my-config.yaml

Alternatively, you can always specify the configuration file on the command line when invoking unionai by using the --config flag:

$ unionai --config ~/.my-config-location/my-config.yaml run my_workflow


If you have previously used Flyte, you may have configuration files left over that will interfere with access to Union BYOC through the unionai CLI tool. Make sure to remove any files in ~/.flyte/ or unset the environment variable FLYTECTL_CONFIG to avoid conflicts.

Create a “Hello, world!” workflow#

To create an example workflow file, copy the following into a file called

from flytekit import task, workflow

def say_hello(name: str) -> str:
    return f"Hello, {name}!"

def hello_world_wf(name: str = 'world') -> str:
    res = say_hello(name=name)
    return res

Tasks and workflows#

The “Hello, world!” code contains a task and a workflow, which are Python functions decorated with the @task and @workflow decorators, respectively. Typically, the corresponding configuration files would be located in the following locations: For more information, see the task and workflow documentation.

Run the workflow locally in Python#

You can run the workflow in your local Python environment with the unionai run command:

$ unionai run hello_world_wf

You should see the following output:

Running Execution on local.
Hello, world!

Since the @workflow function takes an argument called name, you can also pass that in as a command-line argument like this:

$ unionai run hello_world_wf --name Ada

You should see the following output:

Running Execution on local.
Hello, Ada!

Run the workflow remotely on Union#

To run the workflow remotely on Union, add the --remote flag:

$ unionai run --remote hello_world_wf --name "Ada"

The output displays a URL that links to the workflow execution on the Union web console:

[] Go to https://<union-host-url>/org/... to see execution in the console.

Go to the Union console to see the execution: