> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Policies

> Control egress network access for your Devboxes

<Tip>Start with the [Runloop Quickstart](/docs/tutorials/quickstart) to use the examples below.</Tip>

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](/docs/devboxes/agent-gateways) for credential proxying |
| `allow_mcp_gateway`      | If `true`, allows devbox egress to [MCP Hub](/docs/devboxes/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](mailto:support@runloop.ai).

## Creating a Network Policy

<CodeGroup>
  ```python Python theme={null}
  # 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}")
  ```

  ```typescript TypeScript theme={null}
  // Create a restrictive policy allowing only specific hosts
  const policy = await runloop.networkPolicy.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"
  });
  console.log(`Created policy: ${policy.id}`);
  ```
</CodeGroup>

## Policy Types

### Allow All (Default Behavior)

Allows unrestricted network access:

<CodeGroup>
  ```python Python theme={null}
  policy = await runloop.network_policies.create(
      name="allow-all-policy",
      allow_all=True
  )
  ```

  ```typescript TypeScript theme={null}
  const policy = await runloop.networkPolicy.create({
      name: "allow-all-policy",
      allow_all: true
  });
  ```
</CodeGroup>

### Deny All

Block all external network access by setting `allow_all=False` with an empty hostname list:

<CodeGroup>
  ```python Python theme={null}
  policy = await runloop.network_policies.create(
      name="deny-all-policy",
      allow_all=False,
      allowed_hostnames=[]
  )
  ```

  ```typescript TypeScript theme={null}
  const policy = await runloop.networkPolicy.create({
      name: "deny-all-policy",
      allow_all: false,
      allowed_hostnames: []
  });
  ```
</CodeGroup>

### Allow Specific Hosts

Restrict access to only the services your agent needs:

<CodeGroup>
  ```python Python theme={null}
  policy = await runloop.network_policies.create(
      name="restricted-policy",
      allow_all=False,
      allowed_hostnames=[
          "github.com",
          "api.openai.com",
          "*.anthropic.com"
      ]
  )
  ```

  ```typescript TypeScript theme={null}
  const policy = await runloop.networkPolicy.create({
      name: "restricted-policy",
      allow_all: false,
      allowed_hostnames: [
          "github.com",
          "api.openai.com",
          "*.anthropic.com"
      ]
  });
  ```
</CodeGroup>

### Allow Devbox-to-Devbox Communication

Enable traffic between your Devboxes via [tunnels](/docs/devboxes/tunnels):

<CodeGroup>
  ```python Python theme={null}
  policy = await runloop.network_policies.create(
      name="multi-devbox-policy",
      allow_all=False,
      allowed_hostnames=["github.com"],
      allow_devbox_to_devbox=True
  )
  ```

  ```typescript TypeScript theme={null}
  const policy = await runloop.networkPolicy.create({
      name: "multi-devbox-policy",
      allow_all: false,
      allowed_hostnames: ["github.com"],
      allow_devbox_to_devbox: true
  });
  ```
</CodeGroup>

### Allow Agent Gateway and MCP Hub Access

When using [Agent Gateways](/docs/devboxes/agent-gateways) or [MCP Hub](/docs/devboxes/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`.

<CodeGroup>
  ```python Python theme={null}
  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
  )
  ```

  ```typescript TypeScript theme={null}
  const policy = await runloop.networkPolicy.create({
      name: "secure-agent-policy",
      allow_all: false,
      allowed_hostnames: ["github.com", "*.github.com"],
      allow_agent_gateway: true,
      allow_mcp_gateway: true
  });
  ```
</CodeGroup>

<Note>
  If `allow_all` is `true`, Agent Gateway and MCP Hub access are automatically permitted. These toggles only matter when `allow_all` is `false`.
</Note>

## 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`:

<CodeGroup>
  ```python Python theme={null}
  # 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
      }
  )
  ```

  ```typescript TypeScript theme={null}
  // Create a policy
  const policy = await runloop.networkPolicy.create({
      name: "devbox-policy",
      allow_all: false,
      allowed_hostnames: ["github.com", "api.openai.com"]
  });

  // Create a devbox with the policy
  const devbox = await runloop.devbox.create({
      launch_parameters: {
          network_policy_id: policy.id
      }
  });
  ```
</CodeGroup>

### Apply to a Blueprint

Blueprints support two types of network policy application:

1. **Build-time policy** (`network_policy_id` at top level): Restricts network access during the blueprint build process
2. **Runtime policy** (`launch_parameters.network_policy_id`): Applies to all Devboxes created from the blueprint

<CodeGroup>
  ```python Python theme={null}
  # 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()
  ```

  ```typescript TypeScript theme={null}
  // Create policies for build and runtime
  const buildPolicy = await runloop.networkPolicy.create({
      name: "build-policy",
      allow_all: false,
      allowed_hostnames: ["github.com", "*.npmjs.org", "pypi.org"]
  });

  const runtimePolicy = await runloop.networkPolicy.create({
      name: "runtime-policy",
      allow_all: false,
      allowed_hostnames: ["api.openai.com"]
  });

  // Create a blueprint with both policies
  const blueprint = await runloop.blueprint.create({
      name: "secure-blueprint",
      network_policy_id: buildPolicy.id,  // Applies during build
      launch_parameters: {
          network_policy_id: runtimePolicy.id,  // Applies to devboxes
          launch_commands: ["npm install"]
      }
  });

  // Devboxes created from this blueprint inherit the runtime policy
  const devbox = await blueprint.createDevbox();
  ```
</CodeGroup>

See the [Blueprints network policies documentation](/docs/devboxes/blueprints/network-policies) 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:

<CodeGroup>
  ```python Python theme={null}
  # Override with a different policy
  devbox = await runloop.devbox.create(
      blueprint_id=blueprint.id,
      launch_parameters={
          "network_policy_id": different_policy.id
      }
  )
  ```

  ```typescript TypeScript theme={null}
  // Override with a different policy
  const devbox = await runloop.devbox.create({
      blueprint_id: blueprint.id,
      launch_parameters: {
          network_policy_id: differentPolicy.id
      }
  });
  ```
</CodeGroup>

## Managing Network Policies

### List Policies

<CodeGroup>
  ```python Python theme={null}
  policies = await runloop.network_policies.list()
  for policy in policies:
      print(f"{policy.name}: {policy.id}")
  ```

  ```typescript TypeScript theme={null}
  const policies = await runloop.networkPolicy.list();
  for (const policy of policies) {
      console.log(`${policy.name}: ${policy.id}`);
  }
  ```
</CodeGroup>

### Get Policy Details

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  const policy = runloop.networkPolicy.fromId("npol_1234567890");
  const info = await policy.getInfo();
  console.log(`Policy: ${info.name}`);
  console.log(`Allow all: ${info.egress.allow_all}`);
  console.log(`Allowed hosts: ${info.egress.allowed_hostnames}`);
  ```
</CodeGroup>

### Update a Policy

<CodeGroup>
  ```python Python theme={null}
  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"
  )
  ```

  ```typescript TypeScript theme={null}
  const policy = runloop.networkPolicy.fromId("npol_1234567890");
  const updated = await policy.update({
      name: "updated-policy-name",
      allowed_hostnames: ["github.com", "api.openai.com", "*.anthropic.com"],
      description: "Updated description"
  });
  ```
</CodeGroup>

<Note>
  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.
</Note>

### Delete a Policy

<CodeGroup>
  ```python Python theme={null}
  policy = runloop.network_policies.from_id("npol_1234567890")
  await policy.delete()
  ```

  ```typescript TypeScript theme={null}
  const policy = runloop.networkPolicy.fromId("npol_1234567890");
  await policy.delete();
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## 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):

<CodeGroup>
  ```python Python theme={null}
  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"
  )
  ```

  ```typescript TypeScript theme={null}
  const policy = await runloop.networkPolicy.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"
  });
  ```
</CodeGroup>

### Multi-Devbox Workflow

Allow Devboxes to communicate with each other for distributed workloads:

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  const policy = await runloop.networkPolicy.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
  const devbox1 = await runloop.devbox.create({
      launch_parameters: { network_policy_id: policy.id }
  });
  const devbox2 = await runloop.devbox.create({
      launch_parameters: { network_policy_id: policy.id }
  });
  // devbox1 and devbox2 can now communicate via tunnels
  ```
</CodeGroup>

## Best Practices

1. **Start Restrictive**: Begin with a deny-all policy and add only the hosts your agent needs.
2. **Use Wildcards Carefully**: `*.example.com` allows all subdomains, which may be broader than intended.
3. **Name Policies Descriptively**: Use names that indicate the policy's purpose (e.g., `ai-agent-production`, `eval-restricted`).
4. **Document Policies**: Use the description field to document why specific hosts are allowed.
5. **Audit Regularly**: Review policies periodically to remove unnecessary access.
6. **Use Blueprint Inheritance**: Apply policies to Blueprints for consistent security across Devboxes.
7. **Test Policies**: Before deploying to production, test that your agent can access all required services.