Run on a remote cluster

This guide covers setting up your local development environment and configuring the flyte CLI and SDK to connect to your Union.ai instance.

Prerequisites

  • Python 3.10+
  • uv: A fast Python package installer. See the uv installation guide.
  • Access to a Union.ai instance (URL and a project where you can run workflows)

Don’t have a Union.ai instance yet? See Platform deployment to stand one up, or use the Devbox to run a local cluster in Docker.

Install the flyte package

Create a virtual environment and install the flyte package:

uv venv
source .venv/bin/activate
uv pip install flyte

On Windows, use .venv\Scripts\activate instead.

Verify installation:

flyte --version

Configuration file

As we did in Quickstart, use flyte create config to create a configuration file:

flyte create config \
    --endpoint my-org.my-company.com \
    --domain development \
    --project my-project \
    --builder remote

This creates ./.flyte/config.yaml:

admin:
  endpoint: dns:///my-org.my-company.com
image:
  builder: remote
task:
  org: my-org
  domain: development
  project: my-project

The registry (--registry, the image.registry config entry, or the FLYTE_IMAGE_REGISTRY environment variable) sets where locally-built images are pushed. It applies whenever the builder is local: always on Flyte OSS, and on Union if you opt out of remote builds. With --builder remote (the Union default) images are built on the cluster, so no registry is required, which is why the Union example above omits it. Setting the registry from config requires flyte 2.5.9 or later.

Create a custom config file with all available options:

flyte create config \
    --endpoint my-org.my-company.com \
    --org my-org \
    --domain development \
    --project my-project \
    --builder remote \
    --registry ghcr.io/my-org \
    --insecure \
    --output my-config.yaml \
    --force
See the CLI reference for all parameters.

admin: Connection details for your Union.ai instance.

  • endpoint: URL with dns:/// prefix. If your UI is at https://my-org.my-company.com, use dns:///my-org.my-company.com.
  • insecure: Set to true only for local instances without TLS.

image: Docker image building configuration.

  • builder: How container images are built.
    • remote (Union): Images built on Union’s infrastructure.
    • local (Flyte OSS): Images built on your machine. Requires Docker. See Image building.
  • registry: Optional registry prefix to use for image builds. This is helpful when you want the SDK to push or pull images from a custom registry without changing your code. You can also set it with the FLYTE_IMAGE_REGISTRY environment variable.

task: Default settings for task execution.

  • org: Organization name (usually matches the first part of your endpoint URL).
  • domain: Environment separation (development, staging, production).
  • project: Default project for deployments. Must already exist on your instance. See Projects and domains for how to create projects.

Using the configuration

You can reference your config file explicitly or let the SDK find it automatically.

Explicit configuration

ProgrammaticCLI

Initialize with flyte.init_from_config:

flyte.init_from_config("my-config.yaml")
run = flyte.run(main)

Use --config or -c:

flyte --config my-config.yaml run hello.py main
flyte -c my-config.yaml run hello.py main

Without an explicit path, the SDK searches these locations in order:

  1. ./config.yaml
  2. ./.flyte/config.yaml
  3. UCTL_CONFIG environment variable
  4. FLYTECTL_CONFIG environment variable
  5. ~/.union/config.yaml
  6. ~/.flyte/config.yaml
ProgrammaticCLI 
flyte.init_from_config()
 
flyte run hello.py main

Check current configuration 

flyte get config

Output:

CLIConfig(
    Config(
        platform=PlatformConfig(endpoint='dns:///my-org.my-company.com', scopes=[]),
        task=TaskConfig(org='my-org', project='my-project', domain='development'),
        source=PosixPath('/Users/me/.flyte/config.yaml')
    ),
    ...
)

Inline configuration

Skip the config file entirely by passing parameters directly.

ProgrammaticCLI

Use flyte.init:

flyte.init(
    endpoint="dns:///my-org.my-company.com",
    org="my-org",
    project="my-project",
    domain="development",
)

Some parameters go after flyte, others after the subcommand:

flyte \
    --endpoint my-org.my-company.com \
    --org my-org \
    run \
    --domain development \
    --project my-project \
    hello.py \
    main

See the CLI reference for details.

See related methods:

  • flyte.init_from_api_key
  • flyte.init_from_config
  • flyte.init_in_cluster
  • flyte.init_passthrough

Next steps

With your environment fully configured, you’re ready to build:

  • Core concepts: Understand TaskEnvironments, tasks, runs, and actions through working examples.