# 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.

<!--
Hidden until the in-browser demo is repaired. The linked demo
(https://flyte2intro.apps.demo.hosted.unionai.cloud/) is currently unreachable.
To restore: re-add a note callout reading "Want to try Flyte without installing
anything? Try Flyte 2 in your browser" linking to the demo URL once it is live.
-->

## Prerequisites

- **Python 3.10+**
- **`uv`**: A fast Python package installer. See the [`uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/).
- Access to a Flyte instance (URL and a project where you can run workflows)

> [!NOTE]
> Don't have a Flyte cluster yet? See [Platform deployment](https://www.union.ai/docs/v2/flyte/user-guide/oss-deployment/_index)
> to stand one up, or use the [Devbox](https://www.union.ai/docs/v2/flyte/user-guide/run-modes/running-remote/running-devbox) to run a local cluster in Docker.

## Install the flyte package

Create a virtual environment and install the `flyte` package:

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

> [!NOTE]
> On Windows, use `.venv\Scripts\activate` instead.

Verify installation:

```bash
flyte --version
```

## Configuration file

As we did in [Quickstart](https://www.union.ai/docs/v2/flyte/user-guide/run-modes/quickstart), use `flyte create config` to create a configuration file:

```bash
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`:

```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
```

> [!NOTE]
> 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](https://www.union.ai/docs/v2/flyte/user-guide/run-modes/task-configuration/container-images) 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:

```bash
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](https://www.union.ai/docs/v2/flyte/user-guide/run-modes/task-configuration/container-images#image-building) for details.

<details>
<summary>Full example with all options</summary>

Create a custom config file with all available options:

```bash
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](https://www.union.ai/docs/v2/flyte/user-guide/api-reference/flyte-cli#flyte-create-config) for all parameters.

</details>

<details>
<summary>Config properties explained</summary>

**`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](https://www.union.ai/docs/v2/flyte/user-guide/run-modes/task-configuration/container-images#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](https://www.union.ai/docs/v2/flyte/user-guide/run-modes/core-concepts/projects-and-domains) for how to create projects.

</details>

## Using the configuration

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

### Explicit configuration

### Programmatic

Initialize with `flyte.init_from_config`:

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

### CLI

Use `--config` or `-c`:

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

<details>
<summary>Configuration precedence</summary>

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`

</details>

### Programmatic

```python
flyte.init_from_config()
```

### CLI

```bash
flyte run hello.py main
```

### Check current configuration

```bash
flyte get config
```

Output:

```bash
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

Use `flyte.init`:

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

### CLI

Some parameters go after `flyte`, others after the subcommand:

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

See the [CLI reference](https://www.union.ai/docs/v2/flyte/user-guide/api-reference/flyte-cli) 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**](https://www.union.ai/docs/v2/flyte/user-guide/run-modes/core-concepts/_index): Understand `TaskEnvironment`s, tasks, runs, and actions through working examples.

---
**Source**: https://github.com/unionai/unionai-docs/blob/main/content/user-guide/run-modes/running-remote.md
**HTML**: https://www.union.ai/docs/v2/flyte/user-guide/run-modes/running-remote/