App environment settings

[[AppEnvironment]]s control how your apps run in Flyte, including images, resources, secrets, startup behavior, and autoscaling.

Shared environment settings

[[AppEnvironment]]s share many configuration options with [[TaskEnvironment]]s:

• Images: See Container images for details on creating and using container images
• Resources: See Resources for CPU, memory, GPU, and storage configuration
• Secrets: See Secrets for injecting secrets into your app
• Environment variables: Set via the env_vars parameter (same as tasks)
• Cluster pools: Specify via the cluster_pool parameter

App-specific environment settings

type

The type parameter is an optional string that identifies what kind of app this is. It’s used for organizational purposes and may be used by the UI or tooling to display or filter apps.

app_env = flyte.app.AppEnvironment(
    name="my-fastapi-app",
    type="FastAPI",
    # ...
)

When using specialized app environments like FastAPIAppEnvironment, the type is automatically set. For custom apps, you can set it to any string value.

port

The port parameter specifies which port your app listens on. It can be an integer or a Port object.

# Using an integer (simple case)
app_env = flyte.app.AppEnvironment(name="my-app", port=8080, ...)

# Using a Port object (more control)
app_env = flyte.app.AppEnvironment(
    name="my-app",
    port=flyte.app.Port(port=8080),
    # ...
)

The default port is 8080. Your app should listen on this port (or the port you specify).

args

The args parameter specifies arguments to pass to your app’s command. This is typically used when you need to pass additional arguments to the command specified in command, or when using the default command behavior.

app_env = flyte.app.AppEnvironment(
    name="streamlit-app",
    args="streamlit run main.py --server.port 8080",
    port=8080,
    # ...
)

args can be either a string (which will be shell-split) or a list of strings:

# String form (will be shell-split)
args="--option1 value1 --option2 value2"

# List form (more explicit)
args=["--option1", "value1", "--option2", "value2"]

Environment variable substitution

Environment variables are automatically substituted in args strings when they start with the $ character. This works for both:

• Values from env_vars
• Secrets that are specified as environment variables (via as_env_var in flyte.Secret)

The $VARIABLE_NAME syntax will be replaced with the actual environment variable value at runtime:

# Using env_vars
app_env = flyte.app.AppEnvironment(
    name="my-app",
    env_vars={"API_KEY": "secret-key-123"},
    args="--api-key $API_KEY",  # $API_KEY will be replaced with "secret-key-123"
    # ...
)

# Using secrets
app_env = flyte.app.AppEnvironment(
    name="my-app",
    secrets=flyte.Secret(key="AUTH_SECRET", as_env_var="AUTH_SECRET"),
    args=["--api-key", "$AUTH_SECRET"],  # $AUTH_SECRET will be replaced with the secret value
    # ...
)

This is particularly useful for passing API keys or other sensitive values to command-line arguments without hardcoding them in your code. The substitution happens at runtime, ensuring secrets are never exposed in your code or configuration files.

command

The command parameter specifies the full command to run your app. If not specified, Flyte will use a default command that runs your app via fserve, which is the Python executable provided by flyte to run apps.

# Explicit command
app_env = flyte.app.AppEnvironment(
    name="streamlit-hello",
    command="streamlit hello --server.port 8080",
    port=8080,
    # ...
)

# Using default command (recommended for most cases)
# When command is None, Flyte generates a command based on your app configuration
app_env = flyte.app.AppEnvironment(name="my-app", ...)  # command=None by default

requires_auth

The requires_auth parameter controls whether the app requires authentication to access. By default, apps require authentication (requires_auth=True).

# Public app (no authentication required)
app_env = flyte.app.AppEnvironment(
    name="public-dashboard",
    requires_auth=False,
    # ...
)

# Private app (authentication required - default)
app_env = flyte.app.AppEnvironment(
    name="internal-api",
    requires_auth=True,
    # ...
)  # Default

When requires_auth=True, users must authenticate with Flyte to access the app. When requires_auth=False, the app is publicly accessible (though it may still require API keys or other app-level authentication).

domain

The domain parameter specifies a custom domain or subdomain for your app. Use flyte.app.Domain to configure a subdomain or custom domain.

app_env = flyte.app.AppEnvironment(
    name="my-app",
    domain=flyte.app.Domain(subdomain="myapp"),
    # ...
)

links

The links parameter adds links to the App UI page. Use flyte.app.Link objects to specify relative or absolute links with titles.

app_env = flyte.app.AppEnvironment(
    name="my-app",
    links=[
        flyte.app.Link(path="/docs", title="API Documentation", is_relative=True),
        flyte.app.Link(path="/health", title="Health Check", is_relative=True),
        flyte.app.Link(path="https://www.example.com", title="External link", is_relative=False),
    ],
    # ...
)

include

The include parameter specifies files and directories to include in the app bundle. Use glob patterns or explicit paths to include code files needed by your app.

app_env = flyte.app.AppEnvironment(
    name="my-app",
    include=["*.py", "models/", "utils/", "requirements.txt"],
    # ...
)

inputs

The inputs parameter passes inputs to your app at deployment time. Inputs can be primitive values, files, directories, or delayed values like RunOutput or AppEndpoint.

app_env = flyte.app.AppEnvironment(
    name="my-app",
    inputs=[
        flyte.app.Input(name="config", value="foo", env_var="BAR"),
        flyte.app.Input(name="model", value=flyte.io.File(path="s3://bucket/model.pkl"), mount="/mnt/model"),
        flyte.app.Input(name="data", value=flyte.io.File(path="s3://bucket/data.pkl"), mount="/mnt/data"),
    ],
    # ...
)

scaling

The scaling parameter configures autoscaling behavior for your app. Use flyte.app.Scaling to set replica ranges and idle TTL.

app_env = flyte.app.AppEnvironment(
    name="my-app",
    scaling=flyte.app.Scaling(
        replicas=(1, 5),
        scaledown_after=300,  # Scale down after 5 minutes of idle time
    ),
    # ...
)

depends_on

The depends_on parameter specifies environment dependencies. When you deploy an app, all dependencies are deployed first.

backend_env = flyte.app.AppEnvironment(name="backend-api", ...)

frontend_env = flyte.app.AppEnvironment(
    name="frontend-app",
    depends_on=[backend_env],  # backend-api will be deployed first
    # ...
)

App startup

Understanding the difference between args and command is crucial for properly configuring how your app starts.

Command vs args

In container terminology:

• command: The executable or entrypoint that runs
• args: Arguments passed to that command

In Flyte apps:

• command: The full command to run your app (for example, "streamlit hello --server.port 8080")
• args: Arguments to pass to your app’s command (used with the default Flyte command or your custom command)

Default startup behavior

When you don’t specify a command, Flyte generates a default command that uses fserve to run your app. This default command handles:

• Setting up the code bundle
• Configuring the version
• Setting up project/domain context
• Injecting inputs if provided

The default command looks like:

fserve --version <version> --project <project> --domain <domain> -- <args>

So if you specify args, they’ll be appended after the -- separator.

Startup examples

Using args with default command

When you use args without specifying command, the args are passed to the default Flyte command:

# Using args with default command
app_env = flyte.app.AppEnvironment(
    name="streamlit-app",
    args="streamlit run main.py --server.port 8080",
    port=8080,
    include=["main.py"],
    # command is None, so default Flyte command is used
)

This effectively runs:

fserve --version ... --project ... --domain ... -- streamlit run main.py --server.port 8080

Using explicit command

When you specify a command, it completely replaces the default command:

# Using explicit command
app_env2 = flyte.app.AppEnvironment(
    name="streamlit-hello",
    command="streamlit hello --server.port 8080",
    port=8080,
    # No args needed since command includes everything
)

This runs exactly:

streamlit hello --server.port 8080

Using command with args

You can combine both, though this is less common:

# Using command with args
app_env3 = flyte.app.AppEnvironment(
    name="custom-app",
    command="python -m myapp",
    args="--option1 value1 --option2 value2",
    # This runs: python -m myapp --option1 value1 --option2 value2
)

FastAPIAppEnvironment example

When using FastAPIAppEnvironment, the command is automatically configured to run uvicorn:

# FastAPIAppEnvironment automatically sets command
from flyte.app.extras import FastAPIAppEnvironment
from fastapi import FastAPI

app = FastAPI()

env = FastAPIAppEnvironment(
    name="my-api",
    app=app,
    # command is automatically set to: uvicorn <module>:<app_var> --port 8080
    # You typically don't need to specify command or args
)

The FastAPIAppEnvironment automatically:

1. Detects the module and variable name of your FastAPI app
2. Sets the command to run uvicorn <module>:<app_var> --port <port>
3. Handles all the startup configuration for you

Startup best practices

1. Use specialized app environments when available (for example, FastAPIAppEnvironment) – they handle command setup automatically.
2. Use args when you need code bundling and input injection.
3. Use command for simple, standalone apps that don’t need code bundling.
4. Always set port to match what your app actually listens on.
5. Use include with args to bundle your app code files.

Complete example

Here’s a complete example showing various environment, startup, and scaling settings:

"""Complete example showing various environment settings."""

import flyte
import flyte.app

# Create a custom image
image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
    "fastapi==0.104.1",
    "uvicorn==0.24.0",
    "python-multipart==0.0.6",
)

# Configure app with various settings
app_env = flyte.app.AppEnvironment(
    name="my-api",
    type="FastAPI",
    image=image,
    port=8080,
    resources=flyte.Resources(
        cpu="2",
        memory="4Gi",
    ),
    secrets=flyte.Secret(key="my-api-key", as_env_var="API_KEY"),
    env_vars={
        "LOG_LEVEL": "INFO",
        "ENVIRONMENT": "production",
    },
    requires_auth=False,  # Public API
    cluster_pool="production-pool",
    description="My production FastAPI service",
)

This example demonstrates:

• Setting a custom type identifier
• Configuring the port
• Specifying compute resources
• Injecting secrets as environment variables
• Setting environment variables
• Making the app publicly accessible
• Targeting a specific cluster pool
• Adding a description
• Configuring autoscaling behavior

For more details on shared settings like images, resources, and secrets, refer to the task configuration documentation.