# Network and Internet Access
<subtitle>Flexibly configure sandbox outbound connection permissions and access services within sandboxes through public URLs.</subtitle>

## Environment Setup

Before using the SDK, please ensure that the `AGENTBOX_API_KEY` environment variable is configured.

>
> You can obtain your API key from the [Console API Keys page](https://console.ucloud.cn/modelverse/experience/api-keys).

```bash
export AGENTBOX_API_KEY=your_api_key
```

By default, each sandbox has full internet access capability and can expose services through unique public URLs.

---

## Internet Outbound Control

You can quickly lock or open sandbox external network access permissions through the `allow_internet_access` parameter when creating sandboxes.

```python
from ucloud_sandbox import Sandbox

# Enable internet access by default
sandbox = Sandbox.create(allow_internet_access=True)

# Disable all outbound network connections to ensure secure execution of sensitive code
isolated_sandbox = Sandbox.create(allow_internet_access=False)
```

### Fine-Grained Whitelist/Blacklist (CIDR)

If more precise control is needed, you can use the `network` dictionary to configure `allow_out` and `deny_out` rules.

```python
from ucloud_sandbox import Sandbox, ALL_TRAFFIC

# Deny all traffic but allow access to specific API servers
sandbox = Sandbox.create(
    network={
        "deny_out": [ALL_TRAFFIC],
        "allow_out": ["1.2.3.4/32", "8.8.8.0/24"]
    }
)
```

>
> **Priority Rule**: `allow_out` (whitelist) always has higher priority than `deny_out` (blacklist). If an IP appears in both lists, it will be **allowed** to access.

---

## Access Services Within Sandbox (Inbound)

Any network service started within the sandbox (such as Web API, Dashboard) can be accessed externally through public URLs.

### Get Public URL

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

# Get hostname exposed by sandbox on port 3000
host = sandbox.get_host(3000)
print(f"Server URL: https://{host}")

# Example output: https://3000-xxxx.sandbox.ucloudai.com
```

### Protect Sandbox Service (Authentication)

By default, these URLs are public. If you want only authorized clients to access, please disable `allow_public_traffic`.

```python
from ucloud_sandbox import Sandbox
import requests

sandbox = Sandbox.create(
    network={"allow_public_traffic": False}
)

# Access to this sandbox now requires a token
token = sandbox.traffic_access_token

# Make request with authentication header
response = requests.get(
    f"https://{sandbox.get_host(8080)}",
)
print(response) # 403
```

### Custom Request Host Header

If your service within the sandbox has special requirements for the `Host` header (e.g., reverse proxy needs to match `localhost`), you can use `mask_request_host` to rewrite it.

```python
# Rewrite the Host header of requests entering the sandbox to localhost:port
sandbox = Sandbox.create(
    network={
        "mask_request_host": "localhost:${PORT}"
    }
)
```

>
> `${PORT}` is a dynamic placeholder that will be automatically replaced with the actual port number of the request at runtime.