* This page is part of the Union.ai v2 docs.
* Full index: https://www.union.ai/docs/v2/union/llms.txt
* Union.ai is a commercial superset of the open-source Flyte project and uses the same `flyte` SDK and CLI, so questions about Flyte are usually answered here too.
* Only refer to the open-source Flyte docs if you are explicitly looking for information about the open-source Flyte project, particularly the open-source Flyte backend. The open-source Flyte v2 docs are at https://www.union.ai/docs/v2/flyte/llms.txt
* These are the v2 docs. v1 is out of date and deprecated. Only refer to v1 docs if asked explicitly about v1. The v1 index is at https://www.union.ai/docs/v1/union/llms.txt

Run tasks and apps in a lightweight Flyte cluster using Docker. Get the full Flyte UI and backend experience on your machine.

# Run on the Devbox

The Flyte 2 devbox is a great way to try a simplified Union.ai cluster on your local machine. It's a lightweight
cluster that runs on your machine with Docker. It includes a UI, scheduler, and object store, so you can test on-cluster
execution without connecting to a deployed cluster.

> [!NOTE] Try Devbox in your browser
> Prefer not to install anything locally? Create a Devbox in GitHub Codespaces.
>
> [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/flyteorg/flyte-devbox-codespace?quickstart=1)

## What you'll need

- Python 3.10+ in a virtual environment
- [Docker](https://docs.docker.com/get-docker/) installed and running
- [kubectl](https://kubernetes.io/docs/tasks/tools/)

## Install the SDK

If you haven't already, install the `flyte` package:

```bash
pip install flyte
```

## Start the devbox

Launch the devbox:

### CPU

```bash
flyte start devbox
```

### GPU

```bash
flyte start devbox --gpu
```

> **📝 Note**
>
> The `--gpu` flag requires an NVIDIA-enabled host. It currently *does not* support Apple Silicon or AMD GPUs.

![Devbox start](https://www.union.ai/docs/v2/union/_static/images/user-guide/run-modes/flyte-start-devbox.png)

This pulls the necessary containers and starts a local Flyte instance. Once ready, the Flyte UI is available at `http://localhost:30080`.

> **📝 Note**
>
> The first start may take a few minutes while Docker images are downloaded.

## Check the devbox status

> [!NOTE]
> `flyte get devbox` requires flyte 2.6.2 or later.

To see whether the devbox is up, and where it is:

```bash
flyte get devbox
```

This reports the run state, the UI and image registry endpoints, the container image version in use, and where the cluster keeps its state on disk. It is the quickest way to tell a devbox that is still starting from one that is ready.

Add `--no-probes` to skip the readiness probe and the container resource sample, which makes the check faster and works offline:

```bash
flyte get devbox --no-probes
```

For a machine-readable report, pass an output format to the top-level command:

```bash
flyte -of json-raw get devbox
```

## Configure

Create a config file that points to the devbox:

```bash
flyte create config --devbox
```

This creates `.flyte/config.yaml` configured to talk to your local devbox cluster.

The `--devbox` flag requires flyte 2.6.1 or later. It is a shortcut for the explicit form, which you need on earlier versions:

```bash
flyte create config \
    --endpoint localhost:30080 \
    --project flytesnacks \
    --domain development \
    --builder local \
    --insecure
```

Both forms write the same config file. One difference: in an interactive terminal the explicit form offers to reuse a Docker login as your image registry, while `--devbox` skips that prompt, because the devbox pushes to its own in-cluster registry.

`--devbox` cannot be combined with `--endpoint`, but you can still override the project and domain alongside it:

```bash
flyte create config --devbox --project my-project --domain staging
```

## Run a workflow on the devbox

Using the same `hello.py` from the [Quickstart](https://www.union.ai/docs/v2/union/user-guide/get-started/quickstart.md):

```python
# hello.py

import flyte

# The `hello_env` TaskEnvironment is assigned to the variable `env`.
# It is then used in the `@env.task` decorator to define tasks.
# The environment groups configuration for all tasks defined within it.
env = flyte.TaskEnvironment(name="hello_env")

# We use the `@env.task` decorator to define a task called `fn`.
@env.task
def fn(x: int) -> int: # Type annotations are required
    slope, intercept = 2, 5
    return slope * x + intercept

# We also use the `@env.task` decorator to define another task called `main`.
# This is the entrypoint task of the workflow.
# It calls the `fn` task defined above multiple times using `flyte.map`.
@env.task
def main(x_list: list[int] = list(range(10))) -> float:
    y_list = list(flyte.map(fn, x_list)) # flyte.map is like Python map, but runs in parallel.
    y_mean = sum(y_list) / len(y_list)
    return y_mean
```

*Source: https://github.com/unionai/unionai-examples/blob/main/v2/user-guide/getting-started/hello.py*

Run it on the devbox:

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

Without the `--local` flag, the workflow runs on the devbox cluster rather than in your local Python process. Tasks execute inside containers, exactly as they would on a deployed cluster.

## View results in the UI

Open `http://localhost:30080` to see your workflow execution in the Flyte UI. You can inspect task inputs, outputs, logs, and execution timelines.

![Devbox UI](https://www.union.ai/docs/v2/union/_static/images/user-guide/run-modes/flyte-ui-devbox.png)

## Stop the devbox

When you're done, shut down the cluster:

```bash
flyte stop devbox
```

## Inline configuration

Skip the config file entirely by passing parameters directly.

### Programmatic

Use `flyte.init`:

```python
flyte.init(
    endpoint="localhost:30080",
    project="flytesnacks",
    domain="development",
    insecure=True,
)
```

### CLI

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

```bash
flyte \
    --endpoint localhost:30080 \
    --insecure \
    --builder local \
    run \
    --domain development \
    --project flytesnacks \
    hello.py \
    main
```

See the [CLI reference](https://www.union.ai/docs/v2/union/api-reference/flyte-cli.md) for details.

## Delete the devbox

```bash
flyte delete devbox  # add the --volume flag to delete the Docker volume
```

## Using a CUDA-enabled GPU host

If you started the devbox with `flyte start devbox --gpu`, you can use GPUs in your workflows.

```python
import flyte

env = flyte.TaskEnvironment(
    name="gpu_env",
    resources=flyte.Resources(gpu=1),
)

@env.task
def gpu_task() -> bool:
    return torch.cuda.is_available()  # returns True if CUDA (provided by a GPU) is available
```

## Next steps

- [**Core concepts**](https://www.union.ai/docs/v2/union/user-guide/get-started/core-concepts.md): Understand `TaskEnvironment`s, tasks, runs, and actions through working examples.
- [**Run on a deployed cluster**](https://www.union.ai/docs/v2/union/user-guide/get-started/run-modes/running-remote.md): Configure the CLI and SDK to run on a cluster in the cloud or on-premises.

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