Environment variables

Arcjet uses several environment variables that influence its behavior. These are listed and explained in this article.

Arcjet recommends defining environment variables based on the guidance and best practices of your chosen framework and hosting provider e.g. use .env.local files in development and the secrets management of your hosting platform in production.

List of Arcjet environment variables

ARCJET_BASE_URL

URL to Arcjet Cloud API (string, default: "https://decide.arcjet.com"). Should only be set if directed by Arcjet support. Read by both the JS and Python SDKs. See Architecture: Cloud API for more info.

Note that when deployed to Fly.io the default is automatically changed to "https://fly.decide.arcjet.com", which is a dedicated endpoint that runs on on the Fly platform for lower latency.

ARCJET_ENV, NODE_ENV

Whether the app is running in development ("development" | "production", default: "production"). Arcjet is in development mode if either of these fields is set to "development" and production mode otherwise. NODE_ENV is a convention used in Node.js apps — the Python SDK reads ARCJET_ENV only.

In development, the timeout for connecting to Cloud API is increased. In production, the timeout is quicker. This is because in production your app typically runs close to an Arcjet server, but in development your app may run on your local machine, far away from Arcjet servers. See Architecture: API latency for more info.

In production, an error is logged when no client IP is found. In development, the local IP 127.0.0.1 is used as a fallback. When the client IP is missing (or local), geolocation and other IP lookup info will be empty. In development, an x-arcjet-ip header can be used to overwrite the client IP. This is because it’s useful to overwrite IPs for testing, but in production headers cannot be trusted as they can be set by malicious users.

The Arcjet Astro SDK uses ARCJET_ENV and the value at import.meta.env.MODE (from Vite) but does not use NODE_ENV.

ARCJET_KEY

Arcjet key for your site (string). In most cases, this variable name is a recommended convention. This value is not read automatically, unlike other variables, but should be retrieved manually from the environment and must be passed explicitly to Arcjet SDKs. See “How to read environment variables” for more info.

You can find your site key in the Arcjet dashboard. Select your site, select “SDK configuration”, then click to copy.

Arcjet keys are secrets that are always prefixed with ajkey_. As this is a secret, do not commit it to source control or otherwise expose it!

This value is read automatically when using the Arcjet Astro SDK. In the Python SDK, pass it explicitly to arcjet(key=...) or arcjet_sync(key=...) — typically read with os.environ["ARCJET_KEY"] or os.environ.get("ARCJET_KEY").

ARCJET_LOG_LEVEL

Log level to use ("debug" | "error" | "info" | "warn", default: "warn"). Setting for example warn will log warning and error messages. The order of log levels from most verbose to least verbose is debug, info, warn, error.

Read by both the JS and Python SDKs. The Python SDK applies this to the arcjet logger (logging.getLogger("arcjet")) and also accepts a numeric level like "10" (for DEBUG).

List of environment variables read by Arcjet

FIREBASE_CONFIG, FLY_APP_NAME, RENDER, VERCEL

Environment variables set by hosting platforms (string). These should not be set in .env files but are set automatically by the platforms where your app runs. Arcjet checks whether values are non-empty.

FIREBASE_CONFIG is set by Firebase, FLY_APP_NAME is set by Fly, RENDER is set by Render, and VERCEL is set by Vercel.

The inferred platform affects which request headers are trusted when determining the client IP. When Fly is detected, that affects the default value of ARCJET_BASE_URL.

The Python SDK only reads FLY_APP_NAME (to switch the default ARCJET_BASE_URL to the Fly endpoint). It does not read FIREBASE_CONFIG, RENDER, or VERCEL.

VERCEL_GIT_COMMIT_SHA

Git SHA of the commit the deployment was triggered by (string). This should not be set in .env files but VERCEL_GIT_COMMIT_SHA is automatically set by Vercel. When present in the Arcjet Next.js SDK, its value is sent to Arcjet Cloud API as part of the extra fields, which are displayed in the Arcjet dashboard. The Python SDK does not read this variable.

How to define environment variables

Arcjet recommends using .env.local files in development to set environment variables. Be sure to avoid committing any .env files that contain secrets to source control.

In production it is recommended to set environment variables using the dashboard provided by the platform where your app runs, and not to use .env files.

Node 20+ supports loading environment variables from a local file with --env-file. If you’re using an older version of Node, you can use a package like dotenv to load the environment variables from a .env.local file.

node --env-file .env.local index.js

In Python, the python-dotenv package is the standard way to load .env files. Call load_dotenv() before reading the variables:

from dotenv import load_dotenv

load_dotenv()  # Loads .env from the working directory

Flask and pydantic-settings load .env files automatically when python-dotenv is installed — see the framework-specific notes below.

How to load .env files

Whether .env files are loaded automatically and how to load them manually depends on the framework and runtime.

In Astro, Bun, Nuxt, Remix (in development), and SvelteKit (with adapter-node, in development) .env files are loaded automatically.

In Deno you can load .env files by running with the --env-file flag.

In Node.js (which includes Fastify, NestJS, and React Router) you can load a specific .env file by running with the --env-file=file flag.

In Next.js .env files are loaded automatically when using loadEnvConfig from @next/env.

In Flask both .env and .flaskenv files are loaded automatically by the flask CLI when python-dotenv is installed. .flaskenv is intended for public variables (e.g. FLASK_APP); .env for secrets and should be added to .gitignore.

In FastAPI .env files are loaded automatically when you use pydantic-settings and set model_config = SettingsConfigDict(env_file=".env") on your BaseSettings subclass. Otherwise call load_dotenv() from python-dotenv manually at module load time.

How to read environment variables

Arcjet reads most environment variables automatically. The ARCJET_KEY value is not read automatically, except in Astro. How to read it and other environment variables depends on your framework or runtime:

In Node.js and Bun you can read environment variables from process.env.

In Deno you can read environment variables with Deno.env.get().

In SvelteKit you can read environment variables from $env/dynamic/private and the like.

In Python you can read environment variables with os.environ. Use os.environ["ARCJET_KEY"] to raise a KeyError if the variable is missing, or os.environ.get("ARCJET_KEY") to return None. The Arcjet Python SDK does not read ARCJET_KEY automatically — you must pass it explicitly:

import os
from arcjet import arcjet

aj = arcjet(
    key=os.environ["ARCJET_KEY"],
    rules=[],
)

@arcjet/env

The JS SDKs use @arcjet/env to read info from the environment. To read values in the same way as the JS SDKs, for example to figure out whether Arcjet is in development mode, you can use this package.

There is no equivalent package for Python. The Python SDK reads environment variables directly via os.environ / os.getenv in arcjet/_client.py, arcjet/_context.py, and arcjet/_logging.py.