Network Policies allow you to control what network resources your Devboxes can access. By default, Devboxes have unrestricted network access. Network Policies let you restrict egress traffic to specific hostnames, block all external access, or allow communication between your Devboxes.
Why Use Network Policies?
Network Policies are essential for:
- Security: Limit network access to only the services your AI agent needs (e.g., specific APIs, package registries)
- Compliance: Ensure Devboxes can only communicate with approved endpoints
- Cost Control: Prevent unexpected network charges from unrestricted access
- Isolation: Control whether Devboxes can communicate with each other
Network Policy Configuration
A Network Policy defines egress rules with the following options:
| Option | Description |
|---|
name | A unique, human-readable name for the policy |
allow_all | If true, allows all egress traffic (overrides other settings) |
allowed_hostnames | List of DNS hostnames to allow, with wildcard support |
allow_devbox_to_devbox | If true, allows traffic between your account’s Devboxes via tunnels |
allow_agent_gateway | If true, allows devbox egress to Agent Gateways for credential proxying |
allow_mcp_gateway | If true, allows devbox egress to MCP Hub for MCP server access |
description | Optional description for the policy |
Hostname Wildcards
You can use wildcards in the first label of hostnames:
github.com - Allow only github.com*.github.com - Allow all subdomains of github.com*.npmjs.org - Allow all subdomains of npmjs.org
Limits
You can create up to 100 network policies per account. If you need more, please contact support@runloop.ai.
Creating a Network Policy
# Create a restrictive policy allowing only specific hosts
policy = await runloop.network_policies.create(
name="production-policy",
allow_all=False,
allowed_hostnames=[
"github.com",
"*.github.com",
"api.openai.com",
"*.npmjs.org",
"pypi.org"
],
allow_devbox_to_devbox=False,
description="Production policy for AI agent workloads"
)
print(f"Created policy: {policy.id}")
Policy Types
Allow All (Default Behavior)
Allows unrestricted network access:
policy = await runloop.network_policies.create(
name="allow-all-policy",
allow_all=True
)
Deny All
Block all external network access by setting allow_all=False with an empty hostname list:
policy = await runloop.network_policies.create(
name="deny-all-policy",
allow_all=False,
allowed_hostnames=[]
)
Allow Specific Hosts
Restrict access to only the services your agent needs:
policy = await runloop.network_policies.create(
name="restricted-policy",
allow_all=False,
allowed_hostnames=[
"github.com",
"api.openai.com",
"*.anthropic.com"
]
)
Allow Devbox-to-Devbox Communication
Enable traffic between your Devboxes via tunnels:
policy = await runloop.network_policies.create(
name="multi-devbox-policy",
allow_all=False,
allowed_hostnames=["github.com"],
allow_devbox_to_devbox=True
)
Allow Agent Gateway and MCP Hub Access
When using Agent Gateways or MCP Hub with a restrictive network policy, you must explicitly enable access to those services. These are dedicated toggles — you do not need to add Runloop hostnames to allowed_hostnames.
policy = await runloop.network_policies.create(
name="secure-agent-policy",
allow_all=False,
allowed_hostnames=["github.com", "*.github.com"],
allow_agent_gateway=True,
allow_mcp_gateway=True
)
If allow_all is true, Agent Gateway and MCP Hub access are automatically permitted. These toggles only matter when allow_all is false.
Applying Network Policies
Network policies can be applied at multiple levels:
Apply to a Devbox
Apply a policy when creating a Devbox using network_policy_id inside launch_parameters:
# Create a policy
policy = await runloop.network_policies.create(
name="devbox-policy",
allow_all=False,
allowed_hostnames=["github.com", "api.openai.com"]
)
# Create a devbox with the policy
devbox = await runloop.devbox.create(
launch_parameters={
"network_policy_id": policy.id
}
)
Apply to a Blueprint
Blueprints support two types of network policy application:
- Build-time policy (
network_policy_id at top level): Restricts network access during the blueprint build process
- Runtime policy (
launch_parameters.network_policy_id): Applies to all Devboxes created from the blueprint
# Create policies for build and runtime
build_policy = await runloop.network_policies.create(
name="build-policy",
allow_all=False,
allowed_hostnames=["github.com", "*.npmjs.org", "pypi.org"]
)
runtime_policy = await runloop.network_policies.create(
name="runtime-policy",
allow_all=False,
allowed_hostnames=["api.openai.com"]
)
# Create a blueprint with both policies
blueprint = await runloop.blueprint.create(
name="secure-blueprint",
network_policy_id=build_policy.id, # Applies during build
launch_parameters={
"network_policy_id": runtime_policy.id, # Applies to devboxes
"launch_commands": ["npm install"]
}
)
# Devboxes created from this blueprint inherit the runtime policy
devbox = await blueprint.create_devbox()
Override Blueprint Policy
When creating a Devbox from a Blueprint, you can override the inherited runtime policy:
# Override with a different policy
devbox = await runloop.devbox.create(
blueprint_id=blueprint.id,
launch_parameters={
"network_policy_id": different_policy.id
}
)
Managing Network Policies
List Policies
policies = await runloop.network_policies.list()
for policy in policies:
print(f"{policy.name}: {policy.id}")
Get Policy Details
policy = runloop.network_policies.from_id("npol_1234567890")
info = await policy.get_info()
print(f"Policy: {info.name}")
print(f"Allow all: {info.egress.allow_all}")
print(f"Allowed hosts: {info.egress.allowed_hostnames}")
Update a Policy
policy = runloop.network_policies.from_id("npol_1234567890")
updated = await policy.update(
name="updated-policy-name",
allowed_hostnames=["github.com", "api.openai.com", "*.anthropic.com"],
description="Updated description"
)
When you update a network policy, all running Devboxes and Blueprints using that policy will be updated. Changes are eventually consistent and may take a few moments to propagate to all resources.
Delete a Policy
policy = runloop.network_policies.from_id("npol_1234567890")
await policy.delete()
You cannot delete a network policy that is currently in use by any Devboxes or Blueprints. Remove the policy from all resources before deleting it.
Common Use Cases
AI Agent with API Access
Allow access to code repositories, package registries, and Runloop services (Agent Gateway for LLM API proxying, MCP Hub for tool access):
policy = await runloop.network_policies.create(
name="ai-agent-policy",
allow_all=False,
allowed_hostnames=[
# Code repositories
"github.com",
"*.github.com",
"gitlab.com",
# Package registries
"*.npmjs.org",
"pypi.org",
"*.pythonhosted.org"
],
allow_agent_gateway=True,
allow_mcp_gateway=True,
description="Standard AI agent policy"
)
Multi-Devbox Workflow
Allow Devboxes to communicate with each other for distributed workloads:
policy = await runloop.network_policies.create(
name="distributed-workflow",
allow_all=False,
allowed_hostnames=["github.com"],
allow_devbox_to_devbox=True,
description="Policy for multi-devbox workflows"
)
# Create multiple devboxes that can communicate
devbox1 = await runloop.devbox.create(
launch_parameters={"network_policy_id": policy.id}
)
devbox2 = await runloop.devbox.create(
launch_parameters={"network_policy_id": policy.id}
)
# devbox1 and devbox2 can now communicate via tunnels
Best Practices
- Start Restrictive: Begin with a deny-all policy and add only the hosts your agent needs.
- Use Wildcards Carefully:
*.example.com allows all subdomains, which may be broader than intended.
- Name Policies Descriptively: Use names that indicate the policy’s purpose (e.g.,
ai-agent-production, eval-restricted).
- Document Policies: Use the description field to document why specific hosts are allowed.
- Audit Regularly: Review policies periodically to remove unnecessary access.
- Use Blueprint Inheritance: Apply policies to Blueprints for consistent security across Devboxes.
- Test Policies: Before deploying to production, test that your agent can access all required services.
