Environment Variables

Environment variables lets you configure STELLA to your specific needs. This guide will walk you through each variable in the app/.env file, explaining its purpose and how to set it up.

Overview of .env File

The .env file contains key variables that influence the behavior of your STELLA instance. Here’s a look at the standard .env file structure:

# Environment Variables for STELLA
# To get started, run setup.py and follow the instructions.
# For detailed information, visit https://docs.stellaframework.com/ and search for "Environment Variables"
# ================================
# STELLA Configuration
# ================================
HOST=""                              # Host to run the server on
PORT="5001"                                 # Port to run the server on

BCRYPT_SALT=""                              # Generated by stella configure
JWT_SECRET_KEY=""                           # Generated by stella configure
JWT_ACCESS_TOKEN_EXPIRES="7"                # How long user access tokens will be valid (in days)

SOCK_SERVER_OPTIONS_PING_INTERVAL="150"     # time interval between each ping message (in seconds)
ASYNC_MODE="gevent"                         # gevent is recommended
FLASK_CONFIG="development"                  # development, production (development enables debug mode)

AGENT_MAX_DEPTH="999"                       # Max amount of calls for a single agent when solving a task
OVERALL_TASK_MAX_DEPTH="999"                # Maximum depth (agent calls) a task can have before it is stopped

# Dependencies
OPENAI_API_KEY=""                           # OpenAI API key can be found on your OpenAI profile page

# ================================
# Database Configuration
# ================================
DATABASE="sqlite"                           # sqlite, mongodb (default: sqlite, not recommended for production)

# >>> MongoDB Configuration (ignore if you are not using MongoDB) – note: MongoDB Atlas is recommended for production
MONGO_URI=""                                # URI to your MongoDB cluster
MONGO_DB_NAME=""                            # Name of the database to use

# >>> SQLite Configuration (ignore if you are not using SQLite)
SQLITE_DB_PATH="sqlite.db"                  # Path to the SQLite database file
# Note: If you change the database path, you should update .gitignore to ignore the new database path

# ================================
# Package Manager
# ================================

JWT and Security Keys

These keys are essential for securing user authentication and sensitive data within STELLA.

  1. JWT_SECRET_KEY: Used to encode and decode JWT tokens for user authentication. Generate it securely by running the setup.py script in the root folder.

  2. BCRYPT_SALT: Salt for bcrypt, used in hashing passwords and sensitive information. Also generated via setup.py.

  3. ADMIN_KEY: A special key for accessing admin API endpoints. Use the setup.py script to create a secure key.


You can run the setup.py script by running the following command in the root folder:

python setup.py

MongoDB Atlas Configuration

STELLA uses MongoDB Atlas for its database needs. Follow these steps to configure your MongoDB Atlas variables:

  1. MONGO_USERNAME: Your MongoDB Atlas username. Create an account on MongoDB Atlas to obtain this.

  2. MONGO_PASSWORD: Your MongoDB Atlas password.

  3. MONGO_URI: The URI provided by MongoDB Atlas for your database cluster.

  4. MONGO_DB: The name of your database within MongoDB Atlas.

Refer to MongoDB Atlas documentation for detailed setup instructions and security best practices.


Follow this MongoDB Atlas Tutorial to quickly get started with MongoDB Atlas.

OpenAI API Configuration

For AI functionalities, STELLA requires an OpenAI API key:

  1. OPENAI_API_KEY: Register on the OpenAI platform and retrieve your API key from the user dashboard.


You can find your OpenAI API key in your User Settings on OpenAI.

Application Configuration

Configure these variables based on your development or production environment.

  1. FLASK_CONFIG: Set to development for verbose logging during development or production for deployment.

  2. JWT_ACCESS_TOKEN_EXPIRES: Expiration time for JWT access tokens, in days. JWT access tokens are used for user authentication in STELLA.

  3. SOCK_SERVER_OPTIONS_PING_INTERVAL: Ping interval for the socket server in milliseconds.

  4. ASYNC_MODE: The mode of asynchronous operation for Flask-SocketIO. Default is gevent.