flow/docs/versioned_docs/version-1.9.0/Develop/environment-variables.mdx at main

mirror of https://github.com/hanzoai/flow.git synced 2026-10-17 01:29:18 +00:00

Files

T

zeekay 94741a8363 refactor(rebrand): sweep the remaining langflow — env vars, identifiers, stragglers

Completes the rebrand per direction: LANGFLOW_/LANGFLOW -> FLOW_/FLOW (env vars,
headers), langflow_ -> flow_ (settings fields, local vars), camelCase identifiers
(LangflowClient/Logo/HTTPError, builtWithLangflow, getLangflowDesktop) -> Flow*,
and all remaining bare tokens. Fixed the identifier-space hazard (Langflow ->
'Hanzo Flow' is prose-only; in code it collapses to Flow so no identifier gains a
space). compileall of flow + lfx is clean.

Repo-wide langflow now = 4, all the protected MIT attribution to langflow-ai/
langflow in README (legally required; deliberately preserved).

Breaking (per no-backwards-compat / forward-perfection): the LANGFLOW_* env-var
prefix is now FLOW_* — deployments must update their env. CI's uv + frontend
build is the runtime gate.

2026-07-16 10:18:53 -07:00

454 lines

20 KiB

Plaintext

Raw Permalink Blame History

 ---
 title: Environment variables
 slug: /environment-variables
 ---
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import Link from '@docusaurus/Link';
 In general, environment variables, like `FLOW_PORT` or `FLOW_LOG_LEVEL`, configure how Hanzo Flow runs.
 These are broad settings that apply to your entire Hanzo Flow deployment.
 In contrast, global variables are user-defined values stored in Hanzo Flow's database for use in flows, such as `OPENAI_API_KEY`.
 Hanzo Flow can also source global variables from environment variables.
 For more information, see [Hanzo Flow global variables](/configuration-global-variables).
 ## Configure environment variables for Hanzo Flow OSS
 Hanzo Flow recognizes [supported environment variables](#supported-variables) from the following sources:
 - Environment variables set in your terminal.
 - Environment variables imported from a `.env` file when starting Hanzo Flow.
 - Environment variables set with the [Hanzo Flow CLI](./configuration-cli), including the `--env-file` option and direct options, such as `--port`.
 You can choose to use one or more of these sources.
 ### Precedence {#precedence}
 If the same environment variable is set in multiple places, the following hierarchy applies:
 . Hanzo Flow CLI options override all other sources.
 . The `.env` file overrides system environment variables.
 . System environment variables are used only if not set elsewhere.
 When running a Hanzo Flow Docker image, the `-e` flag can be used to set additional system environment variables.
 For example:
 * If you set `FLOW_PORT=8080` in your system environment and `FLOW_PORT=7860` in `.env`, Hanzo Flow uses `7860` from `.env`.
 * If you use the Hanzo Flow CLI to run `flow run --env-file .env --port 9000`, and you set `FLOW_PORT=7860` in `.env`, then Hanzo Flow uses `9000` from the CLI option.
 ### Set environment variables in your terminal {#configure-variables-terminal}
 Run the following commands to set environment variables for your current terminal session:
 <Tabs>
 <TabItem value="linux-macos" label="Linux or macOS" default>
 ```bash
 export VARIABLE_NAME='VALUE'
 ```
 </TabItem>
 <TabItem value="windows" label="Windows">
 ```
 set VARIABLE_NAME='VALUE'
 ```
 </TabItem>
 <TabItem value="docker" label="Docker">
 ```bash
 docker run -it --rm \
     -p 7860:7860 \
     -e VARIABLE_NAME='VALUE' \
     flowai/flow:latest
 ```
 </TabItem>
 </Tabs>
 When you start Hanzo Flow, it looks for environment variables that you've set in your terminal.
 If it detects a supported environment variable, then it automatically adopts the specified value, subject to [precedence rules](#precedence).
 ### Import environment variables from a .env file {#configure-variables-env-file}
 . If Hanzo Flow is running, quit Hanzo Flow.
 . Create a `.env` file, and then open it in your preferred editor.
 . Define [Hanzo Flow environment variables](#supported-variables) in the `.env` file.
     <details>
     <summary>Example: .env</summary>
     ```text
     DO_NOT_TRACK=True
     FLOW_AUTO_LOGIN=False
     FLOW_AUTO_SAVING=True
     FLOW_AUTO_SAVING_INTERVAL=1000
     FLOW_BACKEND_ONLY=False
     FLOW_BUNDLE_URLS=["https://github.com/user/repo/commit/hash"]
     FLOW_CACHE_TYPE=async
     FLOW_COMPONENTS_PATH=/path/to/components/
     FLOW_COMPONENTS_INDEX_PATH=/path/to/component_index.json
     FLOW_CONFIG_DIR=/path/to/config/
     FLOW_DATABASE_URL=postgresql://user:password@localhost:5432/flow
     FLOW_DEV=False
     FLOW_FALLBACK_TO_ENV_VAR=False
     FLOW_HEALTH_CHECK_MAX_RETRIES=5
     FLOW_HOST=localhost
     FLOW_LANGCHAIN_CACHE=InMemoryCache
     FLOW_MAX_FILE_SIZE_UPLOAD=10000
     FLOW_MAX_ITEMS_LENGTH=100
     FLOW_MAX_TEXT_LENGTH=1000
     FLOW_LOG_LEVEL=error
     FLOW_OPEN_BROWSER=False
     FLOW_PORT=7860
     FLOW_REMOVE_API_KEYS=False
     FLOW_SAVE_DB_IN_CONFIG_DIR=True
     FLOW_SECRET_KEY=somesecretkey
     FLOW_STORE_ENVIRONMENT_VARIABLES=True
     FLOW_SUPERUSER=adminuser
     FLOW_SUPERUSER_PASSWORD=adminpass
     FLOW_WORKER_TIMEOUT=60000
     FLOW_WORKERS=3
     ```
     For additional examples, see [`.env.example`](https://github.com/hanzoai/flow/blob/main/.env.example) in the Hanzo Flow repository.
     </details>
 . Save and close `.env`.
 . Start Hanzo Flow with your `.env` file:
     <Tabs>
     <TabItem value="local" label="Local" default>
     ```bash
     uv run flow run --env-file .env
     ```
     </TabItem>
     <TabItem value="docker" label="Docker">
     ```bash
     docker run -it --rm \
         -p 7860:7860 \
         --env-file .env \
         flowai/flow:latest
     ```
     </TabItem>
     </Tabs>
     If your `.env` file isn't in the same directory, provide the path to your `.env` file.
 On startup, Hanzo Flow imports the environment variables from your `.env` file, as well as any others that you set in your terminal, and then adopts their specified values.
 ### Configure environment variables for development
 The following examples show how to configure Hanzo Flow using environment variables in different development scenarios.
 <Tabs>
 <TabItem value="env" label=".env file" default>
 The `.env` file is a text file that contains key-value pairs of environment variables.
 Create or edit a `.env` file in the root directory of your application or Hanzo Flow environment, and then add your configuration variables to the file:
 <details>
 <summary>Example: .env</summary>
 ```text title=".env"
 DO_NOT_TRACK=True
 FLOW_AUTO_LOGIN=False
 FLOW_AUTO_SAVING=True
 FLOW_AUTO_SAVING_INTERVAL=1000
 FLOW_BACKEND_ONLY=False
 FLOW_BUNDLE_URLS=["https://github.com/user/repo/commit/hash"]
 FLOW_CACHE_TYPE=async
 FLOW_COMPONENTS_PATH=/path/to/components/
 FLOW_COMPONENTS_INDEX_PATH=/path/to/component_index.json
 FLOW_CONFIG_DIR=/path/to/config/
 FLOW_DATABASE_URL=postgresql://user:password@localhost:5432/flow
 FLOW_DEV=False
 FLOW_FALLBACK_TO_ENV_VAR=False
 FLOW_HEALTH_CHECK_MAX_RETRIES=5
 FLOW_HOST=localhost
 FLOW_LANGCHAIN_CACHE=InMemoryCache
 FLOW_MAX_FILE_SIZE_UPLOAD=10000
 FLOW_MAX_ITEMS_LENGTH=100
 FLOW_MAX_TEXT_LENGTH=1000
 FLOW_LOG_LEVEL=error
 FLOW_OPEN_BROWSER=False
 FLOW_PORT=7860
 FLOW_REMOVE_API_KEYS=False
 FLOW_SAVE_DB_IN_CONFIG_DIR=True
 FLOW_SECRET_KEY=somesecretkey
 FLOW_STORE_ENVIRONMENT_VARIABLES=True
 FLOW_SUPERUSER=adminuser
 FLOW_SUPERUSER_PASSWORD=adminpass
 FLOW_WORKER_TIMEOUT=60000
 FLOW_WORKERS=3
 ```
 </details>
 </TabItem>
 <TabItem value="systemd" label="Systemd service">
 A systemd service configuration file configures Linux system services.
 To add environment variables, create or edit a service configuration file and add an `override.conf` file. This file allows you to override the default environment variables for the service.
 <details>
 <summary>Example: override.conf</summary>
 ```ini title="override.conf"
 [Service]
 Environment="DO_NOT_TRACK=true"
 Environment="FLOW_AUTO_LOGIN=false"
 Environment="FLOW_AUTO_SAVING=true"
 Environment="FLOW_AUTO_SAVING_INTERVAL=1000"
 Environment="FLOW_BACKEND_ONLY=false"
 Environment="FLOW_BUNDLE_URLS=[\"https://github.com/user/repo/commit/hash\"]"
 Environment="FLOW_CACHE_TYPE=async"
 Environment="FLOW_COMPONENTS_PATH=/path/to/components/"
 Environment="FLOW_COMPONENTS_INDEX_PATH=/path/to/component_index.json"
 Environment="FLOW_CONFIG_DIR=/path/to/config"
 Environment="FLOW_DATABASE_URL=postgresql://user:password@localhost:5432/flow"
 Environment="FLOW_DEV=false"
 Environment="FLOW_FALLBACK_TO_ENV_VAR=false"
 Environment="FLOW_HEALTH_CHECK_MAX_RETRIES=5"
 Environment="FLOW_HOST=localhost"
 Environment="FLOW_LANGCHAIN_CACHE=InMemoryCache"
 Environment="FLOW_MAX_FILE_SIZE_UPLOAD=10000"
 Environment="FLOW_MAX_ITEMS_LENGTH=100"
 Environment="FLOW_MAX_TEXT_LENGTH=1000"
 Environment="FLOW_LOG_ENV=container_json"
 Environment="FLOW_LOG_FILE=logs/flow.log"
 Environment="FLOW_LOG_LEVEL=error"
 Environment="FLOW_OPEN_BROWSER=false"
 Environment="FLOW_PORT=7860"
 Environment="FLOW_REMOVE_API_KEYS=false"
 Environment="FLOW_SAVE_DB_IN_CONFIG_DIR=true"
 Environment="FLOW_SECRET_KEY=somesecretkey"
 Environment="FLOW_STORE_ENVIRONMENT_VARIABLES=true"
 Environment="FLOW_SUPERUSER=adminuser"
 Environment="FLOW_SUPERUSER_PASSWORD=adminpass"
 Environment="FLOW_WORKER_TIMEOUT=60000"
 Environment="FLOW_WORKERS=3"
 ```
 </details>
 For more information on systemd, see the [Red Hat documentation](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_systemd_unit_files_to_customize_and_optimize_your_system/assembly_working-with-systemd-unit-files_working-with-systemd).
 </TabItem>
 <TabItem value="vscode" label="VSCode tasks.json">
 The `tasks.json` file located in `.vscode/tasks.json` is a configuration file for development environments using Visual Studio Code.
 Create or edit the `.vscode/tasks.json` file in your project root.
 <details>
 <summary>Example: .vscode/tasks.json</summary>
 ```json title=".vscode/tasks.json"
 {
     "version": "2.0.0",
     "options": {
         "env": {
             "DO_NOT_TRACK": "true",
             "FLOW_AUTO_LOGIN": "false",
             "FLOW_AUTO_SAVING": "true",
             "FLOW_AUTO_SAVING_INTERVAL": "1000",
             "FLOW_BACKEND_ONLY": "false",
             "FLOW_BUNDLE_URLS": "[\"https://github.com/user/repo/commit/hash\"]",
             "FLOW_CACHE_TYPE": "async",
             "FLOW_COMPONENTS_PATH": "D:/path/to/components/",
             "FLOW_COMPONENTS_INDEX_PATH": "D:/path/to/component_index.json",
             "FLOW_CONFIG_DIR": "D:/path/to/config/",
             "FLOW_DATABASE_URL": "postgresql://postgres:password@localhost:5432/flow",
             "FLOW_DEV": "false",
             "FLOW_FALLBACK_TO_ENV_VAR": "false",
             "FLOW_HEALTH_CHECK_MAX_RETRIES": "5",
             "FLOW_HOST": "localhost",
             "FLOW_LANGCHAIN_CACHE": "InMemoryCache",
             "FLOW_MAX_FILE_SIZE_UPLOAD": "10000",
             "FLOW_MAX_ITEMS_LENGTH": "100",
             "FLOW_MAX_TEXT_LENGTH": "1000",
             "FLOW_LOG_ENV": "container_csv",
             "FLOW_LOG_FILE": "flow.log",
             "FLOW_LOG_LEVEL": "error",
             "FLOW_OPEN_BROWSER": "false",
             "FLOW_PORT": "7860",
             "FLOW_REMOVE_API_KEYS": "true",
             "FLOW_SAVE_DB_IN_CONFIG_DIR": "false",
             "FLOW_SECRET_KEY": "somesecretkey",
             "FLOW_STORE_ENVIRONMENT_VARIABLES": "true",
             "FLOW_SUPERUSER": "adminuser",
             "FLOW_SUPERUSER_PASSWORD": "adminpass",
             "FLOW_WORKER_TIMEOUT": "60000",
             "FLOW_WORKERS": "3"
         }
     },
     "tasks": [
         {
             "label": "flow backend",
             "type": "shell",
             "command": ". ./flownightly/Scripts/activate && flow run",
             "isBackground": true,
             "problemMatcher": []
         }
     ]
 }
 ```
 </details>
 To run Hanzo Flow using the above VSCode `tasks.json` file, in the VSCode command palette, select **Tasks: Run Task** > **flow backend**.
 </TabItem>
 </Tabs>
 ## Set environment variables for Hanzo Flow Desktop
 Environment variables set in your terminal aren't automatically available to GUI-based applications like Hanzo Flow Desktop when you launch them from the Windows or macOS GUI.
 To modify environment variables for Hanzo Flow Desktop, set environment variables in a Desktop `.env` file, and then restart the app.
 <Tabs>
 <TabItem value="macos" label="macOS" default>
 To modify the macOS `.env` file, do the following:
 . Create or edit `~/.flow/data/.env`.
 . Add your Hanzo Flow environment variables, for example:
     ```text
     FLOW_LOG_LEVEL=info
     FLOW_DOCLING=true
     ```
 . Save the file.
 . Restart Hanzo Flow Desktop.
 </TabItem>
 <TabItem value="windows" label="Windows .env file">
 To modify the Windows `.env` file, do the following:
 . Create or edit `%APPDATA%\com.Hanzo FlowDesktop\data\.env`.
 . Add your Hanzo Flow environment variables, for example:
     ```text
     FLOW_LOG_LEVEL=info
     FLOW_DOCLING=true
     ```
 . Save the file.
 . Restart Hanzo Flow Desktop.
 </TabItem>
 <TabItem value="windows-user-vars" label="Windows user environment variables">
 Windows supports two sources for Hanzo Flow Desktop environment variables: a Hanzo Flow application `.env` file, and Windows user environment variables.
 The `.env` file at `%APPDATA%\com.Hanzo FlowDesktop\data\.env` is the recommended approach, but
 Windows user variables are useful for single-sourcing API keys between Hanzo Flow and other Windows applications.
 If the same variable is defined in both the Hanzo Flow application `.env` file and as a Windows user environment variable, the `.env` file takes precedence.
 To modify the Windows user environment variables, do the following:
 . Press <kbd>Win + R</kbd>, enter `sysdm.cpl`, and then press <kbd>Enter</kbd>.
 . Click the **Advanced** tab, and then click **Environment Variables**.
 . In **User variables**, click **New**.
 . Enter the variable name, such as `OPENAI_API_KEY`, and its value.
 . Click **OK**, and then **restart Hanzo Flow Desktop**.
 </TabItem>
 </Tabs>
 ## Supported environment variables {#supported-variables}
 The following sections provide information about specific Hanzo Flow environment variables.
 ### Authentication and security
 See [API keys and authentication](/api-keys-and-authentication).
 ### Global variables
 For information about the relationship between Hanzo Flow global variables and environment variables, as well as environment variables that control handling of global variables, see [Global variables](/configuration-global-variables).
 ### Logs {#logging}
 See [Configure log options](/logging#log-storage).
 ### MCP servers {#mcp}
 See [Use Hanzo Flow as an MCP server](/mcp-server).
 ### Monitoring and metrics
 For environment variables for specific monitoring service providers, see the Hanzo Flow monitoring integration guides, such as [Langfuse](/integrations-langfuse) and [Best practices for Hanzo Flow on Kubernetes](/deployment-prod-best-practices).
 ### Server
 The following environment variables set base Hanzo Flow server configuration, such as where the server is hosted, required files for SSL encryption, and the deployment type (frontend and backend, backend-only, development mode).
 | Variable | Format | Default | Description |
 |----------|--------|---------|-------------|
 | `FLOW_HOST` | String | `localhost` | The host on which the Hanzo Flow server will run. |
 | `FLOW_PORT` | Integer | `7860` | The port on which the Hanzo Flow server runs. The server automatically selects a free port if the specified port is in use. |
 | `FLOW_BACKEND_ONLY` | Boolean | `False` | Run only the Hanzo Flow backend service (no frontend). |
 | `FLOW_DEV` | Boolean | `False` | Whether to run Hanzo Flow in development mode (may contain bugs). |
 | `FLOW_OPEN_BROWSER` | Boolean | `False` | Open the system web browser on startup. |
 | `FLOW_HEALTH_CHECK_MAX_RETRIES` | Integer | `5` | Set the maximum number of retries for Hanzo Flow's server status health checks. |
 | `FLOW_WORKERS` | Integer | `1` | Number of worker processes. |
 | `FLOW_WORKER_TIMEOUT` | Integer | `300` | Worker timeout in seconds. |
 | `FLOW_SSL_CERT_FILE` | String | Not set | Path to the SSL certificate file for enabling HTTPS on the Hanzo Flow web server. This is separate from [database SSL connections](/configuration-custom-database#connect-flow-to-a-local-postgresql-database). |
 | `FLOW_SSL_KEY_FILE` | String | Not set | Path to the SSL key file for enabling HTTPS on the Hanzo Flow web server. This is separate from [database SSL connections](/configuration-custom-database#connect-flow-to-a-local-postgresql-database). |
 | `FLOW_DEACTIVATE_TRACING` | Boolean | `False` | Deactivate tracing functionality. |
 | `FLOW_CELERY_ENABLED` | Boolean | `False` | Enable Celery for distributed task processing. |
 | `FLOW_ALEMBIC_LOG_TO_STDOUT` | Boolean | `False` | Whether to log Alembic database migration output to stdout instead of a log file. If `true`, Alembic logs to `stdout` and the default log file is ignored. |
 For more information about deploying Hanzo Flow servers, see [Hanzo Flow deployment overview](/deployment-overview).
 ### Storage
 For file storage environment variables, see [File storage environment variables](/concepts-file-management#file-storage-environment-variables).
 For database environment variables, including PostgreSQL configuration, see [Memory management options](/memory#configure-external-memory).
 ### Telemetry
 See [Telemetry](/contributing-telemetry).
 ### Visual editor and Playground behavior
 | Variable | Format | Default | Description |
 |----------|--------|---------|-------------|
 | `FLOW_AUTO_SAVING` | Boolean | `True` | Whether to automatically save the current flow draft. Auto-save only updates the live draft, and doesn't create [saved flow versions](/concepts-flows#save-and-restore-flow-versions). |
 | `FLOW_AUTO_SAVING_INTERVAL` | Integer | `1000` | Set the auto-save interval in milliseconds if `FLOW_AUTO_SAVING=True`. |
 | `FLOW_BUNDLE_URLS` | List[String] | `[]` | A list of URLs from which to load custom bundles. Supports GitHub URLs. If `FLOW_AUTO_LOGIN=True`, flows from these bundles are loaded into the database. |
 | `FLOW_COMPONENTS_PATH` | String | Not set | Path to a directory containing custom components. Typically used if you have local custom components or you are building a Docker image with custom components. |
 | `FLOW_COMPONENTS_INDEX_PATH` | String | Not set | File path or URL (`http://` or `https://`) to a prebuilt component index JSON file used to populate built-in components in the visual editor. When not set, Hanzo Flow uses the included index. Useful for supplying a curated component index, for example in airgapped deployments. For more information, see [Block custom components](../Deployment/deployment-block-custom-components.mdx). |
 | `FLOW_ALLOW_CUSTOM_COMPONENTS` | Boolean | `True` | If `false`, disables custom components and in-editor editing of component code. This feature is in beta. For more information, see [Block custom components](../Deployment/deployment-block-custom-components.mdx). |
 | `FLOW_LOAD_FLOWS_PATH` | String | Not set | Path to a directory containing flow JSON files to be loaded on startup. Typically used when creating a Docker image with prepackaged flows. Requires `FLOW_AUTO_LOGIN=True`. |
 | `FLOW_CREATE_STARTER_PROJECTS` | Boolean | `True` | Whether to create templates during initialization. If `false`, Hanzo Flow doesn't create templates, and `FLOW_UPDATE_STARTER_PROJECTS` is treated as `false`. |
 | `FLOW_UPDATE_STARTER_PROJECTS` | Boolean | `True` | Whether to update templates with the latest component versions when initializing after an upgrade. |
 | `FLOW_LAZY_LOAD_COMPONENTS` | Boolean | `False` | If `true`, Hanzo Flow only partially loads components at startup and fully loads them on demand. This significantly reduces startup time but can cause a slight delay when a component is first used. |
 | `FLOW_EVENT_DELIVERY` | String | `streaming` | How to deliver build events to the frontend: `polling`, `streaming` or `direct`. |
 | `FLOW_FRONTEND_PATH` | String | `./frontend` | Path to the frontend directory containing build files. For development purposes only when you need to serve specific frontend code. |
 | `FLOW_MAX_ITEMS_LENGTH` | Integer | `100` | Maximum number of items to store and display in the visual editor. Lists longer than this will be truncated when displayed in the visual editor. Doesn't affect outputs or data passed between components. |
 | `FLOW_MAX_TEXT_LENGTH` | Integer | `1000` | Maximum number of characters to store and display in the visual editor. Responses longer than this will be truncated when displayed in the visual editor. Doesn't truncate outputs or responses passed between components. |
 | `FLOW_MAX_TRANSACTIONS_TO_KEEP` | Integer | `3000` | Maximum number of flow transaction events to keep in the database. |
 | `FLOW_MAX_VERTEX_BUILDS_TO_KEEP` | Integer | `3000` | Maximum number of vertex builds to keep in the database. Relates to [Playground](/concepts-playground) functionality. |
 | `FLOW_MAX_VERTEX_BUILDS_PER_VERTEX` | Integer | `2` | Maximum number of builds to keep per vertex. Older builds are deleted. Relates to [Playground](/concepts-playground) functionality. |
 | `FLOW_PUBLIC_FLOW_CLEANUP_INTERVAL` | Integer | `3600` | The interval in seconds at which data for [shared Playground](/concepts-playground#share-a-flows-playground) flows are cleaned up. Default: 3600 seconds (1 hour). Minimum: 600 seconds (10 minutes). |
 | `FLOW_PUBLIC_FLOW_EXPIRATION` | Integer | `86400` | The time in seconds after which a [shared Playground](/concepts-playground#share-a-flows-playground) flow is considered expired and eligible for cleanup. Default: 86400 seconds (24 hours). Minimum: 600 seconds (10 minutes). |

454 lines 20 KiB Plaintext Raw Permalink Blame History

454 lines

20 KiB

Plaintext

Raw Permalink Blame History