Control network egress

The runtime HTTP client is always present, but what it can reach is first shaped by the manifest and then adjusted further at startup through runtime configuration. This guide shows how to start from the default policy and narrow it to the exact network surface a component needs.

Start from the default

With no network block, every outbound request is refused until a pattern allows it. Loopback, private, and link-local addresses are also refused. An operator opens destinations with NETWORK_ALLOW_PATTERNS.

The manifest is the first place network policy is defined. Runtime configuration can also control the policy at startup, including when the manifest omits the network block entirely, so one compiled binary can still be tightened or relaxed per deployment.

Allow one API host

Add a network block with a single allow pattern when the component should reach one API host and nothing else.

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

Requests to any other host are now refused.

Narrow the methods

Add methods to limit which HTTP methods the client may use. When methods is unset, methods are unrestricted.

network {
  policy {
    methods = ["GET", "POST"]

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

Set a timeout

Add request_timeout_ms when the whole request should have a deadline. Use runtime() when the operator should be able to adjust the value at startup.

network {
  limits {
    request_timeout_ms = runtime("REQUEST_TIMEOUT_MS", 5000)
  }

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

Adjust the policy at startup

NETWORK_ALLOW_PATTERNS sets allow when the binary starts, so one compiled binary can open different destinations per deployment. It applies when the manifest omits allow or writes it as runtime("NETWORK_ALLOW_PATTERNS", [...]). See Runtime values for how the value is read.

# Allow one host
NETWORK_ALLOW_PATTERNS='[{"protocol":"https","hostname":"api.example.com"}]'

# Change the host of the first pattern the manifest declares
NETWORK_ALLOW_PATTERNS__0__HOSTNAME=backend.svc

# Allow every URL
NETWORK_ALLOW_PATTERNS='[{}]'

Permit an address class for local development

Loopback is off by default because allowing it lets component code talk to services bound on the same machine, which is usually broader access than a production agent should have.

Enable it at startup where local development needs it:

NETWORK_ALLOW_LOOPBACK=true

Requests to loopback still need a pattern that allows them:

network {
  policy {
    allow = [
      {
        protocol = "http"
        hostname = "127.0.0.1"
        port     = "3000"
      }
    ]
  }
}

To give the switch a name of your own, write the field with runtime(). The field then reads ALLOW_LOOPBACK in place of NETWORK_ALLOW_LOOPBACK:

network {
  policy {
    addresses {
      allow_loopback = runtime("ALLOW_LOOPBACK", false)
    }
  }
}

Make a request from a component

Send a request from a component using the corresponding runtime library.

import { fetch } from "agentc:http";

try {
  const response = await fetch("https://api.example.com/status");

  if (!response.ok) {
    throw new Error(`upstream returned ${response.status}`);
  }

  const body = await response.text();
  console.log(body);
} catch (error) {
  console.error(String(error));
}

If the request violates the egress policy, the request raises an error whose message explains the refusal.

Where to go next

• network reference
• agentc:http
• agentc_http