Skip to main content
Environment variables are retrieved first from your .env file (or any other file you specify when deploying, see down below), and if not found there, from the [env] section of blaxel.toml. This fallback mechanism allows for two kinds of variables:
  • secrets
  • simple environment variables

​
Secrets

Create a file named .env at the root of your project to store secrets. Blaxel will retrieve them from this default location upon deployment (see down below to override). Add the .env file to your .gitignore to prevent committing sensitive variables. 
MY_SECRET=123456
You can then use secrets in your code as follows: 

import { env } from "@blaxel/core";
console.info(env.MY_SECRET); // 123456

​
Use secrets from another env file

To separate local .env from production, specify a different environment file when deploying your resource to Blaxel using Blaxel CLI: 
bl deploy --env-file anyenvfile
This allows to specify a different environment file for production secrets instead of relying on the default .env, e.g.:
  • Use .env for local development
  • Use .env.prod for production deployment

​
Variables

You can define variables inside your agent or MCP server in the blaxel.toml file at root level of your project. These variables are NOT intended to be use as secrets, but as configuration variables.
blaxel.toml

name = "..."
workspace = "..."
type = "function"

[env]
DEFAULT_CITY = "San Francisco"
You can then use it in your code as follows: 

import { env } from "@blaxel/core";
console.info(env.DEFAULT_CITY); // San Francisco

​
Reserved variables

The following variables are reserved by Blaxel: PORT: Reserved by the system. BL_SERVER_PORT : Port of the HTTP server, it need to be set to allow Blaxel platform to configure it BL_SERVER_HOST : Host of the HTTP server, it need to be set to allow Blaxel platform to configure it Internal URL for Blaxel platform, to avoid linking multiple instance through the Internet BL_AGENT_${envVar}_SERVICE_NAME BL_FUNCTION_${envVar}_SERVICE_NAME BL_RUN_INTERNAL_HOSTNAME: internal run url Override URL to link multiple agents and MCP servers together locally BL_AGENT_${envVar}_URL BL_FUNCTION_${envVar}_URL Metadata automatically set by Blaxel platform in production BL_WORKSPACE : workspace name BL_NAME : name of the function or the agent BL_TYPE : function or agent Authentication environment variables BL_CLIENT_CREDENTIALS : client credentials, used by Blaxel in production with a workspaced service account BL_API_KEY : can be set in your code to connect with the platform (locally or from a server not on Blaxel platform) BL_LOG_LEVEL : Log level, default to info, can be set to debug,warn,error BL_DEBUG_TELEMETRY: Enable telemetry debug mode, will print each interaction with OpenTelemetry BL_ENABLE_OPENTELEMETRY: Enable OpenTelemetry, it’s set automatically by the platform in production
⌘I