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

<CodeGroup>
```typescript box.ts
{ mode: "allow-all" }
```

```python box.py
{"mode": "allow-all"}
```
</CodeGroup>

---

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

<CodeGroup>
```typescript box.ts
type NetworkPolicy =
  | { mode: "allow-all" | "deny-all" }
  | {
      mode: "custom"
      allowedDomains?: string[]
      allowedCidrs?: string[]
      deniedCidrs?: string[]
    }
```

```python box.py
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]
```
</CodeGroup>

---

## Create a box with a policy

Pass `networkPolicy` when creating a box:

<CodeGroup>
```typescript box.ts
import { Box } from "@upstash/box"

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

```python box.py
from upstash_box import Box

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

You can also combine domain and CIDR rules:

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

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

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

---

## Read the current policy

Use the `networkPolicy` getter:

<CodeGroup>
```typescript box.ts
console.log(box.networkPolicy) // { mode: "allow-all" }
```

```python box.py
print(box.network_policy)  # {"mode": "allow-all"}
```
</CodeGroup>

---

## Update a running box

Update the policy after creation:

<CodeGroup>
```typescript box.ts
await box.updateNetworkPolicy({ mode: "deny-all" })
```

```python box.py
box.update_network_policy({"mode": "deny-all"})
```
</CodeGroup>

Switch back to unrestricted outbound access:

<CodeGroup>
```typescript box.ts
await box.updateNetworkPolicy({ mode: "allow-all" })
```

```python box.py
box.update_network_policy({"mode": "allow-all"})
```
</CodeGroup>

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:

<CodeGroup>
```typescript box.ts
await box.updateNetworkPolicy({
  mode: "custom",
  allowedDomains: ["github.com", "*.github.com", "registry.npmjs.org"],
})
```

```python box.py
box.update_network_policy({
    "mode": "custom",
    "allowed_domains": ["github.com", "*.github.com", "registry.npmjs.org"],
})
```
</CodeGroup>

Block all outbound traffic:

<CodeGroup>
```typescript box.ts
await box.updateNetworkPolicy({ mode: "deny-all" })
```

```python box.py
box.update_network_policy({"mode": "deny-all"})
```
</CodeGroup>

Allow a specific public CIDR:

<CodeGroup>
```typescript box.ts
await box.updateNetworkPolicy({
  mode: "custom",
  allowedCidrs: ["104.16.0.0/12"],
})
```

```python box.py
box.update_network_policy({
    "mode": "custom",
    "allowed_cidrs": ["104.16.0.0/12"],
})
```
</CodeGroup>

Block a specific CIDR range:

<CodeGroup>
```typescript box.ts
await box.updateNetworkPolicy({
  mode: "custom",
  deniedCidrs: ["104.16.120.0/24"],
})
```

```python box.py
box.update_network_policy({
    "mode": "custom",
    "denied_cidrs": ["104.16.120.0/24"],
})
```
</CodeGroup>

---

## Related

- [Security](/box/overall/security)
- [Shell](/box/overall/shell)
- [How It Works](/box/overall/how-it-works)