Configuration
FrankenScriptling is configured with environment variables and optional TOML files that only the operator controls. PHP code cannot read or loosen the policy: it can only lower the resource limits for one VM.
The settings are read once, when the first VM is created, and apply to the
whole FrankenPHP process. Set them on the container (docker run -e, Compose
environment:) or in your own image’s ENV. They are not read per site from
the Caddyfile’s env directive.
With nothing set, scripts get the computation-only libraries and no access to files, the network or other processes.
Libraries
Libraries fall into these groups:
| Group | Registered when | Libraries |
|---|---|---|
| Always on | Always | The standard library, toml, yaml, html.parser, logging, sys, secrets, shlex, scriptling.csv, scriptling.xml, scriptling.markdown, scriptling.similarity, scriptling.template.html, scriptling.template.text, scriptling.ai.memory |
| Filesystem | Enabled, and SCRIPTLING_ALLOWED_PATHS grants directories |
pathlib, os, os.path, fs, glob, shutil, tempfile, tarfile, zipfile, scriptling.find, scriptling.grep, scriptling.sed |
| Network | Enabled, and a network policy is set | requests, scriptling.net.websocket, scriptling.net.resolve, scriptling.ai, scriptling.mcp (with scriptling.toon), scriptling.mercure |
| Processes | Enabled | subprocess |
| Secrets | Enabled, and a secret provider is set | scriptling.secret |
| Plugins | Enabled, and plugins are preloaded | scriptling.plugin |
scriptling.ai.agent and scriptling.ai.agent.interact are in the image but
import scriptling.ai, so they work once scriptling.ai is enabled and the
model’s host is allowed. Some
libraries are not in the image at all, whatever the configuration: container
control, the database and key-value stores, messaging, scriptling.wait_for
and the gossip, multicast and unicast networking libraries.
| Variable | Meaning |
|---|---|
SCRIPTLING_ENABLED_LIBRARIES |
Comma-separated libraries to enable from the gated groups. Unset enables none. |
SCRIPTLING_ALLOWED_PATHS |
Colon-separated absolute directories the filesystem libraries may use. Unset or - allows none, so the filesystem libraries stay closed even when enabled. |
SCRIPTLING_NETWORK_POLICY_FILE |
Comma-separated paths to network policy files (below). Unset keeps the network libraries closed even when enabled. Later files override earlier ones. |
docker run --rm -p 8080:80 \
-e SCRIPTLING_ENABLED_LIBRARIES=pathlib,requests \
-e SCRIPTLING_ALLOWED_PATHS=/app/data \
-e SCRIPTLING_NETWORK_POLICY_FILE=/etc/scriptling/network.toml \
-v "$PWD/network.toml:/etc/scriptling/network.toml:ro" \
-v "$PWD/data:/app/data" \
-v "$PWD/public:/app/public" \
paularlott/frankenscriptling:php8.6Scripts can now read and write under /app/data and call the hosts the policy
allows. pathlib.Path("/etc/passwd").read_text() fails with a policy error,
and import subprocess fails because it was not enabled.
A stdio MCP server (mcp.Client("/path/to/server")) starts a process, so
scriptling.mcp refuses it unless subprocess is enabled too.
Network policy file
The network policy is a TOML file in the same format as the CLI’s network policy:
https_only = true
allow_hosts = ["api.example.com", ".internal.example.com"]
deny_hosts = []
allow_cidrs = []
deny_cidrs = []
allow_ip_literals = false
allow_loopback = false
allow_private_ips = false
dns_servers = ["1.1.1.1"]
client_timeout = "30s"Every key is optional. Loopback, link-local (cloud metadata endpoints
included), private and multicast addresses are refused unless allowed, and a
URL with an IP address is refused unless allow_ip_literals is set or the
address is in allow_cidrs. There is no setting that turns the checks off.
A policy cannot name a port, so allowing loopback or a private range opens
everything listening there, including Caddy’s admin API on localhost:2019.
Allow the narrowest allow_cidrs you can instead.
One policy file
SCRIPTLING_POLICY_FILE takes one or more comma-separated TOML files that
hold the libraries, paths, network policy and limits together:
[libraries]
enabled = ["pathlib", "requests"]
[filesystem]
allowed_paths = ["/app/data"]
[network]
https_only = true
allow_hosts = ["api.example.com"]
[limits]
memory_bytes = 67108864
max_value_bytes = 1048576When the separate variables are set too, they are the base and the file overrides what it sets.
Resource limits
| Variable | [limits] key |
Meaning |
|---|---|---|
SCRIPTLING_MEMORY_LIMIT |
memory_bytes |
Estimated memory one VM may hold. Going over cancels the running call with an error containing memory limit exceeded; the VM stays usable. |
SCRIPTLING_MAX_VALUE_BYTES |
max_value_bytes |
Largest string, bytes value or container one operation may create. Going over raises MemoryError in the script. |
Both are in bytes; unset or 0 means no limit. The limits apply to each VM,
not to the process. PHP can lower them for one VM with setMemoryLimit() and
setMaxValueBytes() but cannot raise or remove them. Limit running time per
call with evalWithTimeout().
A malformed setting (an unreadable policy file, a limit that is not a number) fails closed: VMs report the error instead of running with a looser policy.
Secrets
scriptling.secret reads secrets from Vault or 1Password, configured from
the environment so credentials stay out of policy files. It also needs
scriptling.secret in SCRIPTLING_ENABLED_LIBRARIES.
| Variable | Meaning |
|---|---|
SCRIPTLING_SECRET_PROVIDER |
vault or onepassword |
SCRIPTLING_SECRET_ALIAS |
The name scripts pass to secret.get(alias, path, field); defaults to the provider’s name |
SCRIPTLING_SECRET_ADDRESS |
The provider’s address (Vault’s URL) |
SCRIPTLING_SECRET_TOKEN |
Vault token or 1Password service account token |
SCRIPTLING_SECRET_APP_ROLE_ID, SCRIPTLING_SECRET_APP_ROLE_SECRET |
Vault AppRole login, instead of a token |
SCRIPTLING_SECRET_NAMESPACE |
Vault Enterprise namespace |
SCRIPTLING_SECRET_KV_VERSION |
Vault KV engine version, 1 or 2 |
SCRIPTLING_SECRET_CACHE_TTL |
How long a value is cached, such as 5m (the default) |
SCRIPTLING_SECRET_DEFAULT_FIELD |
The field used when a script names none |
SCRIPTLING_SECRET_INSECURE_SKIP_TLS |
true skips TLS verification; for testing only |
For several providers, point SCRIPTLING_SECRET_PROVIDERS_FILE at TOML files
with one [[providers]] table each, using the same settings in snake_case
(provider, alias, address, token, …). See
scriptling.secret for the script side.
Plugins
scriptling.plugin gives scripts the plugins the operator
loads at startup. Scripts cannot load their own unless HTTP loading is turned
on, and they can never start a plugin executable.
| Variable | Meaning |
|---|---|
SCRIPTLING_PLUGIN |
Comma-separated plugin executables or http(s):// URLs to load at startup |
SCRIPTLING_PLUGIN_DIR |
Comma-separated directories of plugin executables to load at startup |
SCRIPTLING_PLUGIN_HTTP_ENABLED |
true lets scripts load() HTTP(S) plugins within the network policy, and unload() only those |
A plugin that fails to load fails the policy closed rather than leaving
scripts with fewer plugins than intended. scriptling.plugin also has to be
in SCRIPTLING_ENABLED_LIBRARIES.
SCRIPTLING_ENABLED_LIBRARIES=scriptling.plugin
SCRIPTLING_PLUGIN=https://billing.internal/rpc
SCRIPTLING_PLUGIN_DIR=/etc/frankenscriptling/pluginsCompose example
services:
app:
image: paularlott/frankenscriptling:php8.6
ports:
- "8080:80"
environment:
SCRIPTLING_POLICY_FILE: /etc/scriptling/policy.toml
SCRIPTLING_SECRET_PROVIDER: vault
SCRIPTLING_SECRET_ADDRESS: https://vault.internal:8200
SCRIPTLING_SECRET_TOKEN: ${VAULT_TOKEN}
volumes:
- ./public:/app/public
- ./policy.toml:/etc/scriptling/policy.toml:ro