Skip to main content
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" }

​
Modes

ModeDescription
allow-allDefault. No outbound restrictions.
deny-allBlock all outbound network access.
customAllow 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[]
    }

​
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"],
  },
})
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"],
  },
})
networkPolicy is also supported in Box.fromSnapshot() and EphemeralBox.

​
Read the current policy

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

​
Update a running box

Update the policy after creation: 
await box.updateNetworkPolicy({ mode: "deny-all" })
Switch back to unrestricted outbound access: 
await box.updateNetworkPolicy({ 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"],
})
Block all outbound traffic: 
await box.updateNetworkPolicy({ mode: "deny-all" })
Allow a specific public CIDR: 
await box.updateNetworkPolicy({
  mode: "custom",
  allowedCidrs: ["104.16.0.0/12"],
})
Block a specific CIDR range: 
await box.updateNetworkPolicy({
  mode: "custom",
  deniedCidrs: ["104.16.120.0/24"],
})