Virtual environments (encrypted JSON feed)

Virtual environments let a consumer read an environment without the CLI, SDK, or an API key, by fetching a self-describing encrypted JSON export from a public, branded URL and decrypting it with the workspace passphrase. It's the right fit for tools, scripts, and languages where installing @goenvless/cli or @goenvless/env isn't practical, but you still want the zero-knowledge guarantee.

Enable it (owner or admin)#

The URL shape#

Exposed environments are served under a branded, slug-based path built from your hierarchy (workspace → product → project → environment):

GET https://api.envless.cloud/exposed/<workspace-slug>/<product-slug>/<project-slug>/<environment-slug>/versions/latest
GET https://api.envless.cloud/exposed/<workspace-slug>/<product-slug>/<project-slug>/<environment-slug>/versions/<versionId>
GET https://api.envless.cloud/exposed/<workspace-slug>/<product-slug>/<project-slug>/<environment-slug>/versions

Pin a versionId when you want reproducible builds, and pin the uuid rather than the label: a label is derived from how many versions the environment has, v{count + 1} at publish time, so it describes a position rather than a fixed snapshot. Use latest when you always want the current published values.

On your own domain#

A workspace with an active custom domain serves the same feeds from its own hostname. The workspace is read from the hostname, so its slug drops out of the path:

GET https://vars.acme.com/exposed/<product-slug>/<project-slug>/<environment-slug>/versions/latest

Both hostnames serve at the same time, and the long form keeps working on your own domain when the workspace slug matches. A custom hostname is there for the feed, /exposed/* is the only surface meant to answer on it, and the rest of the API stays on api.envless.cloud. Add the DNS records with proxying off, the grey cloud on Cloudflare rather than the orange one, or your own zone answers the request and the feed never loads.

Fetch it#

The endpoint is public, so there's no Authorization header. It's a plain GET:

curl https://api.envless.cloud/exposed/acme/payments/billing-api/production/versions/latest

These routes use the same response envelope as the rest of the API, so the export is the data object, not the whole body. Read data, not the top level:

{
    "success": true,
    "code": 200,
    "message": "OK",
    "error": null,
    "data": { "format": "envless.encrypted-export/v1", "…": "…" },
    "_req": { "reqId": "0198…", "resTime": 12 }
}

A path that does not resolve answers 404 with one identical message, Not found, or this environment is not exposed., whatever the reason: a wrong slug, a deleted project, a private product, an environment with the toggle off, or a workspace with the feature off. Probing the URL space therefore tells an attacker nothing. The two exceptions are an environment that does resolve but has never been published, where latest answers 404 with This environment has no published version yet., and a Free workspace pinning a version older than its latest, which answers 402 plan.upgrade_required rather than 404.

Feeds are rate limited per client address: more than 600 requests in a minute from one address answers 429 with request.rate_limited and a Retry-After header, before anything is looked up. It bounds floods, not access: a client that hits it should wait the number of seconds in Retry-After and try again.

Response schema: envless.encrypted-export/v1#

The bundle describes its own crypto: it carries the encrypted values plus the KDF and cipher parameters you need to reproduce the key, PBKDF2 salt included. A consumer therefore needs nothing but the passphrase, and no lookup of the workspace unique id. The flip side is that the response alone is enough to start an offline guessing attack, which is why the passphrase is the whole perimeter here.

{
    "format": "envless.encrypted-export/v1",
    "workspace": { "slug": "acme" },
    "product": { "slug": "payments" },
    "project": { "slug": "billing-api" },
    "environment": { "slug": "production" },
    "version": {
        "id": "0192b7a1-4c62-7d19-8f03-2a6b5c4e9d71",
        "label": "v13",
        "note": "Before the Stripe migration",
        "variableCount": 2,
        "createdAt": "2026-07-22T10:00:00.000Z"
    },
    "decryption": {
        "note": "Derive the AES-GCM key from your workspace passphrase with the kdf below, then decrypt each value. Values prefixed `v2:` carry their own iteration count.",
        "kdf": {
            "algorithm": "PBKDF2",
            "hash": "SHA-256",
            "iterations": 200000,
            "keyLength": 256,
            "salt": "8Zt1nQ4rF2kXbY7uPq0dLw=="
        },
        "cipher": {
            "algorithm": "AES-GCM",
            "ivLength": 12
        },
        "ciphertextFormat": "v1:base64(iv|ciphertext)  |  v2:<iterations>:base64(iv|ciphertext)"
    },
    "variables": [
        {
            "name": "DATABASE_URL",
            "type": "string",
            "visibility": "server",
            "required": true,
            "value": "v1:iVBORw0KGgoAAAANSUhEUgAA…"
        },
        {
            "name": "PORT",
            "type": "number",
            "visibility": "server",
            "required": false,
            "value": "v1:R0lGODlhAQABAAAAACw…"
        }
    ]
}

Decrypt it#

Derive the AES-256 key from the workspace passphrase using the KDF params in the bundle, salt included, then AES-GCM-decrypt each value. The passphrase, or the raw key, is the only thing the consumer brings.

import crypto from 'node:crypto';

const passphrase = process.env.ENVLESS_PASSPHRASE;

const res = await fetch(
    'https://api.envless.cloud/exposed/acme/payments/billing-api/production/versions/latest'
);

// 1. the export is the `data` object of the envelope, never the whole body
const body = await res.json();
if (!res.ok || !body.success) throw new Error(body.message);

const bundle = body.data;
if (bundle.format !== 'envless.encrypted-export/v1') throw new Error('unexpected format');

// 2. the salt is served, base64 of 16 bytes. Nothing to look up, nothing to derive.
const salt = Buffer.from(bundle.decryption.kdf.salt, 'base64');

// 3. one key per distinct iteration count, cached. PBKDF2 is expensive on purpose,
//    so never derive it twice for the same count.
const keys = new Map();
const keyFor = (iterations) => {
    if (!keys.has(iterations)) {
        keys.set(iterations, crypto.pbkdf2Sync(passphrase, salt, iterations, 32, 'sha256'));
    }
    return keys.get(iterations);
};

// 4. read the cost off the envelope. v1 has none, so it uses the bundle default.
//    v2 states its own between 100000 and 1000000, and that is the one that applies.
function parseEnvelope(envelope) {
    if (envelope.startsWith('v2:')) {
        const rest = envelope.slice(3);
        const separator = rest.indexOf(':');
        if (separator === -1) throw new Error('unsupported variable format');

        const iterations = Number(rest.slice(0, separator));
        if (!Number.isInteger(iterations)) throw new Error('unsupported variable format');
        if (iterations < 100000 || iterations > 1000000) throw new Error('unsupported variable format');

        return { payload: rest.slice(separator + 1), iterations };
    }

    if (envelope.startsWith('v1:')) {
        return { payload: envelope.slice(3), iterations: bundle.decryption.kdf.iterations };
    }

    throw new Error('unsupported variable format');
}

// 5. decrypt each envelope: iv (12) ‖ ciphertext ‖ auth tag (16)
function decryptValue(envelope) {
    const { payload: encoded, iterations } = parseEnvelope(envelope);
    const payload = Buffer.from(encoded, 'base64');
    const iv = payload.subarray(0, 12);
    const tag = payload.subarray(payload.length - 16);
    const ct = payload.subarray(12, payload.length - 16);
    const d = crypto.createDecipheriv('aes-256-gcm', keyFor(iterations), iv);
    d.setAuthTag(tag);
    return Buffer.concat([d.update(ct), d.final()]).toString('utf8');
}

const env = Object.fromEntries(
    bundle.variables.map((v) => [v.name, decryptValue(v.value)])
);

import { decrypt } from '@goenvless/env/crypto';

// `/crypto` is the entrypoint to use here: pure Web Crypto, no node built-ins and no
// Buffer, so the same code runs in Node, a browser, a worker or an edge runtime. The root
// `@goenvless/env` entry exports an identical decrypt(), but it pulls in node:fs, so it is
// Node only. So are `/server`, `/next`, `/vite` and `/register`.
//
// decrypt() takes the workspace unique id rather than the salt the bundle serves, and
// derives the same salt itself: the first 16 bytes of SHA-256("envless:workspace:" + id).
// It reads the cost off each envelope and re-derives the key whenever a `v2:` value pins
// something other than 200000, so a bundle that mixes costs decrypts in one pass, exactly
// like the manual path.
// The id is not on any dashboard page; the CLI prints it in the ID column of
// `envless workspace list`.
const value = await decrypt(bundle.variables[0].value, passphrase, workspaceUniqueId);

If you provide ENVLESS_KEY (the raw base64url AES-256 key from the CI / Machine Access page) instead of a passphrase, skip steps 2 and 3 and decrypt directly with that key, imported raw as 32 bytes. No salt, no PBKDF2 pass, and nothing derived from a human-chosen string at read time, which makes it the better credential for an unattended consumer. From @goenvless/env/crypto that is importWorkspaceKey(material) to turn the base64url string into a CryptoKey, then decryptWithKey(key, envelope) per value. importWorkspaceKey rejects anything that does not decode to exactly 32 bytes.

Security model#