# Running on the devbox

The Flyte devbox is a lightweight local cluster that runs on your machine with Docker. It gives you a full Flyte environment — including the UI, scheduler, and object store — so you can test remote execution without deploying to a real cluster.

## What you'll need

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

## Install the SDK

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

```bash
pip install flyte
```

## Start the devbox

Launch the local cluster:

```bash
flyte start devbox
```

![Devbox start](https://www.union.ai/docs/v2/union/user-guide/_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.

## Configure

Create a config file that points to the devbox:

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

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

## Run a workflow on the devbox

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

```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 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, just like they would on a remote 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/user-guide/_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`](https://www.union.ai/docs/v2/union/user-guide/api-reference/flyte-sdk/packages/flyte/_index#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/user-guide/api-reference/flyte-cli) for details.

## Delete the devbox

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

## Next steps

When you're ready to run on a remote Flyte cluster, see [Running on a remote cluster](https://www.union.ai/docs/v2/union/user-guide/run-modes/running-devbox/running-remote) to configure the CLI and SDK.

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