Run on the Devbox

What you’ll need

• Python 3.10+ in a virtual environment
• Docker installed and running
• kubectl

Install the SDK

If you haven’t already, install the flyte package:

pip install flyte

Start the devbox

Launch the devbox:

flyte start devbox

flyte start devbox --gpu

flyte start devbox --apple-silicon

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

Check the devbox status

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

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:

flyte get devbox --no-probes

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

flyte -of json-raw get devbox

Configure

Create a config file that points to the devbox:

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:

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:

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

Run a workflow on the devbox

Using the same hello.py from the Quickstart:

# 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

Run it on the devbox:

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.

Stop the devbox

When you’re done, shut down the cluster:

flyte stop devbox

Inline configuration

Skip the config file entirely by passing parameters directly.

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

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

Delete the devbox

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.

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

Using the Apple Silicon GPU

If you started the devbox on a Mac with flyte start devbox --apple-silicon, tasks and apps that request the Apple Silicon accelerator run natively on the Mac instead of in their container. Their code can use the Mac’s GPU through Metal, for example PyTorch’s mps device or MLX.

Request it with gpu="AppleSilicon" or gpu=flyte.APPLE_SILICON():

import flyte

env = flyte.TaskEnvironment(
    name="apple_silicon_env",
    resources=flyte.Resources(gpu="AppleSilicon"),
)

"AppleSilicon:1" is also accepted. A count above 1, such as "AppleSilicon:2", is rejected.

Requirements:

• flyte 2.12.0 or later.

• uv on the Mac. --apple-silicon refuses to start without it.

• A devbox created from the current devbox image. Starting a stopped devbox doesn’t pull a new image, so recreate an older devbox:

  flyte delete devbox && flyte start devbox --apple-silicon

--apple-silicon can’t be combined with --gpu or with dev mode (--dev). Because workload code runs outside any sandbox, the flag publishes the devbox’s ports on 127.0.0.1 only. They aren’t reachable from the network, but other software on the Mac can reach them. To restart a stopped Apple Silicon devbox, run flyte start devbox. It restarts the Apple Silicon bridge without the flag.

Apple Silicon is a devbox-only accelerator, and a workload that requests it never falls back to the CPU:

• On a devbox started without --apple-silicon, the task fails with APPLE_SILICON_NOT_AVAILABLE, and the message says to restart the devbox with the flag.
• On a remote cluster whose backend includes Apple Silicon support, the task fails with APPLE_SILICON_NOT_AVAILABLE.
• On a backend that predates Apple Silicon support, including an older devbox image, the task’s pod stays Pending instead of failing.
• Where a task would fail with APPLE_SILICON_NOT_AVAILABLE, deploying an app that requests Apple Silicon is refused with the same error.

Next steps

• Core concepts: Understand TaskEnvironments, tasks, runs, and actions through working examples.
• Run on a deployed cluster: Configure the CLI and SDK to run on a cluster in the cloud or on-premises.