Network Policies - Runloop AI Docs

Start with the Runloop Quickstart to use the examples below.

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()

See the Blueprints network policies documentation for more details on using network policies with blueprints.

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.

Documentation Index

​Why Use Network Policies?

​Network Policy Configuration

​Hostname Wildcards

​Limits

​Creating a Network Policy

​Policy Types

​Allow All (Default Behavior)

​Deny All

​Allow Specific Hosts

​Allow Devbox-to-Devbox Communication

​Allow Agent Gateway and MCP Hub Access

​Applying Network Policies

​Apply to a Devbox

​Apply to a Blueprint

​Override Blueprint Policy

​Managing Network Policies

​List Policies

​Get Policy Details

​Update a Policy

​Delete a Policy

​Common Use Cases

​AI Agent with API Access

​Multi-Devbox Workflow

​Best Practices

Why Use Network Policies?

Network Policy Configuration

Hostname Wildcards

Limits

Creating a Network Policy

Policy Types

Allow All (Default Behavior)

Deny All

Allow Specific Hosts

Allow Devbox-to-Devbox Communication

Allow Agent Gateway and MCP Hub Access

Applying Network Policies

Apply to a Devbox

Apply to a Blueprint

Override Blueprint Policy

Managing Network Policies

List Policies

Get Policy Details

Update a Policy

Delete a Policy

Common Use Cases

AI Agent with API Access

Multi-Devbox Workflow

Best Practices