Network Policy
--network-policy restricts where the 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 scriptling.provision.fetch libraries, the Slack, Discord and Telegram libraries, and container endpoints a script supplies may connect — the tool for letting scripts reach the internet without letting them reach your private network or cloud metadata endpoints. Enforcement happens at connect time: hostnames are resolved through the configured DNS servers, every resolved address is checked, and the connection is made to the validated address — so DNS rebinding, redirects, and IP-notation tricks don’t get through.
For scriptling.ai, the policy also covers remote_servers — the MCP servers an AI client can attach for tool use — so a script cannot reach an internal MCP endpoint by routing through ai.Client(..., remote_servers=[...]) instead of mcp.Client(...) directly.
scriptling --network-policy=policy.toml --disable-lib subprocess script.pyA missing or invalid policy file aborts startup rather than running scripts unrestricted. Combine the policy with --disable-lib subprocess in any mode so code cannot bypass it by shelling out to curl; scriptling.container checks only endpoints a script passes as socket=; the configured --docker-host / --podman-host endpoints are trusted. The Slack, Discord and Telegram libraries send every request and gateway connection through the policy, their platforms’ own hosts included, since a script supplies the bot token and could otherwise post data to a bot it controls; the bot token itself is only ever sent to the platform’s hosts. Under a strict allow_hosts, list the hosts of the platforms you use: api.telegram.org; slack.com and its subdomains (for example .slack.com, which covers wss-primary.slack.com and files.slack.com); discord.com plus gateway.discord.gg (and .discordapp.com / .discordapp.net for media). scriptling.net.gossip checks every connection a cluster makes, to joined peers and to peers it learns from the cluster, and carries all traffic over TCP; grant a private cluster with allow_cidrs. With allow_hosts set, gossip peers are limited to the listed names, and a peer given by IP must be granted by allow_cidrs or allow_ip_literals. scriptling.provision.fetch downloads through the policy. A connection the policy denies raises a network policy: … error, including from wait_for.http() and wait_for.port(), which fail immediately rather than waiting out their timeout. A network policy constrains only the libraries wired to it; it is not a process-level network sandbox, and plugin processes are outside it.
With a policy active, these address categories are blocked by default:
- Loopback (
127.0.0.0/8,::1) - Link-local (
169.254.0.0/16including cloud metadata endpoints,fe80::/10) - Private (
10/8,172.16/12,192.168/16,fc00::/7) - Reserved: ranges that are neither private nor publicly routable — shared address space / CGNAT (
100.64/10, home to some cloud metadata endpoints),0/8,192.0.0/24, documentation (192.0.2/24,198.51.100/24,203.0.113/24,2001:db8::/32,3fff::/20), benchmarking (198.18/15,2001:2::/48),240/4and broadcast, and the IPv6 forms that embed or translate IPv4 (IPv4-compatible::/96, NAT6464:ff9b::/96and64:ff9b:1::/48, 6to42002::/16, Teredo2001::/32), plus discard100::/64and deprecated site-localfec0::/10 - Unspecified (
0.0.0.0,::) and multicast addresses - URLs that name an IP directly (e.g.
http://10.0.0.1/)
Policy File Reference
A TOML file; every key is optional.
# Require https:// and wss:// URLs only
https_only = false
# Permit URLs that name an IP directly (http://1.2.3.4/). Blocked by
# default unless the address is already granted by allow_cidrs; every
# literal still faces the address-category and deny_cidrs rules.
# Non-canonical forms count as literals too: a host whose last label is a
# number (2130706433, 0x7f.1, 127.1) or that contains a colon.
allow_ip_literals = false
# Permit loopback addresses (e.g. for local testing)
allow_loopback = false
# Permit private network addresses (10/8, 172.16/12, 192.168/16, fc00::/7)
allow_private_ips = false
# Permit reserved addresses: CGNAT 100.64/10, 0/8, documentation and
# benchmarking ranges, 240/4, IPv4-compatible/NAT64/6to4/Teredo IPv6 and
# similar non-public ranges. To reach just one of them (e.g. a CGNAT
# overlay network), prefer allow_cidrs.
allow_reserved_ips = false
# Host allowlist: when set, ONLY these hosts may be contacted. Listed
# hosts are trusted — they may resolve to loopback, private and reserved
# addresses. deny_cidrs still applies to them, and a link-local answer
# (169.254.0.0/16, fe80::/10 — where cloud metadata lives) still needs an
# allow_cidrs entry: a suffix entry trusts every name under it, and
# wildcard-DNS names can be pointed at any address. An exact name matches
# itself; a leading dot matches the domain and all subdomains.
# Matching ignores case and a trailing dot ("api.example.com." is the
# same host as "api.example.com"), in entries and in requests alike.
allow_hosts = ["api.example.com", ".internal.corp"]
# Host denylist: always wins, even over the allowlist. Same syntax.
deny_hosts = ["tracker.example"]
# Address range exceptions. allow_cidrs overrides the built-in address
# blocks (how you grant one slice of your LAN); deny_cidrs wins over
# everything, allowlisted hosts included. Multicast is always denied unless granted here, e.g. SSDP
# for scriptling.net.multicast: "239.255.255.250/32".
allow_cidrs = ["10.1.0.0/16"]
deny_cidrs = ["10.66.0.0/16"]
# Resolve hostnames through these servers instead of the host's resolver
# (plain DNS, port 53). One resolver then serves every script network path,
# including scriptling.net.resolve, so lookups and connections always agree.
dns_servers = ["1.1.1.1", "8.8.8.8:53"]
# Cap each HTTP request end to end - dial, TLS, redirects, reading the
# body - e.g. "30s" or "2m". Off by default: requests run as long as
# their own per-request timeout allows, which long-running calls such as
# LLM APIs need.
client_timeout = "30s"Common recipes:
# Internet-only: no internal access at all (the default policy — an empty file)# API allowlist: scripts may call one API and nothing else
allow_hosts = ["api.example.com"]# One slice of the LAN granted, https only. IP-literal URLs inside this
# range are accepted without setting allow_ip_literals.
https_only = true
allow_cidrs = ["10.1.0.0/16"]Note that in the CLI, custom DNS always comes with the policy’s address checks — a policy file cannot turn them off. Embedding hosts that want nameservers without any blocking can construct a resolver-only configuration in Go (see AllowAll in the library registration guide).
Go hosts configure the same policy in code — see the library registration guide for the netsecurity.Config reference, and the security guide for the broader sandboxing model.