Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 the --env-file argument in 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

​
Build variables

Build variables let you pass secrets and configuration values into the Docker build phase without exposing them at runtime. This is useful when your build process needs credentials that should never appear inside the deployed agent. Two options exist: .env.build for build secrets and blaxel.toml file for non-secret build variables.

​
.env.build

Create a .env.build file in the root of your project for build secrets. A common example of this is installing private npm packages, which require an NPM_TOKEN during npm install. Variables defined here are injected during the build phase only and are never persisted in the runtime environment.
.env.build
MY_SECRET_BUILD_VAR=I_AM_A_SECRET
Use the --build-env-file argument to bl deploy to specify a custom file name or path instead of the default .env.build.
Ensure that .env.build is ignored during commits to avoid accidentally making secrets public.

​
blaxel.toml

Non-secret build variables that can be placed in the blaxel.toml file, as in the example below:
blaxel.toml
type = "agent"
name = "my-agent"

[build.args]
MY_BUILD_VAR = "I_AM_NOT_A_SECRET"

​
Reserved variables

The following variables are reserved by Blaxel: PORT: Reserved by the system. PORT : Port of the HTTP server, it need to be set to allow Blaxel platform to configure it 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_REGION : default deployment region 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
Last modified on May 1, 2026