Concepts

What is Envless#

Envless is an end-to-end encrypted secrets manager that replaces .env files. It encrypts every variable on your device before upload, so the server only ever stores ciphertext, then versions, audits and syncs them across local, staging, production and CI through a CLI, typed SDKs for TypeScript, Python and Ruby, and a REST API.

The path a variable takes#

Put differently, Envless is a sync layer for environment variables. You manage variables in the dashboard; your machines pull them down, decrypted locally. There are three ways to do that pull, and which one you pick depends on where the code runs.

Three ways to sync#

When to pick which#

They're not mutually exclusive. A typical setup uses import in app code, sync for the docker-compose dev stack, and run in CI.

What makes them work#

The first two pieces below are shared by all three modes, with one exception: the @goenvless/env/edge loader has no filesystem, so it takes the same binding and key material as arguments instead. The third one shapes what the runtime import exposes, and only the runtime import: sync and run hand over every variable whatever its visibility.

The .envless file#

A small JSON file you commit to your repo. It tells Envless what to fetch (workspace, product, project, and one or more environments) and contains no secrets.

{
    "workspace": "acme",
    "product": "payments",
    "project": "my-app",
    "environments": ["development", "staging"]
}

Created by envless link. Safe to commit and share.

The workspace key#

Envless is end-to-end encrypted. The server stores ciphertext only; decryption happens on your machine with a key derived from a workspace passphrase.

Server vs client split#

Every variable has a visibility flag, either server (default) or client. The runtime, @goenvless/env, splits its application surface in two:

import { env } from '@goenvless/env/server';  // all variables
import { env } from '@goenvless/env/client';  // client-flagged only

Server secrets can't end up in a client bundle. That's enforced by types, runtime, bundler, and lint. See Server vs Client.

Those two are the whole application surface. The bare @goenvless/env entry is neither of them: it is untyped and unfiltered, so it hands back server values as well. It is there for load(), encrypt(), decrypt(), passphraseStrength() and ENCRYPTION_PARAMETERS, not for reading variables in application code, and it drags the Node-only loader in with it.

When you want the crypto without the loader, import @goenvless/env/crypto. It is pure Web Crypto with no node: built-ins and no Buffer, so it runs anywhere, and it exports encrypt, decrypt, encryptWithKey, decryptWithKey, workspaceKey, importWorkspaceKey, passphraseStrength and ENCRYPTION_PARAMETERS.

/server fetches nothing on import. Nothing loads until you preload @goenvless/env/register or await load(), and reading a name before that throws. /client needs no load call, because it seeds itself from the payload the Next or Vite plugin inlined at build time.

/server also reaches the loader, which reads .envless and the on-disk cache through node:fs, so it only runs on Node and Bun. The bare . entry and the /next, /vite and /register entrypoints inherit the same constraint. On an edge runtime or a Worker, call load() from @goenvless/env/edge with { token, project, environment } plus either passphrase or key, and optionally product, workspaceId, endpoint and fetch. It resolves a plain record you own: it writes nothing into process.env and keeps no cache.

How a sync actually flows#

┌────────────────────────────────────────┐
│  Dashboard (you manage variables here) │
└──────────────────┬─────────────────────┘
                   │  encrypted blobs
                   ▼
┌────────────────────────────────────────┐
│        Envless API (ciphertext only)   │
└──────────────────┬─────────────────────┘
                   │  fetch (auth: env_cli_ or ev_sk_ token)
                   ▼
┌────────────────────────────────────────┐
│  Your machine                          │
│    .envless                ← binding   │
│    ~/.envless/config.json  ← CLI key   │
│    ENVLESS_KEY/PASSPHRASE  ← runtime   │
│                                        │
│    decrypt locally, then:              │
│      • import { env }     (runtime)    │
│      • write .env.<slug>  (sync)       │
│      • inject into child  (run)        │
└────────────────────────────────────────┘

One pipeline above the bottom box; three ways out of it. The runtime import is the only mode that caches: it keeps the ciphertext under ~/.envless/cache and reuses it for 15 minutes before it refetches. sync, run and @goenvless/env/edge always fetch.

Twenty-six names never reach a process environment. Twenty-four of them change how a process or its children execute code, so storing one would turn write access to a variable into code execution: 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 and PHP_INI_SCAN_DIR. The last two are Envless channels: ENVLESS_CLIENT_ENV, which the Next and Vite plugins use to hand the client payload to the browser, and ENVLESS_INJECTED, the manifest envless run writes so a child process can seed its typed store without credentials. They are still decrypted, still readable off env, and still present in the record load() resolves; the runtime just refuses to write them into process.env, and run refuses to hand them to the child. Both warn when they drop one. A child process env is therefore the ambient environment merged with the decrypted values minus those twenty-six names, not a plain merge of the two.

The runtime narrows it further. A name already present in process.env that the loader does not own is left alone, so a variable exported in your shell or set by your platform wins over the fetched value. Names the loader did set on an earlier load() and that are gone from the new fetch are deleted. Whatever it skips is still on env, so read it from there rather than from process.env.

Consuming without an Envless package: Virtual Envs#

Sometimes the consumer can't install any of the three packages: a tool in another language, a build step you don't control, a runtime with no package manager. A serverless or edge function is usually not one of those, since @goenvless/env/edge and @goenvless/env/crypto run there. For the consumers that really are stuck, a member who can update the workspace (owners and admins by default) can turn on Virtual Envs (Settings → /settings/virtual-envs) and then expose specific environments one at a time.

An exposed environment serves its encrypted variables as self-describing JSON at a branded, guessable URL:

GET <api-base>/exposed/<workspace-slug>/<product-slug>/<project-slug>/<environment-slug>/versions/latest
GET  .../versions/<versionId>   # pin a version by its id or its label (v3)
GET  .../versions               # list published versions (metadata only)

The response (format: "envless.encrypted-export/v1") carries the ciphertext values plus the KDF and cipher params (PBKDF2 200,000 / SHA-256 / AES-GCM-256, 12 byte IV) and the KDF salt, which is base64 of the first 16 bytes of SHA-256 over envless:workspace:<workspace-unique-id>. Each value is either v1:base64(iv|ciphertext) or v2:<iterations>:base64(iv|ciphertext), and a v2: value pins its own iteration count, which replaces the 200,000 in the bundle for that value alone. The bundle never carries the key or the passphrase, and in it workspace, product, project and environment appear as slugs only, with no unique ids and no display names; the version carries its id, label, note, variable count and creation time. In JavaScript, feed each value to @goenvless/env/crypto's decrypt() or @goenvless/sdk's decryptValue(), which both take the ciphertext, the workspace passphrase, and the workspace unique id they derive the salt from, and both re-derive at the pinned cost when they meet a v2: value. In Python, decrypt_value() from envless-sdk does the same. Anywhere else, reimplement the recipe from the parameters in the bundle.

Publishing the shape without the values: example links#

A second, much quieter public feed serves an environment's variable names with every value blank, the file you would otherwise hand-write as .env.example. It is opt-in per environment (Environment settings → Example link) and, unlike Virtual Envs, needs no workspace-level switch. Private products can never publish one.

GET <api-base>/example/<workspace-slug>/<product-slug>/<project-slug>/<environment-slug>/versions/current
GET  .../versions/latest        # the newest published version
GET  .../versions/<versionId>   # pin a version by its id or its label (v3)
GET  .../versions               # list published versions (metadata only)

The response (format: "envless.env-example/v1") carries no ciphertext and no decryption block, because there is nothing to decrypt: each variable is name, an empty value, plus type, visibility, required and secret. Opening the URL in a browser returns a copyable page instead of JSON, and ?format=env returns a raw .env.example. See Example links.

Beyond syncing: API and SDK#

Envless also ships a REST API and programmatic SDKs for TypeScript, @goenvless/sdk, for Python and Ruby, both published as envless-sdk, and for PHP, envless/sdk. None of them is for getting variables into your app, that is the runtime's job. They're for advanced workflows like building tools on top of Envless: writing custom dashboards, scripting workspace/project/variable management, integrating with internal platforms, or automating bulk operations across many projects.

~99% of apps never need these. If you're just trying to use your variables (import them, sync them to a file, or wrap a process), stick with the three modes above. Reach for the API or SDK only when you're building on top of Envless rather than using it.

Glossary#

Quick reference for the resource model you'll see in the dashboard and the .envless file:

Going deeper#

The encryption model on this page is covered end to end, with the exact key-derivation parameters and the test vectors that pin them, on the Envless site.