Environment variables

In general, environment variables, like SKILLFLAW_PORT or SKILLFLAW_LOG_LEVEL, configure how SkillFlaw runs. These are broad settings that apply to your entire SkillFlaw deployment.

In contrast, global variables are user-defined values stored in SkillFlaw's database for use in flows, such as OPENAI_API_KEY. SkillFlaw can also source global variables from environment variables. For more information, see SkillFlaw global variables.

Configure environment variables for SkillFlaw OSS

SkillFlaw recognizes supported environment variables from the following sources:

• Environment variables set in your terminal.
• Environment variables imported from a .env file when starting SkillFlaw.
• Environment variables set with the SkillFlaw CLI, including the --env-file option and direct options, such as --port.

You can choose to use one or more of these sources.

Precedence

If the same environment variable is set in multiple places, the following hierarchy applies:

1. SkillFlaw CLI options override all other sources.
2. The .env file overrides system environment variables.
3. System environment variables are used only if not set elsewhere.

For example:

• If you set SKILLFLAW_PORT=8080 in your system environment and SKILLFLAW_PORT=7860 in .env, SkillFlaw uses 7860 from .env.
• If you use the SkillFlaw CLI to run skillflaw run --env-file .env --port 9000, and you set SKILLFLAW_PORT=7860 in .env, then SkillFlaw uses 9000 from the CLI option.

Set environment variables in your terminal

Run the following commands to set environment variables for your current terminal session:

Linux or macOS

_10

export VARIABLE_NAME='VALUE'

Windows

_10

set VARIABLE_NAME='VALUE'

When you start SkillFlaw, 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.

Import environment variables from a .env file

1. If SkillFlaw is running, quit SkillFlaw.

2. Create a .env file, and then open it in your preferred editor.

3. Define SkillFlaw environment variables in the .env file.

   Example: .env

   
   

   _28

   DO_NOT_TRACK=True

   _28

   SKILLFLAW_AUTO_LOGIN=False

   _28

   SKILLFLAW_AUTO_SAVING=True

   _28

   SKILLFLAW_AUTO_SAVING_INTERVAL=1000

   _28

   SKILLFLAW_BACKEND_ONLY=False

   _28

   SKILLFLAW_BUNDLE_URLS=["https://github.com/user/repo/commit/hash"]

   _28

   SKILLFLAW_CACHE_TYPE=async

   _28

   SKILLFLAW_COMPONENTS_PATH=/path/to/components/

   _28

   SKILLFLAW_CONFIG_DIR=/path/to/config/

   _28

   SKILLFLAW_DATABASE_URL=postgresql://user:password@localhost:5432/skillflaw

   _28

   SKILLFLAW_DEV=False

   _28

   SKILLFLAW_FALLBACK_TO_ENV_VAR=False

   _28

   SKILLFLAW_HEALTH_CHECK_MAX_RETRIES=5

   _28

   SKILLFLAW_HOST=localhost

   _28

   SKILLFLAW_LANGCHAIN_CACHE=InMemoryCache

   _28

   SKILLFLAW_MAX_FILE_SIZE_UPLOAD=10000

   _28

   SKILLFLAW_MAX_ITEMS_LENGTH=100

   _28

   SKILLFLAW_MAX_TEXT_LENGTH=1000

   _28

   SKILLFLAW_LOG_LEVEL=error

   _28

   SKILLFLAW_OPEN_BROWSER=False

   _28

   SKILLFLAW_PORT=7860

   _28

   SKILLFLAW_REMOVE_API_KEYS=False

   _28

   SKILLFLAW_SECRET_KEY=somesecretkey

   _28

   SKILLFLAW_STORE_ENVIRONMENT_VARIABLES=True

   _28

   SKILLFLAW_SUPERUSER=adminuser

   _28

   SKILLFLAW_SUPERUSER_PASSWORD=adminpass

   _28

   SKILLFLAW_WORKER_TIMEOUT=60000

   _28

   SKILLFLAW_WORKERS=3

   
   

   For a maintained template, see .env.example in the project source.

4. Save and close .env.

5. Start SkillFlaw with your .env file:

   
   

   _10

   uv run skillflaw run --env-file .env

   
   

   If your .env file isn't in the same directory, provide the path to your .env file.

On startup, SkillFlaw 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 SkillFlaw using environment variables in different development scenarios.

.env file

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 SkillFlaw environment, and then add your configuration variables to the file:

Example: .env

_27

DO_NOT_TRACK=True

_27

SKILLFLAW_AUTO_SAVING=True

_27

SKILLFLAW_AUTO_SAVING_INTERVAL=1000

_27

SKILLFLAW_BACKEND_ONLY=False

_27

SKILLFLAW_BUNDLE_URLS=["https://github.com/user/repo/commit/hash"]

_27

SKILLFLAW_CACHE_TYPE=async

_27

SKILLFLAW_COMPONENTS_PATH=/path/to/components/

_27

SKILLFLAW_CONFIG_DIR=/path/to/config/

_27

SKILLFLAW_DATABASE_URL=postgresql://user:password@localhost:5432/skillflaw

_27

SKILLFLAW_DEV=False

_27

SKILLFLAW_FALLBACK_TO_ENV_VAR=False

_27

SKILLFLAW_HEALTH_CHECK_MAX_RETRIES=5

_27

SKILLFLAW_HOST=localhost

_27

SKILLFLAW_LANGCHAIN_CACHE=InMemoryCache

_27

SKILLFLAW_MAX_FILE_SIZE_UPLOAD=10000

_27

SKILLFLAW_MAX_ITEMS_LENGTH=100

_27

SKILLFLAW_MAX_TEXT_LENGTH=1000

_27

SKILLFLAW_LOG_LEVEL=error

_27

SKILLFLAW_OPEN_BROWSER=False

_27

SKILLFLAW_PORT=7860

_27

SKILLFLAW_REMOVE_API_KEYS=False

_27

SKILLFLAW_SECRET_KEY=somesecretkey

_27

SKILLFLAW_STORE_ENVIRONMENT_VARIABLES=True

_27

SKILLFLAW_SUPERUSER=adminuser

_27

SKILLFLAW_SUPERUSER_PASSWORD=adminpass

_27

SKILLFLAW_WORKER_TIMEOUT=60000

_27

SKILLFLAW_WORKERS=3

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.

Example: override.conf

_30

[Service]

_30

Environment="DO_NOT_TRACK=true"

_30

Environment="SKILLFLAW_AUTO_SAVING=true"

_30

Environment="SKILLFLAW_AUTO_SAVING_INTERVAL=1000"

_30

Environment="SKILLFLAW_BACKEND_ONLY=false"

_30

Environment="SKILLFLAW_BUNDLE_URLS=[\"https://github.com/user/repo/commit/hash\"]"

_30

Environment="SKILLFLAW_CACHE_TYPE=async"

_30

Environment="SKILLFLAW_COMPONENTS_PATH=/path/to/components/"

_30

Environment="SKILLFLAW_CONFIG_DIR=/path/to/config"

_30

Environment="SKILLFLAW_DATABASE_URL=postgresql://user:password@localhost:5432/skillflaw"

_30

Environment="SKILLFLAW_DEV=false"

_30

Environment="SKILLFLAW_FALLBACK_TO_ENV_VAR=false"

_30

Environment="SKILLFLAW_HEALTH_CHECK_MAX_RETRIES=5"

_30

Environment="SKILLFLAW_HOST=localhost"

_30

Environment="SKILLFLAW_LANGCHAIN_CACHE=InMemoryCache"

_30

Environment="SKILLFLAW_MAX_FILE_SIZE_UPLOAD=10000"

_30

Environment="SKILLFLAW_MAX_ITEMS_LENGTH=100"

_30

Environment="SKILLFLAW_MAX_TEXT_LENGTH=1000"

_30

Environment="SKILLFLAW_LOG_ENV=container_json"

_30

Environment="SKILLFLAW_LOG_FILE=logs/skillflaw.log"

_30

Environment="SKILLFLAW_LOG_LEVEL=error"

_30

Environment="SKILLFLAW_OPEN_BROWSER=false"

_30

Environment="SKILLFLAW_PORT=7860"

_30

Environment="SKILLFLAW_REMOVE_API_KEYS=false"

_30

Environment="SKILLFLAW_SECRET_KEY=somesecretkey"

_30

Environment="SKILLFLAW_STORE_ENVIRONMENT_VARIABLES=true"

_30

Environment="SKILLFLAW_SUPERUSER=adminuser"

_30

Environment="SKILLFLAW_SUPERUSER_PASSWORD=adminpass"

_30

Environment="SKILLFLAW_WORKER_TIMEOUT=60000"

_30

Environment="SKILLFLAW_WORKERS=3"

For more information on systemd, see the Red Hat documentation.

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.

Example: .vscode/tasks.json

_45

{

_45

"version": "2.0.0",

_45

"options": {

_45

"env": {

_45

"DO_NOT_TRACK": "true",

_45

"SKILLFLAW_AUTO_SAVING": "true",

_45

"SKILLFLAW_AUTO_SAVING_INTERVAL": "1000",

_45

"SKILLFLAW_BACKEND_ONLY": "false",

_45

"SKILLFLAW_BUNDLE_URLS": "[\"https://github.com/user/repo/commit/hash\"]",

_45

"SKILLFLAW_CACHE_TYPE": "async",

_45

"SKILLFLAW_COMPONENTS_PATH": "D:/path/to/components/",

_45

"SKILLFLAW_CONFIG_DIR": "D:/path/to/config/",

_45

"SKILLFLAW_DATABASE_URL": "postgresql://postgres:password@localhost:5432/skillflaw",

_45

"SKILLFLAW_DEV": "false",

_45

"SKILLFLAW_FALLBACK_TO_ENV_VAR": "false",

_45

"SKILLFLAW_HEALTH_CHECK_MAX_RETRIES": "5",

_45

"SKILLFLAW_HOST": "localhost",

_45

"SKILLFLAW_LANGCHAIN_CACHE": "InMemoryCache",

_45

"SKILLFLAW_MAX_FILE_SIZE_UPLOAD": "10000",

_45

"SKILLFLAW_MAX_ITEMS_LENGTH": "100",

_45

"SKILLFLAW_MAX_TEXT_LENGTH": "1000",

_45

"SKILLFLAW_LOG_ENV": "container_csv",

_45

"SKILLFLAW_LOG_FILE": "skillflaw.log",

_45

"SKILLFLAW_LOG_LEVEL": "error",

_45

"SKILLFLAW_OPEN_BROWSER": "false",

_45

"SKILLFLAW_PORT": "7860",

_45

"SKILLFLAW_REMOVE_API_KEYS": "true",

_45

"SKILLFLAW_SECRET_KEY": "somesecretkey",

_45

"SKILLFLAW_STORE_ENVIRONMENT_VARIABLES": "true",

_45

"SKILLFLAW_SUPERUSER": "adminuser",

_45

"SKILLFLAW_SUPERUSER_PASSWORD": "adminpass",

_45

"SKILLFLAW_WORKER_TIMEOUT": "60000",

_45

"SKILLFLAW_WORKERS": "3"

_45

}

_45

},

_45

"tasks": [

_45

{

_45

"label": "skillflaw backend",

_45

"type": "shell",

_45

"command": ". ./skillflawnightly/Scripts/activate && skillflaw run",

_45

"isBackground": true,

_45

"problemMatcher": []

_45

}

_45

]

_45

}

To run SkillFlaw using the above VSCode tasks.json file, in the VSCode command palette, select Tasks: Run Task > skillflaw backend.

Set environment variables for SkillFlaw Desktop

Environment variables set in your terminal aren't automatically available to GUI-based applications like SkillFlaw Desktop when you launch them from the Windows or macOS GUI.

For Windows, this means any GUI-based app launched from the Start menu, desktop shortcuts, or Windows Explorer.

For macOS, this means any GUI-based app launched from Finder, Spotlight, Launchpad, or the Dock.

To set environment variables for SkillFlaw Desktop, you need to use specific commands or files, depending on your OS.

macOS

SkillFlaw Desktop for macOS cannot automatically use variables set in your terminal, such as those in.zshrc or .bash_profile, when launched from the macOS GUI.

To make environment variables available to GUI apps on macOS, you need to use launchctl with a plist file:

1. Create the LaunchAgents directory if it doesn't exist:

   
   

   _10

   mkdir -p ~/Library/LaunchAgents

   
   

2. In the LaunchAgents directory, create a .plist file called dev.skillflaw.env.

3. Add the following content to dev.skillflaw.env.plist, and then add, change, or remove SkillFlaw environment variables as needed for your configuration.

   This example sets multiple environmental variables for all GUI apps launched from the macOS GUI.

   
   

   _21

   <?xml version="1.0" encoding="UTF-8"?>

   _21

   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

   _21

   <plist version="1.0">

   _21

   <dict>

   _21

   <key>Label</key>

   _21

   <string>dev.skillflaw.env</string>

   _21

   <key>ProgramArguments</key>

   _21

   <array>

   _21

   <string>/bin/sh</string>

   _21

   <string>-c</string>

   _21

   <string>

   _21

   launchctl setenv SKILLFLAW_CONFIG_DIR /Users/your_user/custom/config ;

   _21

   launchctl setenv SKILLFLAW_PORT 7860 ;

   _21

   launchctl setenv SKILLFLAW_HOST localhost ;

   _21

   launchctl setenv ARIZE_API_KEY ak-...

   _21

   </string>

   _21

   </array>

   _21

   <key>RunAtLoad</key>

   _21

   <true/>

   _21

   </dict>

   _21

   </plist>

   
   

4. Load the file with launchctl:

   
   

   _10

   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.skillflaw.env.plist

   
   

Window System Properties

SkillFlaw Desktop for Windows cannot automatically use variables set in your terminal, such as those defined with set in cmd or $env:VAR=... in PowerShell, when launched from the Windows GUI.

To make environment variables available to the SkillFlaw Desktop app, you must set them at the user or system level using the System Properties interface or the Terminal.

To set environment variables using the System Properties interface, do the following:

1. Press Win + R, enter SystemPropertiesAdvanced, and then press Enter.

2. Click Environment Variables.

3. Under User variables, click New.

   tip

   To apply the setting to all users, select System variables.

4. Enter the name of the SkillFlaw variable you want to set, such as SKILLFLAW_CONFIG_DIR, and the desired value, such as C:\Users\your_user\.skillflaw_config.

5. Click OK to save the variable.

6. Repeat until you have set all necessary SkillFlaw environment variables.

7. Launch or restart SkillFlaw Desktop to apply the environment variables.

Powershell

To define environment variables for Windows using PowerShell, do the following:

1. Enter the name of the SkillFlaw variable you want to set, such as SKILLFLAW_CONFIG_DIR, and the desired value, such as C:\Users\your_user\.skillflaw_config.

   To set an environment variable for the current user:

   
   

   _10

   [System.Environment]::SetEnvironmentVariable("SKILLFLAW_CONFIG_DIR", "C:\Users\your_user\.skillflaw_config", "User")

   
   

   To set an environment variable for all users (you must have Administrator priveleges):

   
   

   _10

   [System.Environment]::SetEnvironmentVariable("SKILLFLAW_CONFIG_DIR", "C:\SkillFlaw\Config", "Machine")

   
   

2. Repeat until you have set all necessary SkillFlaw environment variables.

3. Launch or restart SkillFlaw Desktop to apply the environment variables.

Supported environment variables

The following sections provide information about specific SkillFlaw environment variables.

Authentication and security

See API keys and authentication.

Global variables

For information about the relationship between SkillFlaw global variables and environment variables, as well as environment variables that control handling of global variables, see Global variables.

Logs

See Configure log options.

MCP servers

See Use SkillFlaw as an MCP server.

Monitoring and metrics

For environment variables for specific monitoring service providers, see the SkillFlaw monitoring integration guides, such as Langfuse and Best practices for SkillFlaw on Kubernetes.

Server

The following environment variables set base SkillFlaw 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
SKILLFLAW_HOST	String	localhost	The host on which the SkillFlaw server will run.
SKILLFLAW_PORT	Integer	7860	The port on which the SkillFlaw server runs. The server automatically selects a free port if the specified port is in use.
SKILLFLAW_BACKEND_ONLY	Boolean	False	Run only the SkillFlaw backend service (no frontend).
SKILLFLAW_DEV	Boolean	False	Whether to run SkillFlaw in development mode (may contain bugs).
SKILLFLAW_OPEN_BROWSER	Boolean	False	Open the system web browser on startup.
SKILLFLAW_HEALTH_CHECK_MAX_RETRIES	Integer	5	Set the maximum number of retries for SkillFlaw's server status health checks.
SKILLFLAW_WORKERS	Integer	1	Number of worker processes.
SKILLFLAW_WORKER_TIMEOUT	Integer	300	Worker timeout in seconds.
SKILLFLAW_SSL_CERT_FILE	String	Not set	Path to the SSL certificate file for enabling HTTPS on the SkillFlaw web server. This is separate from database SSL connections.
SKILLFLAW_SSL_KEY_FILE	String	Not set	Path to the SSL key file for enabling HTTPS on the SkillFlaw web server. This is separate from database SSL connections.
SKILLFLAW_DEACTIVATE_TRACING	Boolean	False	Deactivate tracing functionality.
SKILLFLAW_CELERY_ENABLED	Boolean	False	Enable Celery for distributed task processing.
SKILLFLAW_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 SkillFlaw servers, see SkillFlaw deployment overview.

Storage

For file storage environment variables, see File storage environment variables.

For database environment variables, including PostgreSQL configuration, see Memory management options.

Telemetry

See Telemetry.

Visual editor and Playground behavior

Variable	Format	Default	Description
SKILLFLAW_AUTO_SAVING	Boolean	True	Whether to automatically save flows.
SKILLFLAW_AUTO_SAVING_INTERVAL	Integer	1000	Set the auto-save interval in milliseconds if SKILLFLAW_AUTO_SAVING=True.
SKILLFLAW_BUNDLE_URLS	List[String]	[]	A list of URLs from which to load custom bundles. Supports GitHub URLs. If SKILLFLAW_AUTO_LOGIN=True, flows from these bundles are loaded into the database.
SKILLFLAW_COMPONENTS_PATH	String	Not set	Path to a directory containing custom components. Typically used when loading custom components from a local or managed runtime path.
SKILLFLAW_LOAD_FLOWS_PATH	String	Not set	Path to a directory containing flow JSON files to be loaded on startup. Typically used when preloading flows from a prepared runtime directory. Requires SKILLFLAW_AUTO_LOGIN=True.
SKILLFLAW_CREATE_STARTER_PROJECTS	Boolean	True	Whether to create templates during initialization. If false, SkillFlaw doesn't create templates, and SKILLFLAW_UPDATE_STARTER_PROJECTS is treated as false.
SKILLFLAW_UPDATE_STARTER_PROJECTS	Boolean	True	Whether to update templates with the latest component versions when initializing after an upgrade.
SKILLFLAW_LAZY_LOAD_COMPONENTS	Boolean	False	If true, SkillFlaw 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.
SKILLFLAW_EVENT_DELIVERY	String	streaming	How to deliver build events to the frontend: polling, streaming or direct.
SKILLFLAW_FRONTEND_PATH	String	./frontend	Path to the frontend directory containing build files. For development purposes only when you need to serve specific frontend code.
SKILLFLAW_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.
SKILLFLAW_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.
SKILLFLAW_MAX_TRANSACTIONS_TO_KEEP	Integer	3000	Maximum number of flow transaction events to keep in the database.
SKILLFLAW_MAX_VERTEX_BUILDS_TO_KEEP	Integer	3000	Maximum number of vertex builds to keep in the database. Relates to Playground functionality.
SKILLFLAW_MAX_VERTEX_BUILDS_PER_VERTEX	Integer	2	Maximum number of builds to keep per vertex. Older builds are deleted. Relates to Playground functionality.
SKILLFLAW_PUBLIC_FLOW_CLEANUP_INTERVAL	Integer	3600	The interval in seconds at which data for shared Playground flows are cleaned up. Default: 3600 seconds (1 hour). Minimum: 600 seconds (10 minutes).
SKILLFLAW_PUBLIC_FLOW_EXPIRATION	Integer	86400	The time in seconds after which a shared Playground flow is considered expired and eligible for cleanup. Default: 86400 seconds (24 hours). Minimum: 600 seconds (10 minutes).