# Workloads

> Create projects and deployment targets, choose an encryption level, and deploy workloads to the Evolving Edge network.

Source: https://docs.evolvingedge.ai/workloads/

## What is a workload?

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.

---

## Quick start

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)](https://docs.evolvingedge.ai/cli/) |
| **CI, such as GitHub Actions** | Publishing automatically every time you push | [Deploying from GitHub Actions](https://docs.evolvingedge.ai/cli/#deploying-from-github-actions) |

If your site comes from a static site generator, see [Static Site Generators](https://docs.evolvingedge.ai/static-sites/) for its output folder and the one routing setting it needs.

### In the portal

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](#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](https://docs.evolvingedge.ai/cli/#size-limit). 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.

### From the command line or CI

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:

```sh
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](https://docs.evolvingedge.ai/cli/#deploying-from-github-actions). You'll need a deploy token, covered under [Automating deploys](#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](#urls-and-aliases)).

---

## Deployment targets

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](https://docs.evolvingedge.ai/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`

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:

```jsonc
// 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](https://docs.evolvingedge.ai/image-conversion/#options). |

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.

---

## Encryption levels in depth

### Level 0 — Public

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.

### Level 1 — Encrypted (client-side)

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:

  ```html
  <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](#browser-sdk-level-1) below for programmatic use (fetching files directly, video playback).

### 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.

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

   ```
   GET /ee/<hash>/<path>
   X-EE-Access-Token: <opaque token>
   ```

3. 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.

---

## URLs and aliases

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](#level-2--double-zero-trust-server-authorized) above.

### Custom domains

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](https://docs.evolvingedge.ai/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.

---

## Browser SDK (Level 1)

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

```ts
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>");
```

### Video playback

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

```ts
import { createEEVideoPlayer } from "@ee-cdn/client";

const player = createEEVideoPlayer(videoElement, client);
await player.load("/ee/<hash>/video.mp4#key=<encryption-key>");
```

---

## Automating deploys

For CI/CD or scripted publishing, create a **Deploy Token** instead of deploying by hand through the portal, and publish with the [command line](https://docs.evolvingedge.ai/cli/):

- 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](https://docs.evolvingedge.ai/cli/#astro) on the command-line page.

---

## What's next

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) >](https://docs.evolvingedge.ai/cli/)
