# Local setup

In this section we will set up your local environment so that you can start building and deploying Union.ai workflows from your local machine.

## Install `uv`

First, [install `uv`](https://docs.astral.sh/uv/#getting-started).

> [!NOTE] Using `uv` as best practice
> The `uv` tool is our [recommended package and project manager](https://docs.astral.sh/uv/).
> It replaces `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more.
>
> You can, of course, use other tools,
> but all discussion in these pages will use `uv`,
> so you will have to adapt the directions as appropriate.

## Ensure the correct version of Python is installed

Union requires Python `>=3.9,<3.13`.
We recommend using `3.12`.
You can install it with:

```shell
$ uv python install 3.12
```

> [!NOTE] Uninstall higher versions of Python
> When installing Python packages "as tools" (as we do below with the `union`),
> `uv` will default to the latest version of Python available on your system.
> If you have a version `>=3.13` installed, you will need to uninstall it since `union` requires `>=3.9,<3.13`.

## Install the `union` CLI

Once `uv` is installed, use it to install the `union` CLI by installing the `union` Python package:

```shell
$ uv tool install union
```

This will make the `union` CLI globally available on your system.

> [!NOTE] Add the installation location to your PATH
> `uv` installs tools in `~/.local/bin` by default.
> Make sure this location is in your `PATH`, so you can run the `union` command from anywhere.
> `uv` provides a convenience command to do this: `uv tool update-shell`.
>
> Note that later in this guide we will be running the `union` CLI to run your workflows.
> In those cases you will be running `union` within the Python virtual environment of your workflow project.
> You will not be using this globally installed instance of `union`.
> This instance of `union` is only used during the configuration step, below, when no projects yet exist.

## Configure the connection to your cluster

Next, you need to create a configuration file that contains your Union.ai connection information:

```shell
$ union create login --host <union-host-url>
```

`<union-host-url>` is the URL of your Union.ai instance, mentioned in [Getting started](https://www.union.ai/docs/v1/union/user-guide/getting-started/local-setup/page.md#gather-your-credentials).

This will create the `~/.union/config.yaml` with the configuration information to connect to your Union.ai instance.

> [!NOTE]
> These directions apply to Union.ai BYOC and Self-managed, where you connect to your own dedicated Union.ai instance.

See [Running in a local cluster](https://www.union.ai/docs/v1/union/user-guide/getting-started/development-cycle/running-in-a-local-cluster) for more details on the format of the `yaml` file.
<!-- TODO: Fix this target page to have a more generic title (it applies to all clusters) and fix its content -->

By default, the Union CLI will look for a configuration file at `~/.union/config.yaml`. (See [Union CLI](https://www.union.ai/docs/v1/union/user-guide/api-reference/union-cli) for more details.)
You can override this behavior to specify a different configuration file by setting the `UNION_CONFIG` environment variable:

```shell
$ export UNION_CONFIG=~/.my-config-location/my-config.yaml
```

Alternatively, you can always specify the configuration file on the command line when invoking `union` by using the `--config` flag.
For example:

```shell
$ union --config ~/.my-config-location/my-config.yaml run my_script.py my_workflow
```

> [!WARNING]
> If you have previously used Union.ai, you may have configuration files left over that will interfere with
> access to Union.ai Serverless through the Union CLI tool.
> Make sure to remove any files in `~/.unionai/` or `~/.union/` and unset the environment
> variables `UNIONAI_CONFIG` and `UNION_CONFIG` to avoid conflicts.

See [Running in a local cluster](https://www.union.ai/docs/v1/union/user-guide/getting-started/development-cycle/running-in-a-local-cluster) for more details on
the format of the `yaml` file.
<!-- TODO: Fix this target page to have a more generic title (it applies to all clusters) and fix its content -->

## Check your CLI configuration

To check your CLI configuration, run:

```shell
$ union info
```

You should get a response like this:

```shell
$ union info
╭────────────────────────────────────────────────────────── Union.ai CLI Info ─────────────────────────────────────────────────────────────╮
│                                                                                                                                       │
│ union is the CLI to interact with Union.ai. Use the CLI to register, create and track task and workflow executions locally and remotely. │
│                                                                                                                                       │
│ Union.ai Version    : 0.1.132                                                                                                            │
│ Flytekit Version : 1.14.3                                                                                                             │
│ Union.ai Endpoint   : <union-host-url>                                                                                                   │
│ Config Source    : <path-to-config> file                                                                                              │
│                                                                                                                                       │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

For more details on connection configuration see [Authentication](https://www.union.ai/docs/v1/union/user-guide/getting-started/development-cycle/authentication).

---
**Source**: https://github.com/unionai/unionai-docs/blob/main/content/user-guide/getting-started/local-setup.md
**HTML**: https://www.union.ai/docs/v1/union/user-guide/getting-started/local-setup/