Skip to content

Workloads

View as Markdown

A workload is a bundle of content — a static site, an image set, a video library, a dataset, whatever you need to serve — packaged for delivery on the Edge Computing Cloud. When you deploy, your files are compressed and addressed by a content hash, then distributed to edge nodes so they can be served close to your users.

Every workload is published at one of three encryption levels, chosen per deployment target:

Level Name Who can read the content Best for
Level 0 Public Anyone with the URL Public static sites, public assets, anything you’d put on a normal CDN
Level 1 Encrypted Anyone with the URL and the key (key travels with the page) Content you want off-server but not indexable/hotlinkable without your embed code
Level 2 Double Only requests your backend has explicitly authorized Paid/gated content — course videos, licensed downloads, per-user access

If you’re not sure which to pick: start with Level 0. Reach for Level 1 or 2 only when you need to control who can access the content, not just where it’s hosted.


There are three ways to publish a workload. All three produce the same thing, so you can start with one and move to another.

How Best for Start here
The portal Trying it out, or sites you update by hand The steps below
The command line Publishing a build from your own computer with one command Command line (ee-cdn-cli)
CI, such as GitHub Actions Publishing automatically every time you push Deploying from GitHub Actions

If your site comes from a static site generator, see Static Site Generators for its output folder and the one routing setting it needs.

  1. Create a project. A project is the top-level container for a site or app — its files, deployment targets, and deploy history all live under it.
  2. Add your files. Drag and drop, select multiple files, upload a whole folder, or import directly from a URL (up to 100 MB per file).
  3. Create a deployment target. This defines what gets published, at what encryption level, and where — see Deployment targets below.
  4. Deploy. One click packages the files under your target’s root into a workload and publishes it, and gives you its live CDN URL. A package can be up to 1 GiB. The time it takes depends on how many files and photos you’re deploying, their size and their format: a site with hundreds of large photos takes several minutes.

Build your site, then publish it with ee-deploy, the command in the @evolving-edge/ee-cdn-cli npm package. It finds your generator’s output folder, or you can name it:

Terminal window
export EE_CDN_TOKEN=<your deploy token>
npx @evolving-edge/ee-cdn-cli ./dist --domain www.example.com --project proj_abc123

The same command runs in CI. A GitHub Actions workflow that builds and publishes on every push to main takes about 25 lines: see Deploying from GitHub Actions. You’ll need a deploy token, covered under Automating deploys.

Each deploy is content-addressed and immutable — deploying again creates a new workload and a new hash, without disturbing anything that already links to the previous one (see URLs and aliases).


A deployment target tells the platform what to build and publish. A project can have more than one — for example, a public marketing site at / and a gated members area at /members/.

Each target has:

Field Description
Name A label for the target (e.g. main, members-area).
Deployment Root The folder (prefix) within your project’s files to publish. / publishes everything.
Encryption None (Level 0), Encrypted (Level 1), or Double (Level 2).
Domain An optional custom domain to serve this target on (see Custom domains).

Click Deploy on a target whenever you want to publish the current state of its files. Every deploy is recorded in that target’s history with its content hash, file count, size, and timestamp, so you can always see — and link back to — exactly what was live at a given point in time.

Configuring a target from your files: ee.jsonc

Section titled “Configuring a target from your files: ee.jsonc”

If you’d rather define a target’s settings alongside your content instead of through the UI, drop an ee.jsonc file in the folder you want to publish:

ee.jsonc
{
"name": "main",
"encryptionLevel": "level1",
"domain": "app.example.com",
"exclude": ["**/*.map", "drafts/**"],
"autoBuild": false
}
Field Description
name Target name.
encryptionLevel level0, level1, or level2.
domain Custom domain for this target.
include / exclude Glob patterns to filter which files are packaged.
autoBuild Reserved for automatic redeploys on file changes.
images Convert JPEG and PNG images to WebP or AVIF when you publish with ee-deploy. See Images.

An ee.jsonc at your project root configures the root (/) target; one inside a subfolder configures a target scoped to that subfolder. Settings in ee.jsonc take precedence over the target’s saved configuration, so you can version content settings alongside the content itself.


No encryption. Content is compressed and served as-is — this is a conventional CDN experience. Use it for anything meant to be publicly accessible: marketing sites, public documentation, open datasets, static assets.

Deploying a Level 0 target gives you a CDN URL immediately — nothing further to configure.

Content is encrypted before it ever leaves our storage. The decryption key travels separately from the content — embedded in your page via a small script tag, or appended to a URL as a fragment (#key=...) — and the browser decrypts it locally using the EE SDK. Edge nodes and regional gateways only ever see and cache ciphertext.

This is useful when you want content off conventional hotlinking/scraping paths, or delivered only through your own page rather than served as a bare public file — without standing up your own auth backend.

What you get after deploying a Level 1 target:

  • A CDN URL for the deployed site.

  • If your deploy includes an index.html, the SDK <script> tag and key are injected into it automatically — the page decrypts itself, no extra work needed.

  • An embed code for embedding individual encrypted assets elsewhere:

    <script src="https://cdn.example.com/ee.js"
    data-hash="<content-hash>"
    data-key="<encryption-key>"></script>
  • The encryption key itself, shown once in the portal. Treat it like a secret you’re deliberately handing to your own frontend — anyone who has it can decrypt the content, by design. Don’t commit it to a public repo unless that’s the intent.

See Browser SDK below for programmatic use (fetching files directly, video playback).

Level 2 — Double (zero-trust, server-authorized)

Section titled “Level 2 — Double (zero-trust, server-authorized)”

The strongest option: content is encrypted, and the decryption key never reaches the browser at all. Instead, your backend authorizes each viewer individually:

  1. Your server calls the control plane to request a short-lived access token for the workload:

    POST /api/access-token
    { "workloadHash": "<hash>", "userAuth": "<your API key or user auth>" }
    → { "accessToken": "<opaque token>", "expiresIn": 30, "tokenId": "..." }

This token is opaque and contains no key material — it just proves to the edge that this specific request is authorized, and it expires in seconds.

  1. The browser sends that token to the edge node when requesting content:

    GET /ee/<hash>/<path>
    X-EE-Access-Token: <opaque token>
  2. The edge node validates the token with the control plane. Only if it’s valid does the control plane hand the edge node the decryption key — never the browser — and the edge decrypts and serves the plaintext.

Because the key only ever exists server-side (your backend and our control plane and regional gateways), this level is appropriate for content you’re actually gating — paid courses, licensed video, per-user downloads — where “the link is on a page only paying users see” isn’t a strong enough guarantee.

There’s no bare public URL for a Level 2 target’s content — access is always mediated by your backend issuing tokens per request/session. Budget for this integration work up front; it’s a deliberate tradeoff for real access control rather than obscurity.


Every deploy is reachable multiple ways, from most to least specific:

URL type Example Stability
Custom domain https://app.example.com/ Stable — always points at your latest deploy to that target, once the domain is claimed and active.
Latest URL (mutable alias) https://ee-myapp-main.evolvingedge.ai/ Stable — one per deployment target, automatically repoints to each new deploy. Use this for “the current version,” e.g. in your own links or embeds.
Version URL (per-deploy alias) https://ee-happy-fox.evolvingedge.ai/ Immutable — pins to the exact workload from one specific deploy. Never changes, even after you deploy again. Good for sharing a specific snapshot or rolling back by re-pointing your custom domain.
Hash URL https://ee-<content-hash>.evolvingedge.ai/ Immutable — the raw content address. Always works as a fallback.

Level 2 targets don’t expose a direct browsable URL — see Level 2 above.

Serve a deployment target on your own domain by setting the target’s Domain, claiming the domain for your project, and adding two DNS records that prove it’s yours. A certificate is issued automatically. A domain belongs to one project at a time, and only that project can deploy to it.

See Custom domains for the steps.

——|——|—––| | CNAME | app.example.com | (shown in the portal once you set a domain) |

DNS propagation is typically fast, but can take longer depending on your registrar and existing TTLs. Once it resolves, the custom domain always serves your target’s most recent deploy.


For anything beyond dropping in the auto-injected <script> tag, use the @ee-cdn/client SDK to fetch and decrypt Level 1 content programmatically:

import { createEEClient } from "@ee-cdn/client";
import init, { decompress } from "brotli-wasm";
await init();
const client = createEEClient("https://cdn.example.com");
client.setBrotliDecompress(decompress);
// Fetch and decrypt a single file — key comes from the URL fragment
const data = await client.fetch("/ee/<hash>/app/main.js#key=<encryption-key>");
// List everything in the workload
const index = await client.getIndex("/ee/<hash>/#key=<encryption-key>");

Level 1 video is decrypted incrementally as it streams, rather than requiring the whole file up front:

import { createEEVideoPlayer } from "@ee-cdn/client";
const player = createEEVideoPlayer(videoElement, client);
await player.load("/ee/<hash>/video.mp4#key=<encryption-key>");

For CI/CD or scripted publishing, create a Deploy Token instead of deploying by hand through the portal, and publish with the command line:

  • Scope a token globally or to a single project.
  • Grant it workload:write (deploy content) and/or release:write as needed.
  • Tokens can be revoked at any time from the portal; revoking immediately invalidates it.

If your project is built with Astro, the ee-cdn integration wraps this whole flow — including stable-key caching, so republishing unchanged content doesn’t rotate encryption keys or produce needless new deploys — into your normal npm run build. See Astro on the command-line page.


This draft covers content and delivery. Not yet included, to follow in a later pass:

  • Account, workspace, and team member management
  • Billing and usage
  • Support channels and SLAs

Reviewer notes welcome — especially on terminology (e.g. “Deployment Target” vs. “Deploy Target” vs. something else), how much of the Level 2 token flow to show vs. link out to an API reference, and whether the Astro integration deserves its own full page rather than a pointer.

Next: Command line (ee-cdn-cli) >