Skip to content

Runtime registry

backend/app/runtime_registry.py is the one place that says which languages and versions run, which image each one uses and how the pod starts the script. The API validates requests against it, the k8s worker builds pods from it, and the frontend reads it through GET /api/v1/k8s-limits.

Languages and versions

LANGUAGE_SPECS: dict[str, LanguageSpec] = {
    "python": {
        "versions": ["3.14", "3.13", "3.12", "3.11"],
        "image_tpl": "python:{version}-slim",
        "file_ext": "py",
        "interpreter": ["python"],
    },
    "node": {
        "versions": ["26", "24", "22"],
        "image_tpl": "node:{version}-alpine",
        "file_ext": "js",
        "interpreter": ["node"],
    },
    "ruby": {
        "versions": ["4.0", "3.4", "3.3"],
        "image_tpl": "ruby:{version}-alpine",
        "file_ext": "rb",
        "interpreter": ["ruby"],
    },
    "bash": {
        "versions": ["5.3"],
        "image_tpl": "bash:{version}",
        "file_ext": "sh",
        "interpreter": ["bash"],
    },
    "go": {
        "versions": ["1.27", "1.26"],
        "image_tpl": "golang:{version}-alpine",
        "file_ext": "go",
        # exec keeps the PID, so the entrypoint measures the program instead of the go tool that built it
        "interpreter": [
            "sh",
            "-c",
            'go build -o /tmp/main -ldflags="-s -w" -gcflags=all=-dwarf=false "$0" && exec /tmp/main',
        ],
        # A cold build compiles the runtime and std into GOCACHE: about 50Mi of /tmp, 230Mi RSS, 10s of CPU.
        "pod": PodRuntimeConfig(
            env={"HOME": "/tmp", "GOCACHE": "/tmp/go-cache"},  # NOSONAR  # nosec B108
            tmp_size="64Mi",
            min_cpu="1000m",
            min_memory="320Mi",
            min_timeout_seconds=30,
        ),
    },
}

Each entry follows this shape:

class LanguageSpec(TypedDict):
    versions: list[str]
    image_tpl: str
    file_ext: str
    interpreter: list[str]
    pod: NotRequired[PodRuntimeConfig]

The registry offers only versions that upstream still supports, and lists them newest first. Today that is Python 3.14, 3.13, 3.12 and 3.11, Node 26, 24 and 22, Ruby 4.0, 3.4 and 3.3, Go 1.27 and 1.26, and Bash 5.3. A unit test in tests/unit/app/test_runtime_registry.py pins that order.

DEFAULT_LANG is "python" and DEFAULT_LANG_VERSION is the first Python version, so 3.14 today. Every lang and lang_version default in the schemas, domain models and documents reads these two constants, except in the saved-script update models, where both default to None so an update leaves them alone.

From spec to pod

_make_runtime_configs() turns each language and version into a RuntimeConfig:

class RuntimeConfig(NamedTuple):
    image: str  # Full Docker image reference
    file_name: str  # Name that will be mounted under /scripts/
    command: list[str]  # Entrypoint executed inside the container

The file is always main.{file_ext}, and the command is the interpreter plus /scripts/main.{file_ext}, so Python 3.12 gets python:3.12-slim and ["python", "/scripts/main.py"]. ExecutionService copies image, command and file name into the ExecutionRequestedEvent, and the k8s worker builds the pod from that event.

The worker puts the script into a ConfigMap, mounts it read-only at /scripts, and starts the container as /bin/sh /entry/entrypoint.sh <command>. The entrypoint runs the command as plain arguments, with no shell in between. On startup the worker also runs a pre-puller DaemonSet that pulls every image in the registry.

Per-language pod settings

Most languages get the same pod. A language that needs more sets pod to a PodRuntimeConfig, which carries extra env vars, the size of the /tmp emptyDir (10Mi by default) and minimums for CPU limit, memory limit and timeout, which default to zero. PodBuilder applies one rule: the effective value is the larger of the configured limit and the language minimum. The configured limits come from the admin system settings, which fall back to K8S_POD_CPU_LIMIT, K8S_POD_MEMORY_LIMIT and K8S_POD_EXECUTION_TIMEOUT. Requests aren't touched.

Go is the only language with settings today. It builds and runs the way the Rust example below does, go build into /tmp and then exec, so the entrypoint measures the program and not the go tool; go run would report the go tool's own 25MB and leave the program out. A cold build compiles the runtime and standard library first, so Go pods get HOME=/tmp and GOCACHE=/tmp/go-cache (the root filesystem is read-only), 64Mi of /tmp, and at least 1000m CPU, 320Mi memory and 30 seconds.

GET /api/v1/k8s-limits reports the configured limits at the top level and the effective ones per language under language_limits. The editor shows the entry for the selected language. The result processor rates peak memory against the same effective limit, and parse_quantity and at_least in the registry are the one copy of that rule for all three.

Dropped versions

A version that leaves the list stops working everywhere:

  • POST /api/v1/execute rejects it with 422 while validating ExecutionRequest.
  • POST /api/v1/executions/{execution_id}/retry raises RuntimeNotSupportedError, which is a 422.
  • Creating or updating a saved script with it raises the same 422.

The editor doesn't send one. On load it swaps a stored version that's gone for the newest offered version of that language, the first one the API lists, and if the language itself is gone it takes the first language the API returns. Opening a saved script with a dropped version makes the language picker switch to the newest version and say so in a toast.

Example scripts

GET /api/v1/example-scripts returns one starter script per language, and the editor's example button loads the one for the selected language. Every script runs on every offered version. A feature older than the oldest offered version is used directly. A newer one is checked first: Python looks for itertools.batched, Node for RegExp.escape, Ruby for Array#fetch_values, and Bash compares BASH_VERSINFO. Go can't check at runtime, so its script sticks to what Go 1.26 has.

EXAMPLE_SCRIPTS
EXAMPLE_SCRIPTS: dict[str, str] = {
    "python": """\
import itertools
import platform

print(f"Hello from a Python {platform.python_version()} script!")


# Structural pattern matching and X | Y unions work on every offered version (3.11+).
def process_data(value: int | str | None) -> str:
    match value:
        case None:
            return "No value"
        case int() if value > 10:
            return f"Big number: {value}"
        case _:
            return f"Got: {value}"


print(process_data(42))
print(process_data("hello"))
print(process_data(None))

# itertools.batched() arrived in Python 3.12, so check for it first.
if hasattr(itertools, "batched"):
    print(f"itertools.batched() is available (Python 3.12+): {list(itertools.batched('abcdef', 2))}")
else:
    print("itertools.batched() is not available on this version (needs Python 3.12+).")
""",
    "node": """\
console.log(`Hello from Node.js ${process.version}!`);

// Promise.withResolvers() (Node.js 22+) works on every offered version.
const { promise, resolve } = Promise.withResolvers();
promise.then((msg) => console.log(`Promise.withResolvers() resolved with: ${msg}`));
resolve('Success');

// RegExp.escape() arrived in Node.js 24, so check for it first.
if (typeof RegExp.escape === 'function') {
  console.log(`RegExp.escape() is available (Node.js 24+): ${RegExp.escape('(1+1)?')}`);
} else {
  console.log('RegExp.escape() is not available on this version (needs Node.js 24+).');
}
""",
    "ruby": """\
puts "Hello from Ruby #{RUBY_VERSION}!"

# Data objects (Ruby 3.2+) work on every offered version.
Point = Data.define(:x, :y)
point = Point.new(x: 1, y: 2)
puts "Data objects are supported. Created point: #{point.inspect}"

# Array#fetch_values arrived in Ruby 3.4, so check for it first.
if [].respond_to?(:fetch_values)
  puts "Array#fetch_values is available (Ruby 3.4+): #{%w[a b c].fetch_values(0, 2).inspect}"
else
  puts "Array#fetch_values is not available on this version (needs Ruby 3.4+)."
end
""",
    "bash": """\
echo "Hello from Bash version $BASH_VERSION"
echo "Bash major version: ${BASH_VERSINFO[0]}"
echo "Bash minor version: ${BASH_VERSINFO[1]}"

# The ${var@U} uppercase expansion (Bash 5.1+) works on every offered version.
my_var="hello"
echo "Original: $my_var, Uppercased: ${my_var@U}"

# ${ command; } runs a command substitution without a subshell (Bash 5.3+), so check the version first.
if (( BASH_VERSINFO[0] > 5 || (BASH_VERSINFO[0] == 5 && BASH_VERSINFO[1] >= 3) )); then
    counter=1
    result=${ counter=2; echo "no subshell"; }
    echo "Command substitution ran with $result, counter is now $counter (Bash 5.3+)"
else
    echo "The \\${ command; } substitution is not available in this Bash version (needs Bash 5.3+)."
fi
""",
    "go": """\
package main

import (
    "fmt"
    "runtime"
)

// Generics (Go 1.18+) work on every offered version.
func Print[T any](s T) {
    fmt.Println(s)
}

func main() {
    Print(fmt.Sprintf("Hello from Go version %s!", runtime.Version()))

    // The clear() builtin (Go 1.21+) empties maps and slices.
    myMap := map[string]int{"a": 1}
    Print(fmt.Sprintf("Map before clear: %v", myMap))
    clear(myMap)
    Print(fmt.Sprintf("Map after clear: length is %d", len(myMap)))

    // new() accepts an expression since Go 1.26.
    answer := new(len(myMap) + 42)
    Print(fmt.Sprintf("new(expr) (Go 1.26+) points to %d", *answer))
}
""",
}

Adding a language

  1. Add an entry to LANGUAGE_SPECS with versions newest first, and a pod config if the defaults aren't enough.
  2. Add a script to EXAMPLE_SCRIPTS that runs on every listed version.
  3. Add a loader for the language's CodeMirror mode in frontend/src/lib/editor/languages.ts. It's a dynamic import(), so the mode loads only when someone picks the language. Without one the editor shows plain text.

Request validation, SUPPORTED_RUNTIMES, the version picker, file upload by extension and the image pre-puller all derive from the registry.

A compiled language needs a build step before the run, and the command has no shell to chain them. Wrap both in sh -c and let the appended script path arrive as $0. For Rust, whose upstream supports only the latest stable release:

"rust": {
    "versions": ["1.99"],
    "image_tpl": "rust:{version}-slim",
    "file_ext": "rs",
    # The registry appends /scripts/main.rs, which sh hands to the script as $0.
    "interpreter": ["sh", "-c", 'rustc -C strip=symbols -o /tmp/main "$0" && exec /tmp/main'],
},

There's no {file} placeholder: the path is always appended as the last argument. The binary goes to /tmp because the root filesystem is read-only, and -C strip=symbols keeps it small: a hello world comes out at about 340KB instead of 4.4MB. Under the default pod (10Mi of /tmp, 128Mi, 1000m) that build takes about 0.2 s and peaks near 60MiB, so small programs fit; give the language a pod entry if bigger ones run out of memory, disk or time. The rust:1.99-slim image is about 330MB compressed, so the pre-puller's first pull takes a while.