Library Registration
When embedding Scriptling in a Go application, you control which libraries are available to scripts. A bare scriptling.New() interpreter has no importable libraries: a library exists for scripts only once you register it.
Libraries come in two tiers, and the tier tells you both what a library can reach and what it costs to include.
| Tier | Go package | What it may do | How to register |
|---|---|---|---|
| Standard libraries | github.com/paularlott/scriptling/stdlib |
Pure computation. No filesystem, network, process, environment or host access, and no third-party dependency beyond what the interpreter core already links | stdlib.RegisterAll(p), or p.RegisterLibrary(stdlib.XLibrary) one at a time |
| Extension libraries | One package per library or family, under github.com/paularlott/scriptling/extlibs/... |
Anything the host grants: files, network, processes, host information, credentials, or simply a large dependency | Import the package and call its Register function |
Why Two Tiers
Capability. Every standard library is safe by construction: it can compute, but it cannot touch the world outside the interpreter. You can register the whole set for untrusted scripts, which are then bounded by the interpreter’s resource limits. Each extension library is a capability you grant deliberately, usually with a path or network policy attached.
Binary size and dependencies. The interpreter core depends on the stdlib package, so the standard libraries are compiled into every application that embeds Scriptling whether or not you register them; registering them costs no extra binary size. Extension libraries are the opposite: each lives in its own Go package, and an application that does not import a package does not link it or its dependencies. You only ship, and only have to audit, the extensions you register.
The split was driven by measurement. Before it, the extension libraries shared one Go package, so registering only YAML produced a 13.7 MB binary: it linked every library in that package, including the WebSocket client, the Markdown renderer, process inspection, the KV store, the HTTP client and subprocess. Today the same embedder is 6.83 MB.
Measured on stripped darwin/arm64 embedder binaries, the interpreter plus every standard library is 6.52 MB. Adding one extension gives:
| Registered on top of the standard libraries | Binary | Added |
|---|---|---|
toml |
6.73 MB | 0.21 MB |
os (filesystem) |
6.81 MB | 0.29 MB |
yaml |
6.83 MB | 0.31 MB |
scriptling.net.multicast |
7.86 MB | 1.34 MB |
scriptling.template.* |
7.96 MB | 1.44 MB |
requests |
9.96 MB | 3.44 MB |
scriptling.mercure |
10.04 MB | 3.52 MB |
The runtime family is split the same way, so a server pays only for the pieces it registers:
| Runtime libraries registered | Added |
|---|---|
Core: scriptling.runtime (background tasks), .sync, .sandbox, .jsonrpc, .mcp, .plugin |
0.34 MB |
scriptling.runtime.kv only |
0.46 MB |
scriptling.runtime.http (links the core) |
1.92 MB |
| All of the runtime libraries | 2.40 MB |
When the tiers were drawn, the candidate libraries were measured in isolation:
| Library | Size | Tier |
|---|---|---|
shlex |
16 KB | Standard |
secrets |
16 KB | Standard |
html.parser |
64 KB | Standard |
csv |
65 KB | Standard |
xml |
68 KB | Standard |
toml |
197 KB | Extension |
yaml |
296 KB | Extension |
scriptling.template.* |
1.4 MB | Extension |
The first five meet the standard-library rule and are small (229 KB together), so they are standard libraries. YAML, TOML and the template engine stay opt-in because of their weight, even though they have no host access.
Minimal Embedder
An interpreter with the standard libraries and nothing else. Scripts can compute, parse and format data, but cannot reach files, the network, processes or the host:
package main
import (
"fmt"
"github.com/paularlott/scriptling"
"github.com/paularlott/scriptling/stdlib"
)
func main() {
p := scriptling.New()
stdlib.RegisterAll(p)
_, err := p.Eval(`
import csv, io, json, statistics
rows = list(csv.DictReader(io.StringIO("name,score\nada,92\nalan,87\n")))
print(json.dumps({"rows": len(rows), "mean": statistics.mean([int(r["score"]) for r in rows])}))
`)
if err != nil {
fmt.Println("Error:", err)
}
}Pick What You Need
Add extension libraries one at a time, each with the narrowest policy that works. Only the packages imported here are linked into the binary:
package main
import (
"fmt"
"github.com/paularlott/scriptling"
"github.com/paularlott/scriptling/extlibs/filesystem"
"github.com/paularlott/scriptling/extlibs/logging"
"github.com/paularlott/scriptling/extlibs/netsecurity"
"github.com/paularlott/scriptling/extlibs/requests"
"github.com/paularlott/scriptling/extlibs/yaml"
"github.com/paularlott/scriptling/stdlib"
)
func main() {
p := scriptling.New()
stdlib.RegisterAll(p)
// No host access, just a parser: no policy needed.
yaml.Register(p)
// Log through the default logger (stdout).
logging.RegisterDefault(p)
// os, os.path and pathlib, confined to one directory.
filesystem.RegisterOS(p, []string{"/srv/app/data"})
filesystem.RegisterPathlib(p, []string{"/srv/app/data"})
// Outbound HTTPS to a single API host.
requests.Register(p, &netsecurity.Config{
RequireHTTPS: true,
AllowHosts: []string{"api.example.com"},
})
if _, err := p.Eval(`import yaml, os, requests`); err != nil {
fmt.Println("Error:", err)
}
}Standard Libraries
Register All at Once
import "github.com/paularlott/scriptling/stdlib"
stdlib.RegisterAll(p)stdlib.LibraryNames() returns the name of every library RegisterAll registers, in registration order, which is useful for building allow or deny lists.
Register Individually
p.RegisterLibrary(stdlib.JSONLibrary)
p.RegisterLibrary(stdlib.MathLibrary)
p.RegisterLibrary(stdlib.ReLibrary)
p.RegisterLibrary(stdlib.TimeLibrary)Registering a subset changes what scripts can import, not what is compiled in: the whole stdlib package is part of every embedding binary.
stdlib.RegisterAll registers every library in this table. Each library variable has a matching name constant (stdlib.JSONLibraryName and so on) where one is declared in stdlib.
| Import name | Go variable |
|---|---|
base64 |
stdlib.Base64Library |
collections |
stdlib.CollectionsLibrary |
contextlib |
stdlib.ContextlibLibrary |
copy |
stdlib.CopyLibrary |
csv |
stdlib.CSVAliasLibrary |
dataclasses |
stdlib.DataclassesLibrary |
datetime |
stdlib.DatetimeLibrary |
difflib |
stdlib.DifflibLibrary |
enum |
stdlib.EnumLibrary |
functools |
stdlib.FunctoolsLibrary |
hashlib |
stdlib.HashlibLibrary |
hmac |
stdlib.HmacLibrary |
html |
stdlib.HTMLLibrary |
html.parser |
stdlib.HTMLParserLibrary |
io |
stdlib.IOLibrary |
itertools |
stdlib.ItertoolsLibrary |
json |
stdlib.JSONLibrary |
math |
stdlib.MathLibrary |
msgpack |
stdlib.MsgpackLibrary |
random |
stdlib.RandomLibrary |
re |
stdlib.ReLibrary |
scriptling.csv |
stdlib.CSVLibrary |
scriptling.xml |
stdlib.XMLLibrary |
secrets |
stdlib.SecretsLibrary |
shlex |
stdlib.ShlexLibrary |
statistics |
stdlib.StatisticsLibrary |
string |
stdlib.StringLibrary |
textwrap |
stdlib.TextwrapLibrary |
time |
stdlib.TimeLibrary |
typing |
stdlib.TypingLibrary |
urllib |
stdlib.URLLibLibrary |
urllib.parse |
stdlib.URLParseLibrary |
uuid |
stdlib.UUIDLibrary |
xml |
stdlib.XMLAliasLibrary |
csv and xml are the same libraries as scriptling.csv and scriptling.xml, registered under their Python names as well. secrets draws from the operating system’s cryptographic random source, which is not host access in the sense above: it reveals nothing about the host and changes nothing.
platform is not a standard library: it reports the host name, so it is an extension (platform.Register(p), see Utilities).
Extension Libraries
Each extension lives in its own package under github.com/paularlott/scriptling/extlibs/. Import the package, then call its registration function. Every package also exports its import name as a constant (yaml.LibraryName, filesystem.OSLibraryName, runtime.RuntimeSyncLibraryName, kv.LibraryName and so on).
In the tables below, the package column is relative to github.com/paularlott/scriptling/, and Grants is the reason to think before registering: filesystem, network, process, host information, credentials, code execution, inbound (a server entry point), or none (no host access, opt-in only because of its size or dependencies).
Filesystem Libraries
Package extlibs/filesystem. Every function takes allowedPaths []string, the directories the library may touch (see Path Policy).
import "github.com/paularlott/scriptling/extlibs/filesystem"
// Everything in the family, under one path policy
filesystem.RegisterAll(p, []string{"/tmp", "/data"})
// Or only what scripts need
filesystem.RegisterOS(p, []string{"/tmp", "/data"})
filesystem.RegisterGlob(p, []string{"/data"})| Import name | Registration | Grants |
|---|---|---|
os, os.path |
filesystem.RegisterOS(p, allowedPaths) |
Filesystem read/write; environment variables (os.environ, os.getenv) |
pathlib |
filesystem.RegisterPathlib(p, allowedPaths) |
Filesystem read/write |
glob |
filesystem.RegisterGlob(p, allowedPaths) |
Filesystem read (listings) |
fs |
filesystem.RegisterFS(p, allowedPaths) |
Filesystem read/write |
shutil |
filesystem.RegisterShutil(p, allowedPaths) |
Filesystem read/write |
tempfile |
filesystem.RegisterTempfile(p, allowedPaths) |
Filesystem write |
zipfile |
filesystem.RegisterZipfile(p, allowedPaths) |
Filesystem read/write |
tarfile |
filesystem.RegisterTarfile(p, allowedPaths) |
Filesystem read/write |
scriptling.grep |
filesystem.RegisterGrep(p, allowedPaths) |
Filesystem read |
scriptling.find |
filesystem.RegisterFind(p, allowedPaths) |
Filesystem read |
scriptling.sed |
filesystem.RegisterSed(p, allowedPaths) |
Filesystem read/write |
| all of the above | filesystem.RegisterAll(p, allowedPaths) |
The constructors (filesystem.NewOSLibrary, NewPathlibLibrary, NewGlobLibrary, NewShutilLibrary, NewTempfileLibrary, NewZipfileLibrary, NewTarfileLibrary, NewGrepLibrary, NewFindLibrary, NewSedLibrary) take an fssecurity.Config and return the library without registering it. The package also exports a plain Go API (filesystem.Grep, filesystem.Find, filesystem.SedReplace, filesystem.EditFile and their option types) that needs no interpreter.
Path Policy
Every library that touches files takes the same policy, either as allowedPaths []string or as an fssecurity.Config{AllowedPaths: ...} (package extlibs/fssecurity):
| Value | Meaning |
|---|---|
nil (or a zero fssecurity.Config) |
No restriction: the whole filesystem the process can reach |
[]string{} |
Deny all paths |
[]string{"/srv/data", ...} |
Only these directories and everything below them |
Relative entries are made absolute against the process’s working directory. Every check resolves symbolic links and .. before comparing, so a link or traversal that leads outside the allowed directories is refused, and /allowed does not match /allowed-other. A refused path raises PermissionError.
The same policy confines the file access of libraries outside the filesystem family:
| Library | Registration | What the paths confine |
|---|---|---|
requests |
requests.RegisterConfigured(p, paths, policy) |
The CA bundle a script names with verify="path" |
scriptling.oauth |
oauth.RegisterConfigured(p, paths, policy) |
CA bundle files |
scriptling.mercure |
mercure.RegisterConfigured(p, paths, policy, opts...) |
CA bundle files |
scriptling.wait_for |
waitfor.RegisterConfigured(p, allowedPaths, policy...) |
file(), dir() and file_content() |
scriptling.container |
container.RegisterConfigured(...) or container.RegisterWithOptions(p, opts) |
Unix sockets and bind-mounted volumes a script names |
| Slack, Discord, Telegram | slack.RegisterConfigured(p, logger, allowedPaths, policy...) (same for discord, telegram) |
Local files send_file() reads |
scriptling.runtime.http |
http.Register(p, allowedPaths) (extlibs/runtime/http) |
Directories static() may serve; the server serves only files that resolve inside them |
scriptling.runtime.kv |
kv.Register(p, allowedPaths) (extlibs/runtime/kv) |
Persistent stores kv.open() creates or opens (in-memory :memory: stores are always allowed) |
scriptling.runtime.sandbox |
runtime.RegisterSandbox(p, allowedPaths) |
Scripts exec_file() reads |
scriptling.provision.file, .fetch |
file.RegisterConfigured(p, paths, ...), fetch.RegisterConfigured(p, paths, guard, ...) |
Files they create, change or download to |
Each plain Register in that table registers the library without a path restriction. The runtime libraries have no such variant: http.Register, kv.Register and runtime.RegisterSandbox always take allowedPaths, so an unconfined static(), kv.open() or exec_file() means passing nil explicitly. A path they refuse raises the same uncatchable PermissionError as the filesystem libraries. The CLI registers all of these libraries with its --allowed-paths list.
Network and HTTP
| Import name | Package | Registration | Grants |
|---|---|---|---|
requests |
extlibs/requests |
requests.Register(p, policy...) or requests.RegisterConfigured(p, paths, policy) |
Network (outbound HTTP); reads CA bundle files |
scriptling.oauth |
extlibs/oauth |
oauth.Register(p, policy...) or oauth.RegisterConfigured(p, paths, policy) |
Network |
scriptling.net.websocket |
extlibs/net/websocket |
websocket.Register(p, policy...) |
Network |
scriptling.net.unicast |
extlibs/net/unicast |
unicast.Register(p, policy...) |
Network |
scriptling.net.multicast |
extlibs/net/multicast |
multicast.Register(p, policy...) |
Network |
scriptling.net.gossip |
extlibs/net/gossip |
gossip.Register(p, logger, policy...) (a nil logger is a null logger) |
Network |
scriptling.net.resolve |
extlibs/net/resolve |
resolve.Register(p, resolver) (your resolve.Resolver) |
DNS lookups through the resolver you supply |
scriptling.mercure |
extlibs/mercure |
mercure.Register(p, policy...) or mercure.RegisterConfigured(p, paths, policy, opts...) |
Network |
scriptling.wait_for |
extlibs/waitfor |
waitfor.Register(p, policy...) or waitfor.RegisterConfigured(p, allowedPaths, policy...) |
Network (ports, HTTP), filesystem (file checks), process list (process_name()) |
mercure.WithoutSubscribe() is an option for RegisterConfigured that lets scripts publish but not receive. The interpreter closes the Mercure clients a script leaves open (lifecycle).
requests.Register with a policy but no paths leaves the CA bundle unconfined; use requests.RegisterConfigured(p, fssecurity.Config{AllowedPaths: paths}, policy) to confine it too (outside the paths it raises an uncatchable PermissionError, as in os). The CLI registers it this way with --allowed-paths and --network-policy.
Network Policy
The outbound networking libraries (requests, scriptling.wait_for, scriptling.net.websocket, scriptling.net.unicast, scriptling.net.multicast, scriptling.net.gossip, scriptling.nomad, scriptling.oauth, scriptling.mercure, scriptling.ai, scriptling.mcp, and the Slack, Discord and Telegram messaging libraries) accept an optional *netsecurity.Config (package extlibs/netsecurity) that restricts where scripts may connect. scriptling.container takes one through container.RegisterConfigured or container.Options.Policy (it checks the endpoints a script supplies), and scriptling.provision.fetch takes a *netsecurity.Guard through fetch.RegisterConfigured. Pass nil (or omit the argument) for no restrictions; a non-nil policy blocks loopback, link-local (cloud metadata), private, unspecified, and multicast addresses, and IP-literal URLs, by default. An invalid policy fails closed: the library refuses every connection rather than falling back to unrestricted access.
import (
"github.com/paularlott/scriptling/extlibs/ai"
scriptlingmcp "github.com/paularlott/scriptling/extlibs/mcp"
"github.com/paularlott/scriptling/extlibs/net/websocket"
"github.com/paularlott/scriptling/extlibs/netsecurity"
"github.com/paularlott/scriptling/extlibs/requests"
"github.com/paularlott/scriptling/extlibs/waitfor"
)
policy := &netsecurity.Config{
RequireHTTPS: true,
AllowHosts: []string{"api.example.com"},
}
requests.Register(p, policy)
waitfor.Register(p, policy)
websocket.Register(p, policy)
ai.Register(p, policy)
scriptlingmcp.Register(p, policy)To load the same TOML file the CLI’s --network-policy flag uses, import extlibs/netsecurity/policyfile. It is a separate package so that the network libraries do not link a TOML parser; only an application that reads policy files imports it:
import "github.com/paularlott/scriptling/extlibs/netsecurity/policyfile"
policy, err := policyfile.LoadConfig("policy.toml") // *netsecurity.Config
if err != nil {
return err // invalid policies are an error, never an open policy
}
requests.Register(p, policy)ai.Register’s policy also guards remote_servers, the MCP servers an ai.Client() instance can attach for tool use, so a script cannot reach a policy-blocked endpoint by routing through ai.Client(..., remote_servers=[...]) instead of mcp.Client(...) directly. Stdio-transport mcp.Client() instances (a local subprocess) are unaffected: the policy only governs network access.
Config options (all optional; the zero value behind a non-nil pointer is a safe default policy):
| Option | Type | Default | Meaning |
|---|---|---|---|
RequireHTTPS |
bool |
false |
Reject plain http:// and ws:// URLs |
AllowIPLiterals |
bool |
false |
Permit URLs that name an IP directly; granted addresses still face the address rules |
AllowLoopback |
bool |
false |
Permit 127.0.0.0/8 and ::1 |
AllowPrivateIPs |
bool |
false |
Permit RFC1918 and IPv6 unique-local ranges |
AllowReservedIPs |
bool |
false |
Permit reserved ranges that are neither private nor publicly routable: CGNAT 100.64.0.0/10, 0.0.0.0/8, documentation and benchmarking ranges, 240.0.0.0/4, IPv4-compatible/NAT64/6to4/Teredo IPv6 and more; the full list is netsecurity.ReservedCIDRs. Policy files set it as allow_reserved_ips = true |
AllowHosts |
[]string |
nil |
Host allowlist; when set, only these hosts may be contacted. Listed hosts are trusted: they may resolve to loopback, private and reserved addresses; DeniedCIDRs still applies to them, and a link-local answer still needs an AllowedCIDRs entry. Exact names match themselves; a leading dot (.corp.example.com) matches the domain and all subdomains |
DenyHosts |
[]string |
nil |
Host denylist; always wins, even over AllowHosts. Same syntax |
AllowedCIDRs |
[]string |
nil |
Address ranges permitted explicitly, overriding the built-in blocks (how you grant one slice of a LAN) |
DeniedCIDRs |
[]string |
nil |
Address ranges blocked explicitly; wins over everything, including AllowedCIDRs |
DNSServers |
[]string |
nil |
Resolve through these servers ("1.1.1.1" or "8.8.8.8:53", plain DNS) instead of the host resolver; the same resolver then serves scriptling.net.resolve too |
AllowAll |
bool |
false |
Host-use only (not settable from policy files): disable every address and host check, leaving only the shared DNS resolver; the way to configure nameservers without imposing a policy |
ClientTimeout |
time.Duration |
0 |
Optional end-to-end cap on each HTTP request (dial, TLS, redirects, reading the body) for the client the guard hands to script libraries. 0 enforces no cap: requests run as long as their own per-request timeout allows, which long-running calls such as LLM APIs need. Policy files set it as client_timeout = "45s" |
An invalid config (bad CIDR, malformed DNS server) fails netsecurity.NewGuard / policyfile.LoadConfig with an error: treat it as a startup failure. netsecurity.FailClosed(err) returns a guard that rejects every request if you need to keep serving after a config error.
Process and System
| Import name | Package | Registration | Grants |
|---|---|---|---|
subprocess |
extlibs/subprocess |
subprocess.Register(p) |
Process execution |
sys |
extlibs/sys |
sys.Register(p, argv, stdin) |
Host information (platform, executable path), argv, the standard streams, exit(), and an input() builtin reading stdin when it is non-nil |
platform |
extlibs/platform |
platform.Register(p) |
Host information (host name, OS, architecture) |
logging |
extlibs/logging |
logging.Register(p, logger) or logging.RegisterDefault(p) |
Writes to your logger; RegisterDefault (or a nil logger) logs to stdout |
scriptling.secret |
extlibs/secret |
secret.Register(p, registry) |
Credentials from the *secretprovider.Registry you supply |
import (
"os"
"github.com/paularlott/scriptling/extlibs/logging"
"github.com/paularlott/scriptling/extlibs/secret"
"github.com/paularlott/scriptling/extlibs/sys"
)
sys.Register(p, []string{"script.py"}, os.Stdin) // argv and stdin
logging.Register(p, myLogger) // or logging.RegisterDefault(p)
secret.Register(p, registry) // *secretprovider.Registrysys.NewLibrary(argv, stdin) and secret.NewLibrary(registry) build the library without registering it.
Secret Providers
scriptling.secret reads from a *secretprovider.Registry (package extlibs/secretprovider). That package is only the core: the Provider interface, the alias Registry, provider Config blocks and a table of provider-type factories (RegisterFactory, RegisteredTypes). It holds no concrete provider, so it links no HTTP client. Either register your own Provider with registry.Register(provider, alias, cacheTTL), or enable the built-in provider types you want and build providers from config:
provider = |
Package | Enable with | Construct directly |
|---|---|---|---|
"vault" (HashiCorp Vault) |
extlibs/secretprovider/vault |
vault.Register() |
vault.New(cfg) |
"onepassword" (1Password Connect) |
extlibs/secretprovider/onepassword |
onepassword.Register() |
onepassword.New(cfg) |
import (
"github.com/paularlott/scriptling/extlibs/secret"
"github.com/paularlott/scriptling/extlibs/secretprovider"
"github.com/paularlott/scriptling/extlibs/secretprovider/onepassword"
"github.com/paularlott/scriptling/extlibs/secretprovider/vault"
)
if err := vault.Register(); err != nil { // provider = "vault"
return err
}
if err := onepassword.Register(); err != nil { // provider = "onepassword" (Connect)
return err
}
registry := secretprovider.NewRegistry()
if err := secretprovider.RegisterConfigs(registry, configs); err != nil { // []secretprovider.Config
return err
}
secret.Register(p, registry)Call each provider’s Register() before secretprovider.RegisterConfigs or secretprovider.NewProvider; a config block whose type was not registered fails with an error naming the type. Register() is safe to call more than once. A onepassword block with service_account_token (a 1Password service account instead of Connect) also needs the github.com/paularlott/scriptling-onepassword extension linked in with a blank import; see scriptling.secret.
Runtime Libraries
The runtime family is three packages, so an application links only what it registers:
| Package | Go package name | Libraries | Links |
|---|---|---|---|
extlibs/runtime |
runtime (alias it if you also import Go’s runtime) |
scriptling.runtime (background tasks, server lifecycle) and .sync, .sandbox, .jsonrpc, .mcp, .plugin |
No KV store, no WebSocket server, no net/http |
extlibs/runtime/kv |
kv |
scriptling.runtime.kv |
The KV store; independent of the rest of the family |
extlibs/runtime/http |
http (alias it if you also import Go’s net/http) |
scriptling.runtime.http |
The WebSocket server; imports the core package |
There is no register-everything call: register each library you want. The CLI registers them in this order (scriptling.runtime.plugin later, with the other libraries):
import (
scriptlingruntime "github.com/paularlott/scriptling/extlibs/runtime"
rthttp "github.com/paularlott/scriptling/extlibs/runtime/http"
"github.com/paularlott/scriptling/extlibs/runtime/kv"
)
allowedPaths := []string{"/srv/app/data"}
rthttp.Register(p, allowedPaths) // scriptling.runtime.http
kv.Register(p, allowedPaths) // scriptling.runtime.kv
scriptlingruntime.RegisterSync(p) // scriptling.runtime.sync
scriptlingruntime.RegisterSandbox(p, allowedPaths) // scriptling.runtime.sandbox
scriptlingruntime.RegisterJSONRPC(p) // scriptling.runtime.jsonrpc
scriptlingruntime.RegisterMCP(p) // scriptling.runtime.mcp
scriptlingruntime.Register(p) // scriptling.runtime (background tasks)
scriptlingruntime.RegisterPlugin(p) // scriptling.runtime.plugin| Import name | Registration | Grants |
|---|---|---|
scriptling.runtime |
runtime.Register(p) |
Background tasks (concurrent execution) |
scriptling.runtime.http |
http.Register(p, allowedPaths) |
Inbound: HTTP and WebSocket routes your server exposes; static() serves files within allowedPaths |
scriptling.runtime.kv |
kv.Register(p, allowedPaths) |
In-memory stores; filesystem for persistent stores within allowedPaths |
scriptling.runtime.jsonrpc |
runtime.RegisterJSONRPC(p) |
Inbound: JSON-RPC methods |
scriptling.runtime.mcp |
runtime.RegisterMCP(p) |
Inbound: MCP tools, resources and prompts |
scriptling.runtime.sync |
runtime.RegisterSync(p) |
None (shared concurrency primitives) |
scriptling.runtime.sandbox |
runtime.RegisterSandbox(p, allowedPaths) |
Code execution in an isolated environment; exec_file() reads scripts within allowedPaths |
scriptling.runtime.plugin |
runtime.RegisterPlugin(p) |
Inbound: serves this script as a plugin |
allowedPaths follows the path policy: nil is unrestricted, []string{} denies every path. Each sub-library registered with the same interpreter, before or after runtime.Register, is also reachable as an attribute of the parent, so import scriptling.runtime as rt; rt.kv.open(...) works when scriptling.runtime.kv is registered and rt.kv is absent when it is not.
For a kv.default store, call kv.InitStore(path, logger) before kv.Register (an empty path is memory-only; a nil logger keeps the default stderr logger) and kv.CloseStore() on shutdown. kv.DefaultDB() returns that store’s *snapshotkv.DB, and kv.StoreDB(obj) returns the DB behind any store object a script hands back. Route registrations live in http.State (types http.RouteInfo, http.WebSocketRouteInfo, http.WebSocketServerConn), guarded by runtime.RuntimeState’s lock. Other exported names keep their meaning: runtime.RuntimeState, runtime.ResetRuntime (which also clears the routes and closes the KV stores), runtime.SetSandboxFactory and so on. Request-scoped context and the transport name live in extlibs/reqctx (reqctx.SetTransport, reqctx.Transport, reqctx.WithRequestContext).
AI & Agent
import (
"github.com/paularlott/scriptling/extlibs/agent"
"github.com/paularlott/scriptling/extlibs/ai"
aimemory "github.com/paularlott/scriptling/extlibs/ai/memory"
aitools "github.com/paularlott/scriptling/extlibs/ai/tools"
)
ai.Register(p) // scriptling.ai (optional *netsecurity.Config)
agent.Register(p) // scriptling.ai.agent (returns error)
agent.RegisterInteract(p) // scriptling.ai.agent.interact (returns error)
aimemory.Register(p) // scriptling.ai.memory (optional logger)
aitools.Register(p) // scriptling.ai.tools| Import name | Package | Registration | Grants |
|---|---|---|---|
scriptling.ai |
extlibs/ai |
ai.Register(p, policy...) |
Network (LLM APIs and remote MCP servers) |
scriptling.ai.agent |
extlibs/agent |
agent.Register(p) |
Runs model-chosen tool calls with the libraries you have registered |
scriptling.ai.agent.interact |
extlibs/agent |
agent.RegisterInteract(p) |
Interactive terminal agent loop |
scriptling.ai.memory |
extlibs/ai/memory |
memory.Register(p, logger...) |
Memory stored in a scriptling.runtime.kv store |
scriptling.ai.tools |
extlibs/ai/tools |
tools.Register(p) |
None (tool schema builder) |
agent.Register and agent.RegisterInteract register script libraries and take a registrar with RegisterScriptLibrary, such as *scriptling.Scriptling.
MCP Protocol & TOON
import "github.com/paularlott/scriptling/extlibs/mcp"
mcp.Register(p) // scriptling.mcp
mcp.RegisterToolHelpers(p) // scriptling.mcp.tool
mcp.RegisterToon(p) // scriptling.toon| Import name | Registration | Grants |
|---|---|---|
scriptling.mcp |
mcp.Register(p, policy...) or mcp.RegisterConfigured(p, policy, allowProcesses) |
Network (HTTP MCP servers); process execution (stdio MCP servers) |
scriptling.mcp.tool |
mcp.RegisterToolHelpers(p) |
None (helpers for writing MCP tools) |
scriptling.toon |
mcp.RegisterToon(p) |
None (TOON encoding) |
mcp.Register allows stdio servers, which mcp.Client() starts as subprocesses. Hosts that disable subprocesses use mcp.RegisterConfigured(p, policy, false), which refuses any target that is not an http(s) URL.
Networking
| Import name | Package | Call |
|---|---|---|
scriptling.net.resolve |
extlibs/net/resolve |
resolve.Register(p, resolver) |
scriptling.net.multicast |
extlibs/net/multicast |
multicast.Register(p, policy...) |
scriptling.net.unicast |
extlibs/net/unicast |
unicast.Register(p, policy...) |
scriptling.net.gossip |
extlibs/net/gossip |
gossip.Register(p, logger, policy...) |
scriptling.net.websocket |
extlibs/net/websocket |
websocket.Register(p, policy...) |
scriptling.mercure |
extlibs/mercure |
mercure.Register(p, policy...) or mercure.RegisterConfigured(p, paths, policy, opts...) |
import (
"github.com/paularlott/scriptling/extlibs/mercure"
"github.com/paularlott/scriptling/extlibs/net/gossip"
"github.com/paularlott/scriptling/extlibs/net/multicast"
"github.com/paularlott/scriptling/extlibs/net/resolve"
"github.com/paularlott/scriptling/extlibs/net/unicast"
"github.com/paularlott/scriptling/extlibs/net/websocket"
)
resolve.Register(p, myResolver) // requires a resolve.Resolver implementation
multicast.Register(p)
unicast.Register(p)
gossip.Register(p, nil) // nil = null logger
websocket.Register(p)
mercure.Register(p)All of these grant network access; see Network Policy.
Messaging
import (
"github.com/paularlott/scriptling/extlibs/messaging/console"
"github.com/paularlott/scriptling/extlibs/messaging/discord"
"github.com/paularlott/scriptling/extlibs/messaging/slack"
"github.com/paularlott/scriptling/extlibs/messaging/telegram"
)
console.Register(p) // scriptling.messaging.console
telegram.Register(p, nil) // scriptling.messaging.telegram (logger, optional *netsecurity.Config)
discord.Register(p, nil) // scriptling.messaging.discord (logger, optional *netsecurity.Config)
slack.Register(p, nil) // scriptling.messaging.slack (logger, optional *netsecurity.Config)| Import name | Package | Call | Grants |
|---|---|---|---|
scriptling.messaging.console |
extlibs/messaging/console |
console.Register(p) |
Terminal input and output |
scriptling.messaging.telegram |
extlibs/messaging/telegram |
telegram.Register(p, logger, policy...) |
Network; inbound bot messages; local files for send_file() |
scriptling.messaging.discord |
extlibs/messaging/discord |
discord.Register(p, logger, policy...) |
Network; inbound bot messages; local files for send_file() |
scriptling.messaging.slack |
extlibs/messaging/slack |
slack.Register(p, logger, policy...) |
Network; inbound bot messages; local files for send_file() |
Each of telegram, discord and slack also has RegisterConfigured(p, logger, allowedPaths, policy...), which confines the local files send_file() reads to allowedPaths; plain Register leaves them unconfined.
Utilities
import (
"github.com/paularlott/scriptling/extlibs/console"
"github.com/paularlott/scriptling/extlibs/container"
"github.com/paularlott/scriptling/extlibs/markdown"
"github.com/paularlott/scriptling/extlibs/nomad"
"github.com/paularlott/scriptling/extlibs/oauth"
"github.com/paularlott/scriptling/extlibs/platform"
"github.com/paularlott/scriptling/extlibs/similarity"
"github.com/paularlott/scriptling/extlibs/template"
"github.com/paularlott/scriptling/extlibs/toml"
"github.com/paularlott/scriptling/extlibs/yaml"
)
yaml.Register(p) // yaml
toml.Register(p) // toml
template.RegisterHTML(p) // scriptling.template.html
template.RegisterText(p) // scriptling.template.text
markdown.Register(p) // scriptling.markdown
similarity.Register(p) // scriptling.similarity
platform.Register(p) // platform
console.Register(p) // scriptling.console
container.Register(p, "", "") // scriptling.container (empty = default sockets)
nomad.Register(p) // scriptling.nomad (optional *netsecurity.Config)
oauth.Register(p) // scriptling.oauth (optional *netsecurity.Config)| Import name | Package | Call | Grants |
|---|---|---|---|
yaml |
extlibs/yaml |
yaml.Register(p) |
None (YAML parser, 296 KB) |
toml |
extlibs/toml |
toml.Register(p) |
None (TOML parser, 197 KB) |
scriptling.template.html |
extlibs/template |
template.RegisterHTML(p) |
None (Go template engine, 1.4 MB with .text) |
scriptling.template.text |
extlibs/template |
template.RegisterText(p) |
None (Go template engine) |
scriptling.markdown |
extlibs/markdown |
markdown.Register(p) |
None (Markdown renderer) |
scriptling.similarity |
extlibs/similarity |
similarity.Register(p) |
None |
platform |
extlibs/platform |
platform.Register(p) |
Host information (host name, OS, architecture) |
scriptling.console |
extlibs/console |
console.Register(p) |
Terminal user interface |
scriptling.container |
extlibs/container |
container.Register(p, dockerSock, podmanSock), container.RegisterConfigured(p, dockerSock, podmanSock, paths, policy) or container.RegisterWithOptions(p, opts) |
Control of Docker, Podman or Apple containers on the host |
scriptling.nomad |
extlibs/nomad |
nomad.Register(p, policy...) |
Network; control of a Nomad cluster |
scriptling.oauth |
extlibs/oauth |
oauth.Register(p, policy...) or oauth.RegisterConfigured(p, paths, policy) |
Network |
container.Options adds Paths (the filesystem jail for sockets and volumes), Policy (network policy for script-supplied endpoints; also refuses network="host"), AppleCLI and DenyPrivileged (refuses run(privileged=True)).
The provisioning libraries, scriptling.provision.file, .fetch, .command and .package, are covered in the next section.
Provisioning
| Import name | Package | Call | Grants |
|---|---|---|---|
scriptling.provision.file |
extlibs/provision/file |
file.Register(p) or file.RegisterConfigured(p, paths, opts...) |
Filesystem write |
scriptling.provision.fetch |
extlibs/provision/fetch |
fetch.Register(p) or fetch.RegisterConfigured(p, paths, guard, opts...) |
Network; filesystem write |
scriptling.provision.command |
extlibs/provision/command |
command.Register(p) or command.RegisterConfigured(p, opts...) |
Process execution |
scriptling.provision.package |
extlibs/provision/packages |
packages.Register(p) or packages.RegisterConfigured(p, opts...) |
Process execution (system package manager) |
Provisioning as Root
The provisioning libraries run become=True steps as root only when you give them a become.Become. Without one, such a step fails with a PermissionError (unless the process already runs as root). The first root step starts your own program again through sudo as a helper, so your program must serve it: call become.ServeIfHelper() first thing in main.
import "github.com/paularlott/scriptling/extlibs/provision/become"
func main() {
become.ServeIfHelper() // started as the root helper: serve it and exit
// ...
b := become.New(become.Config{Paths: paths}) // the same allowed paths as the libraries
defer b.Close()
file.RegisterConfigured(p, paths, file.WithBecome(b))
fetch.RegisterConfigured(p, paths, guard, fetch.WithBecome(b))
command.RegisterConfigured(p, command.WithBecome(b))
packages.RegisterConfigured(p, packages.WithBecome(b))
}become.Config also takes Command, the helper’s command line (default: this program with become.HelperArg), and Sudo (default sudo; doas works too). One helper serves every interpreter that shares the Become.
Executable Plugins
scriptling.plugin (the control library for executable plugins, listing/calling/loading them at runtime) lives in the top-level plugin package, not under extlibs, and needs a *plugin.Manager rather than just the interpreter:
import (
"github.com/paularlott/scriptling/plugin"
)
manager := plugin.NewManager(myLogger, func(name string, err error) {
myLogger.Error("plugin process exited", "plugin", name, "error", err)
})
manager.AddDir("./plugins")
if err := manager.Load(ctx); err != nil {
// handle error
}
plugin.RegisterLibraries(p, manager) // scriptling.plugin, plus plugin.<name> for each loaded executable| Import name | Package | Call |
|---|---|---|
scriptling.plugin |
plugin |
plugin.RegisterLibraries(p, manager, policy...) or plugin.RegisterLibrariesConfigured(p, manager, policy, allowProcesses) |
A plugin whose name the interpreter already has, a registered library or a module its library loader supplies, is skipped with a manager warning rather than shadowing it, so set the library loader before calling plugin.RegisterLibraries. plugin.RegisterLibrariesConfigured with allowProcesses false refuses script-driven load() of an executable while HTTP(S) plugins still load; plugin.ProcessesAllowed(disabledLibs) derives the flag from your disabled-library list, as the CLI’s --no-subprocess does.
See Plugin Manager for the full plugin embedding guide.
Migrating from v0.39
v0.40.0 removed the single extlibs package. There is no compatibility layer; replace each old name with the new one.
| Old | New |
|---|---|
extlibs.RegisterCsvLibrary, RegisterXmlLibrary, RegisterHTMLParserLibrary, RegisterShlexLibrary, RegisterSecretsLibrary |
stdlib.RegisterAll(p), or p.RegisterLibrary(stdlib.CSVLibrary) and so on |
platform from stdlib.RegisterAll |
platform.Register(p) (extlibs/platform) |
extlibs.RegisterYAMLLibrary, RegisterTOMLLibrary, RegisterMarkdownLibrary |
yaml.Register, toml.Register, markdown.Register |
extlibs.RegisterTemplateHTMLLibrary, RegisterTemplateTextLibrary |
template.RegisterHTML, template.RegisterText |
extlibs.RegisterOSLibrary(p, paths) and the other filesystem Register…Library calls |
filesystem.RegisterOS(p, paths), filesystem.RegisterPathlib, … or filesystem.RegisterAll(p, paths) |
extlibs.RegisterRequestsLibrary, RegisterRequestsLibraryConfigured, SetRequestsMaxParallelLimit |
requests.Register, requests.RegisterConfigured, requests.SetRequestsMaxParallelLimit |
extlibs.RegisterWebSocketLibrary |
websocket.Register (extlibs/net/websocket) |
extlibs.RegisterWaitForLibrary, RegisterWaitForLibraryConfigured |
waitfor.Register, waitfor.RegisterConfigured |
extlibs.RegisterSubprocessLibrary, RegisterSysLibrary, NewSysLibrary |
subprocess.Register, sys.Register, sys.NewLibrary |
extlibs.RegisterLoggingLibrary, RegisterLoggingLibraryDefault |
logging.Register, logging.RegisterDefault |
extlibs.RegisterSecretLibrary, NewSecretLibrary |
secret.Register, secret.NewLibrary |
extlibs.RegisterRuntimeLibrary |
runtime.Register (extlibs/runtime) |
extlibs.RegisterRuntime{JSONRPC,MCP,Sync,Plugin}Library, RegisterRuntimeSandboxLibrary(p, paths) |
runtime.Register{JSONRPC,MCP,Sync,Plugin}, runtime.RegisterSandbox(p, paths) |
extlibs.RegisterRuntimeLibraryAll(p, paths) |
One call per library: http.Register(p, paths), kv.Register(p, paths), runtime.RegisterSync, runtime.RegisterSandbox(p, paths), runtime.RegisterJSONRPC, runtime.RegisterMCP, runtime.Register |
extlibs.RegisterRuntimeKVLibrary, RegisterRuntimeKVLibraryWithSecurity(p, paths), NewKVSubLibrary, NewKVSubLibraryWithSecurity |
kv.Register(p, paths) (extlibs/runtime/kv); pass nil for unrestricted |
extlibs.InitKVStore, CloseKVStore, KVStoreDB, RuntimeState.KVDB |
kv.InitStore, kv.CloseStore, kv.StoreDB, kv.DefaultDB() |
extlibs.RegisterRuntimeHTTPLibrary, HTTPSubLibrary, NewHTTPSubLibrary(paths) |
http.Register(p, paths) (extlibs/runtime/http); pass nil for unrestricted |
extlibs.RouteInfo, WebSocketRouteInfo, WebSocketServerConn; RuntimeState.Routes, .WebSocketRoutes, .WebSocketConnections |
The same types in extlibs/runtime/http; http.State.Routes and so on, under runtime.RuntimeState’s lock |
extlibs.SetSandboxFactory, extlibs.RuntimeState and the other runtime names |
The same names in extlibs/runtime |
extlibs.RuntimeState.Transport |
reqctx.SetTransport, reqctx.Transport (extlibs/reqctx) |
secretprovider.NewVaultProvider(cfg) |
vault.Register(), or vault.New(cfg) (extlibs/secretprovider/vault) |
secretprovider.NewOnePasswordProvider(cfg) |
onepassword.Register(), or onepassword.New(cfg) (extlibs/secretprovider/onepassword) |
netsecurity.LoadConfig(path) |
policyfile.LoadConfig(path) (extlibs/netsecurity/policyfile) |
extlibs.XLibraryName constants |
Each package’s own constant: yaml.LibraryName, filesystem.OSLibraryName, kv.LibraryName, http.LibraryName, runtime.RuntimeSyncLibraryName, … |
Security Considerations
When embedding Scriptling, you have full control over what scripts can access. The standard libraries are safe to expose to untrusted scripts under the interpreter’s resource limits; every extension library is a capability you grant. See the Security Guide for best practices.
Never register these libraries when running untrusted code:
subprocess: allows arbitrary command executionsys: exposes host details and process control (exit)scriptling.container: controls Docker/Podman containers on the hostscriptling.nomad: grants full control over a Nomad cluster (CSI volumes, jobs)scriptling.runtime.sandbox: can execute arbitrary codescriptling.ai.agent: can execute AI-generated code with toolsscriptling.provision.commandandscriptling.provision.package: run commands, possibly as root
Register filesystem and network libraries for untrusted code only with a path policy and a network policy. Even platform reveals the host name, which is why it is an extension rather than a standard library.
See Also
- Basics: creating interpreters and exchanging variables
- Security Guide: security best practices for embedding
- Libraries: usage reference for all libraries
Database Drivers in Embedded Hosts
Scriptling is the library; your application is the host, and the database drivers are optional at every level: you may compile them in, load them as external plugin binaries, or have neither. One call covers all three cases:
import scriptlingplugin "github.com/paularlott/scriptling/plugin"
// On every interpreter your host spins up: main instances, HTTP request
// environments, MCP sessions, sandbox/background factories:
scriptlingplugin.RegisterLibraries(p, pluginManager, scriptlingplugin.PolicyFromSecurity(netPolicy, allowedPaths))- Compiled in (build tags
plugin_sqlite/plugin_sql/plugin_valkey/plugin_badgerdb, or import the plugin packages and callsqlite.RegisterInProcess(p, policy)): registers regardless of the manager; a nilpluginManageris fine. - External plugin binaries: pass your
*plugin.Manager(see Plugin Manager) and the proxy libraries register per instance. - Neither: nothing registers; scripts importing
scriptling.sqlitefail with a namedunknown libraryerror.
The CLI is exactly this pattern: its --plugin-dir handling, exe-relative discovery and per-mode wiring are host choices, not library behaviour. Inside handler scripts, open a connection per run and let the environment’s teardown collect it (Connection closes itself when instances are collected; explicit conn.close() is still good manners).