network

The network block declares the egress policy and limits for outbound requests.

The network block declares what the agent's outbound HTTP client may do.

agent.acl

network {
  user_agent = runtime("USER_AGENT", "my-agent/1.0")

  headers = {
    "X-Env" = "production"
  }

  limits {
    request_timeout_ms = runtime("NETWORK_REQUEST_TIMEOUT_MS", 5000)
  }

  policy {
    allow = [
      {
        protocol = "https"
        hostname = "api.example.com"
      }
    ]
  }
}

Fields

Field	Type	Required	runtime()	Default	Description
`user_agent`	string	no	yes	unset	The `User-Agent` header sent with every request.
`headers`	map<string, string>	no	yes	`{}`	Additional headers sent with every request.
`limits`	NetworkLimits	no		defaults below	Connection, timeout, and size limits.
`policy`	NetworkPolicy	no		defaults below	Rules governing the destination addresses, HTTP methods, and URLs available to outgoing requests.

NetworkLimits

Field	Type	Required	runtime()	Default	Description
`connect_timeout_ms`	integer	no	yes	unset	Time in milliseconds allowed to establish a connection.
`read_timeout_ms`	integer	no	yes	unset	Time in milliseconds allowed between response body chunks.
`request_timeout_ms`	integer	no	yes	unset	Time in milliseconds allowed for the entire request.
`max_redirects`	integer	no	yes	`5`	Number of redirects one request may follow.
`max_response_bytes`	integer	no	yes	unset	Maximum accepted response body size in bytes.
`concurrency_limit`	integer	no	yes	unset	Maximum requests in flight at once.

An unset limit is not enforced.

NetworkPolicy

The policy block contains addresses, methods, and allow.

addresses

Field	Type	Required	runtime()	Default	Description
`allow_loopback`	boolean	no	yes	`false`	Allow requests to this machine through addresses such as `127.0.0.1` and `::1`.
`allow_private`	boolean	no	yes	`false`	Allow destinations on private networks, such as `10.0.0.1`, `192.168.1.1`, and IPv6 unique-local addresses.
`allow_link_local`	boolean	no	yes	`false`	Allow addresses usable only on the immediately connected network, such as `169.254.0.1`.

These permit categories of destination address. The checks apply to every address a host name resolves to. The link-local category is the one covering the cloud instance metadata address.

methods

Field	Type	Required	runtime()	Default	Description
`methods`	array<string>	no	yes	unset (all methods)	HTTP methods the agent may use.

allow

allow is a list of WHATWG URLPattern objects. An empty list denies every request. [{}] matches every URL. Each pattern uses the protocol, hostname, port, and pathname components. An omitted component matches anything.

Field	Type	Required	runtime()	Default	Description
`allow`	array<URLPattern>	no	yes	`[]`	URL patterns the agent may request.

URLPattern

Field	Type	Required	runtime()	Default	Description
`protocol`	string	no	yes	any	The URL scheme pattern, such as `https` or `http{s}?`.
`hostname`	string	no	yes	any	The host name pattern, such as `api.example.com`, `*.example.com`, or `:tenant.example.com`.
`port`	string	no	yes	any	The port pattern, such as `8443` or `(8080\|8443)`.
`pathname`	string	no	yes	any	The path pattern, such as `/v1/*` or `/users/:id`.

Host name patterns

Host name matching follows URLPattern hostname semantics, which are label-aware rather than plain substring matches.

*.acme.com matches any number of leading labels.
:sub.acme.com matches exactly one leading label.
api.acme.com matches both patterns.
deep.api.acme.com matches *.acme.com, but not :sub.acme.com.
evilacme.com matches neither pattern, because acme.com is not a separate host label there.

Environment variables

An omitted field below is read at startup from its variable. When the variable is unset, the field's default applies. Setting the field in the manifest replaces the variable. See Runtime values for how values are read.

Variable	Field
`NETWORK_USER_AGENT`	`user_agent`
`NETWORK_HEADERS`	`headers`
`NETWORK_CONNECT_TIMEOUT_MS`	`connect_timeout_ms`
`NETWORK_READ_TIMEOUT_MS`	`read_timeout_ms`
`NETWORK_REQUEST_TIMEOUT_MS`	`request_timeout_ms`
`NETWORK_MAX_REDIRECTS`	`max_redirects`
`NETWORK_MAX_RESPONSE_BYTES`	`max_response_bytes`
`NETWORK_CONCURRENCY_LIMIT`	`concurrency_limit`
`NETWORK_ALLOW_METHODS`	`methods`
`NETWORK_ALLOW_PATTERNS`	`allow`
`NETWORK_ALLOW_LOOPBACK`	`allow_loopback`
`NETWORK_ALLOW_PRIVATE`	`allow_private`
`NETWORK_ALLOW_LINK_LOCAL`	`allow_link_local`

See HTTP library for what component code sees and Control network egress for the step-by-step recipe.