Overview

DieselEngine is a self-hosted backend platform built on Spring Boot and GraalVM. Scripts are ES modules (ECMAScript 2023+) executed by the GraalVM JavaScript engine, with direct access to PostgreSQL, Redis, S3 storage, email, outbound HTTP, and more.

What Can Scripts Do?

Scripts in DieselEngine can:

• Serve HTTP requests — map URL routes to JavaScript handler functions
• Handle WebSocket connections — build real-time features with rooms and broadcast
• Run on a schedule — cron jobs with standard cron expressions
• Execute at startup — initialization scripts that run once when the engine boots
• Run on demand — triggered manually from the UI or via MCP tools
• Access databases — full JDBC with prepared statements, JSONB, and PostgreSQL arrays
• Connect to services — Redis, MinIO/S3, SMTP email, outbound HTTP
• Spawn agent runs — kick off autonomous LLM-powered tasks from code
• Interop with Java — call any Java class via Java.type()

Global Bindings

Every script execution receives these globals automatically:

Binding	Type	Description
diesel	DieselEngine	Main API: database, Redis, MinIO, email, PDF, crypto, file I/O
Results	ResultsProxy	HTTP response builder (ingress handlers)
okHttpClient	OkHttpClient	Outbound HTTP client (OkHttp 4)
RequestBody	Class	okhttp3.RequestBody for building HTTP request bodies
RequestBuilder	Class	okhttp3.Request.Builder for constructing HTTP requests
MediaType	Class	okhttp3.MediaType for MIME types
TimeUnit	Class	java.util.concurrent.TimeUnit
SQLType	Class	java.sql.SQLType for null parameter types
RedisClient	Class	Lettuce RedisClient (available in ingress handlers)

Your First Script

Here is a minimal HTTP ingress handler that returns JSON:

export function handleRequest(context) {
  return Results.json().renderRaw(JSON.stringify({
    message: "Hello from DieselEngine!",
    timestamp: Date.now()
  }));
}

To make this accessible at GET /api/hello, create an ingress rule mapping the route to this script. This can be done through the UI or via the MCP ingress_create tool.

Execution Modes at a Glance

Mode	Trigger	Entry Point
HTTP ingress	HTTP request matches a route	export function handleRequest(context) { ... }
WebSocket	Client connects to a WS route	export function onOpen/onMessage/onClose(session) { ... }
On-demand	User or agent triggers a run	Top-level module code
Cron job	Schedule fires	Top-level module code
Startup	Engine boots	Top-level module code

TIP

All execution modes share the same diesel API and global bindings. The only difference is how the script is triggered and what entry point it uses.

Console Output

console.log(), console.error(), and print() output appears in the DieselEngine UI console in real time. Script exceptions are also displayed with file and line information.

What's Next?

• Project Layout — how to organize your scripts
• Module System — ES module imports and resolution
• HTTP Ingress Handlers — serve HTTP requests
• Database (JDBC) — query PostgreSQL