Connecting to a cluster

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

Want to try Flyte without installing anything? Try Flyte 2 in your browser.

Prerequisites

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

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

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 \
    --insecure \
    --output my-config.yaml \
    --force
See the CLI reference for all parameters.

admin — Connection details for your Union/Flyte 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.

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:

Next steps

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

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