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 Flyte instance.

Prerequisites

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

Don’t have a Flyte cluster 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 local \
    --registry ghcr.io/my-org

This creates ./.flyte/config.yaml:

        
    
admin:
  endpoint: dns:///my-org.my-company.com
image:
  builder: local
  registry: ghcr.io/my-org
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.

Set up local Docker

The --builder local setting means container images are built locally on your machine and pushed to a container registry that your Flyte cluster can pull from. You’ll need Docker running and logged into that registry, for example:

docker login ghcr.io

Because you set image.registry in your config above, your Image definitions don’t need a registry; the local build pushes there automatically. (Set registry= on an individual Image only to override it.) See Image building for details.

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 local \
    --registry ghcr.io/my-org \
    --insecure \
    --output my-config.yaml \
    --force

See the CLI reference for all parameters.

admin: Connection details for your 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.
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

Programmatic

CLI

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:

./config.yaml
./.flyte/config.yaml
UCTL_CONFIG environment variable
FLYTECTL_CONFIG environment variable
~/.union/config.yaml
~/.flyte/config.yaml

Programmatic

CLI

        
    
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.

Programmatic

CLI

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.