Static Folders

Static folder ingress rules serve files directly from a folder in the virtual filesystem — no script execution required. Use this for HTML pages, CSS, images, JavaScript bundles, and other static assets.

How It Works

1. An ingress rule with type STATIC_FOLDER maps a URL prefix to a folder in the virtual filesystem
2. When a request arrives, the engine resolves the relative path after the route prefix
3. It walks the virtual filesystem tree to find the matching file
4. The file is served with a Content-Type guessed from the filename
5. Directory requests serve index.html automatically

Key Differences from Script Ingress

Aspect	HTTP Ingress	Static Folder
scriptUUID points to	A script file	A folder tree item
Execution	Script runs per request	No script — file served directly
Content-Type	Set by Results chain	Auto-detected from filename
Index behavior	N/A	Serves index.html for directory URLs

Ingress rules reference UUIDs, not paths

The script_uuid in a STATIC_FOLDER rule is the UUID of the folder tree item — not its path or name. This means:

• Renaming a folder does not break the ingress — the UUID stays the same.
• Moving a folder to a different parent also keeps the ingress intact.
• Deleting a folder and creating a new one at the same path does break the ingress, because the new folder gets a fresh UUID.

When using build_deploy, the deploy directory is overwritten in-place (its contents are mirrored via rsync), so its UUID is always stable across redeployments. Agents should never rename or delete the deploy folder between redeployments.

Route Mapping

Given a static folder ingress with route /site pointing to a folder containing:

/my-website/
  index.html
  styles.css
  app.js
  images/
    logo.png

The following URLs are served:

URL	File served
/backend/site	index.html
/backend/site/	index.html
/backend/site/styles.css	styles.css
/backend/site/app.js	app.js
/backend/site/images/logo.png	images/logo.png

Serving at the Root Route (/)

A STATIC_FOLDER ingress with route / serves a full website at the domain root:

Ingress: STATIC_FOLDER, route = /
Folder:  /public-website/

/public-website/index.html   →  http://your-host/
/public-website/about.html   →  http://your-host/about.html
/public-website/css/main.css →  http://your-host/css/main.css

Script-backed handler rules (HTTP_GET, HTTP_POST, HTTP_DELETE) are always matched before STATIC_FOLDER rules, so API routes are never shadowed by a catch-all static folder at /.

Content-Type Detection

Content types are guessed from the file extension using Java's URLConnection.guessContentTypeFromName(). Common mappings:

Extension	Content-Type
.html	text/html
.css	text/css
.js	application/javascript
.json	application/json
.png	image/png
.jpg / .jpeg	image/jpeg
.svg	image/svg+xml
.pdf	application/pdf
.txt	text/plain

Use Cases

Single-Page Application

Serve a built SPA (React, Vue, etc.) by pointing a static folder at the build output:

/spa-app/
  index.html
  assets/
    main.js
    style.css

Marketing Site

Serve a static marketing site alongside your API endpoints:

Static folder ingress: / → /marketing-site/
HTTP GET ingress:      /api/contact → /ingresses/api/contact-form.js

Documentation

Host generated documentation (e.g., from a static site generator):

Static folder ingress: /docs → /documentation/

Filter Scripts

Static folder rules also support filter scripts via filterScriptUUID. The filter runs before the file is served. If the filter's handleRequest(context) returns a non-null IngressResult, the static file is not served and the filter's response is returned instead. Return null to allow the file to be served normally.

This is useful for protecting static sites behind authentication or restricting access to certain paths:

// /filters/require-login.js
export function handleRequest(context) {
  const cookie = context.getHeader("Cookie");
  const session = parseSession(cookie);

  if (!session) {
    return Results.redirect("/login");
  }

  return null; // allow the static file to be served
}

TIP

Static folders are the simplest way to serve frontend assets. They require no JavaScript handler code and are served directly from the virtual filesystem.