Environment Variables

SamaFlow support different environment variables to configure your instance. You can specify the following variables in the .env file inside packages/server folder. Refer to .env.example file.

For Database

For Storage

SamaFlow store the following files under a local path folder by default.

• Files uploaded on Document Loaders/Document Store
• Image/Audio uploads from chat
• Images/Files from Assistant
• Files from Vector Upsert API

User can specify STORAGE_TYPE to use AWS S3, Google Cloud Storage or local path

For Debugging and Logs

DEBUG: if set to true, will print logs to terminal/console:

LOG_LEVEL: Different log levels for loggers to be saved. Can be error, info, verbose, or debug. By default it is set to info, only logger.info will be saved to the log files. If you want to have complete details, set to debug.

Logs Streaming S3

When STORAGE_TYPE env variable is set to s3 , logs will be automatically streamed and stored to S3. New log file will be created hourly, enabling easier debugging.

Logs Streaming GCS

When STORAGE_TYPE env variable is set to gcs , logs will be automatically streamed to Google Cloud Logging.

For Credentials

SamaFlow store your third party API keys as encrypted credentials using an encryption key.

By default, a random encryption key will be generated when starting up the application and stored under a file path. This encryption key is then retrieved everytime to decrypt the credentials used within a chatflow. For example, your OpenAI API key, Pinecone API key, etc.

You can configure to use AWS Secret Manager to store the encryption key instead.

For some reasons, sometimes encryption key might be re-generated or the stored path was changed, this will cause errors like - Credentials could not be decrypted.

To avoid this, you can set your own encryption key as FLOWISE_SECRETKEY_OVERWRITE, so that the same encryption key will be used everytime. There is no restriction on the format, you can set it as any text that you want, or the same as your FLOWISE_PASSWORD.

INFO: Credential API Key returned from the UI is not the same length as your original Api Key that you have set. This is a fake prefix string that prevents network spoofing, that's why we are not returning the Api Key back to UI. However, the correct Api Key will be retrieved and used during your interaction with the chatflow.

For Models

In some cases, you might want to use custom model on the existing Chat Model and LLM nodes, or restrict access to only certain models.

By default, SamaFlow pulls the model list from here. However user can create their own models.json file and specify the file path:

For Built-In and External Dependencies

There are certain nodes/features within SamaFlow that allow user to run Javascript code. For security reasons, by default it only allow certain dependencies. It's possible to lift that restriction for built-in and external modules by setting the following environment variables:

```bash # Allows usage of all builtin modules TOOL_FUNCTION_BUILTIN_DEP=* # Allows usage of only fs TOOL_FUNCTION_BUILTIN_DEP=fs # Allows usage of only crypto and fs TOOL_FUNCTION_BUILTIN_DEP=crypto,fs # Allow usage of external npm modules. TOOL_FUNCTION_EXTERNAL_DEP=cheerio,typeorm ALLOW_BUILTIN_DEP=true ```

Using Built In Dependencies

WARNING: Some built-in dependencies, such as Puppeteer, may introduce potential security vulnerabilities. It is recommended to analyze and assess these risks carefully before using them.

NodeVM Execution Error: VMError: Cannot find module

If you are using library that is not allowed by default, you can either:

1. Allow all project's libraries/dependencies: ALLOW_BUILTIN_DEP=true
2. (Recommended) Specifically allow certain libraries/dependencies: TOOL_FUNCTION_EXTERNAL_DEP=cheerio,typeorm

Security Configuration

CUSTOM_MCP_SECURITY_CHECK=true

By default, this is enabled. When enabled, applies the following security validations:

• Command Allowlist: Only permits safe commands (node, npx, python, python3, docker)
• Argument Validation: Blocks dangerous file paths, directory traversal, and executable files
• Injection Prevention: Prevents shell metacharacters and command chaining
• Environment Protection: Blocks modification of critical environment variables (PATH, LD_LIBRARY_PATH)

CUSTOM_MCP_PROTOCOL

• stdio: Direct process communication (default, requires command execution)
• sse: Server-Sent Events over HTTP (recommended for production, more secure)

Recommended Production Settings

# Enable security validation (default)
CUSTOM_MCP_SECURITY_CHECK=true

# Use SSE protocol for better security
CUSTOM_MCP_PROTOCOL=sse

# Block dangerous domains (example)
HTTP_DENY_LIST=localhost,127.0.0.1,internal.company.com

# Blocks a hardcoded list of dangerous domains by default, but can be set to false to disable
HTTP_SECURITY_CHECK=true

# Enables checks on provided file and folder paths to prevent path traversal attacks
PATH_TRAVERSAL_SAFETY=true

WARNING: Warning: Disabling CUSTOM_MCP_SECURITY_CHECK allows arbitrary command execution and poses significant security risks in production environments.

HTTP_SECURITY_CHECK enables a built-in security feature that blocks a hardcoded list of dangerous domains. It is true by default and can be disabled by setting it to false.

HTTP_DENY_LIST allows you to specify an additional, custom list of domains to block. This list is empty by default.

PATH_TRAVERSAL_SAFETY enables a built-in security feature to prevent path traversal attacks on file and folder paths. It is true by default and can be disabled by setting it to false.

Examples of how to set environment variables

NPM

You can set all these variables when running SamaFlow using npx. For example:

npx samaflow start --PORT=3000 --DEBUG=true

Docker

docker run -d -p 5678:5678 samaflow \
 -e DATABASE_TYPE=postgresdb \
 -e DATABASE_PORT=<POSTGRES_PORT> \
 -e DATABASE_HOST=<POSTGRES_HOST> \
 -e DATABASE_NAME=<POSTGRES_DATABASE_NAME> \
 -e DATABASE_USER=<POSTGRES_USER> \
 -e DATABASE_PASSWORD=<POSTGRES_PASSWORD> \

Docker Compose

You can set all these variables in the .env file inside docker folder. Refer to .env.example file.