Load at boot

The store starts empty. The Python runtime has to fetch the ciphertext and decrypt it before env holds anything, and reading env.X before that raises NotLoadedError:

Envless env is not loaded yet. Import 'envless_env.register' or call load() first.

Importing envless_env or envless_env.server loads nothing by itself. There are two ways to make sure the load has happened before your code reads a variable.

Import envless_env.register first#

envless_env.register loads when it is imported and exports nothing. Make it the first import of your entry point, the module your server or worker imports before anything else, and every later import sees a loaded environment.

import envless_env.register  # noqa: F401
from envless_env.server import env

database_url = env.DATABASE_URL

If the load fails, the import raises the same LoadError that load() would, so a misconfigured process stops at boot instead of serving requests with a hole in its configuration.

Or call load() yourself#

from envless_env.server import env, load

record = load()
debug = env.DEBUG

load() returns a plain dict[str, str] of every decrypted value, a copy you own and may serialise. It is memoised: later calls return the same values without fetching again, and calls from several threads wait for one load instead of starting their own. A load that raises is not memoised, so the next call tries again.

In asyncio or trio code, await aload() does the same work in a worker thread, so the event loop keeps running while the key is derived and the values are fetched.

from envless_env.server import aload


async def startup() -> None:
    await aload()

The credentials it reads#

Get the machine key from Keys in the dashboard and the raw workspace key from machine access. With ENVLESS_TOKEN unset, the loader falls back to the token envless login stored on this machine, and since that is a session token it fails with ENVLESS_TOKEN must be a machine key (ev_sk_…). Create one in the Envless dashboard. The standalone loader is always machine authenticated.

The .envless file is the one envless link writes into your project folder. The loader reads it from the current working directory, so start your process from the folder that holds it, or set the three slugs as variables instead.

What a load does#

The process environment#

Decrypted values are written into os.environ without overwriting anything already set, so a variable from your shell or platform wins there, the way python-dotenv behaves by default. Libraries that read os.environ directly, such as boto3 or a database driver, keep working. The env object always hands back the Envless value.

Names that change how a process or its children execute code are never written into os.environ: NODE_OPTIONS, NODE_PATH, NODE_REPL_EXTERNAL_MODULE, ELECTRON_RUN_AS_NODE, LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, DYLD_FRAMEWORK_PATH, PATH, BUN_INSPECT, BUN_INSPECT_CONNECT_TO, RUBYOPT, RUBYLIB, BUNDLE_GEMFILE, GEM_HOME, GEM_PATH, PYTHONPATH, PYTHONHOME, PYTHONSTARTUP, PYTHONUSERBASE, PHPRC, PHP_INI_SCAN_DIR, ENVLESS_CLIENT_ENV and ENVLESS_INJECTED, whatever their case. A stored PYTHONPATH would otherwise decide what every child Python process imports: a subprocess, a multiprocessing worker, the development server's reloader. They are still decrypted and readable through env, and the loader logs a warning on the envless_env logger naming each one it skipped. With no logging configured, Python prints it to stderr, and -W error cannot turn it into a failed load.

Inside envless run#

When envless run or envless build starts your process, the CLI has already decrypted the values into the environment and written a manifest, ENVLESS_INJECTED, naming each variable with its type and visibility. The first time anything touches the store, the Python runtime adopts those names straight from os.environ: no ENVLESS_TOKEN, no key, no register import and no request.

envless run --env production -- python app.py

load() then returns the injected values without fetching. load(revalidate=True) deliberately escapes the seed and runs a real load, so it needs a machine key like any standalone load. See typed variables inside envless run for the manifest in detail. It is the same for both runtimes.

Reloading#

load(revalidate=True) skips the memo and the cache, fetches again, and replaces the values in env. In os.environ, a name a previous load wrote is updated, a name that has disappeared is removed, and a name that was already set from somewhere else is still left alone.

import logging
import signal
from types import FrameType

from envless_env import LoadError
from envless_env.server import load


def reload(signum: int, frame: FrameType | None) -> None:
    try:
        load(revalidate=True)
    except LoadError:
        logging.getLogger(__name__).exception('envless reload failed, keeping the old values')


signal.signal(signal.SIGHUP, reload)

Catch the error inside the handler. A signal handler runs in the middle of whatever the main thread was doing, so an exception that escapes it lands in your server loop.

The cache#

After a fetch, the ciphertext is written to ~/.envless/cache/, one file per product, project and environment, prefixed with the workspace when .envless names one, in the same format @goenvless/env writes, so a Node and a Python app on one machine share it. Only ciphertext is stored, never a decrypted value, in a folder with mode 0700 and files with mode 0600. Writing it is best effort: a failed write never fails the load. An entry older than 15 minutes, stamped in the future or written under another workspace is ignored. With ENVLESS_KEY, a load from the cache makes no request at all. With ENVLESS_PASSPHRASE it still resolves the workspace over the API and derives the key first. envless cache clear removes the entry for the current product, project and environment, and envless cache clear --all removes every one. Caching and reloads covers the details, which are identical in both runtimes.

Servers, workers and scripts#

When a load fails#

Every failure raises LoadError, with the API or network error as its __cause__ where there is one. The store and os.environ are left as they were, so after a failed reload env keeps the values of the last load that worked.