Network Policy

Network policies control outbound network access from a box. Use them when you want to:

block all outbound traffic
allow only specific public domains
restrict egress to specific CIDR ranges

By default, boxes use:

{ mode: "allow-all" }

{"mode": "allow-all"}

Modes

Mode	Description
`allow-all`	Default. No outbound restrictions.
`deny-all`	Block all outbound network access.
`custom`	Allow or deny specific domains and CIDR ranges.

The SDK type is:

type NetworkPolicy =
  | { mode: "allow-all" | "deny-all" }
  | {
      mode: "custom"
      allowedDomains?: string[]
      allowedCidrs?: string[]
      deniedCidrs?: string[]
    }

from typing import Literal, TypedDict, Union
from typing_extensions import NotRequired

class AllowDenyNetworkPolicy(TypedDict):
    mode: Literal["allow-all", "deny-all"]

class CustomNetworkPolicy(TypedDict):
    mode: Literal["custom"]
    allowed_domains: NotRequired[list[str]]
    allowed_cidrs: NotRequired[list[str]]
    denied_cidrs: NotRequired[list[str]]

NetworkPolicy = Union[AllowDenyNetworkPolicy, CustomNetworkPolicy]

Create a box with a policy

Pass networkPolicy when creating a box:

import { Box } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  networkPolicy: {
    mode: "custom",
    allowedDomains: ["api.github.com", "registry.npmjs.org"],
  },
})

from upstash_box import Box

box = Box.create(
    runtime="node",
    network_policy={
        "mode": "custom",
        "allowed_domains": ["api.github.com", "registry.npmjs.org"],
    },
)

You can also combine domain and CIDR rules:

const box = await Box.create({
  runtime: "node",
  networkPolicy: {
    mode: "custom",
    allowedDomains: ["api.github.com", "*.githubusercontent.com"],
    allowedCidrs: ["104.16.0.0/12"],
  },
})

box = Box.create(
    runtime="node",
    network_policy={
        "mode": "custom",
        "allowed_domains": ["api.github.com", "*.githubusercontent.com"],
        "allowed_cidrs": ["104.16.0.0/12"],
    },
)

networkPolicy is also supported in Box.fromSnapshot() and EphemeralBox.

Read the current policy

Use the networkPolicy getter:

console.log(box.networkPolicy) // { mode: "allow-all" }

print(box.network_policy)  # {"mode": "allow-all"}

Update a running box

Update the policy after creation:

await box.updateNetworkPolicy({ mode: "deny-all" })

box.update_network_policy({"mode": "deny-all"})

Switch back to unrestricted outbound access:

await box.updateNetworkPolicy({ mode: "allow-all" })

box.update_network_policy({"mode": "allow-all"})

Changes take effect immediately. You do not need to recreate the box.

Matching rules

allowedDomains supports exact matches such as api.github.com
wildcard domains must use *.suffix form, for example *.githubusercontent.com
allowedCidrs and deniedCidrs use standard CIDR notation
in custom mode, deniedCidrs takes precedence over allowed CIDRs
private IP ranges are always blocked even if you try to allow them explicitly

Example patterns

Allow only GitHub and npm:

await box.updateNetworkPolicy({
  mode: "custom",
  allowedDomains: ["github.com", "*.github.com", "registry.npmjs.org"],
})

box.update_network_policy({
    "mode": "custom",
    "allowed_domains": ["github.com", "*.github.com", "registry.npmjs.org"],
})

Block all outbound traffic:

await box.updateNetworkPolicy({ mode: "deny-all" })

box.update_network_policy({"mode": "deny-all"})

Allow a specific public CIDR:

await box.updateNetworkPolicy({
  mode: "custom",
  allowedCidrs: ["104.16.0.0/12"],
})

box.update_network_policy({
    "mode": "custom",
    "allowed_cidrs": ["104.16.0.0/12"],
})

Block a specific CIDR range:

await box.updateNetworkPolicy({
  mode: "custom",
  deniedCidrs: ["104.16.120.0/24"],
})

box.update_network_policy({
    "mode": "custom",
    "denied_cidrs": ["104.16.120.0/24"],
})

Introduction

Basics

Lifecycle

Security

Guides

Modes

Create a box with a policy

Read the current policy

Update a running box

Matching rules

Example patterns

​Modes

​Create a box with a policy

​Read the current policy

​Update a running box

​Matching rules

​Example patterns

​Related

Modes

Create a box with a policy

Read the current policy

Update a running box

Matching rules

Example patterns

Related