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

# Control internet access and expose ports

> Turn internet access on or off, set outbound allowlists and denylists, expose a service through the sandbox URL, and mask request Host headers.

Internet access is enabled in every sandbox by default, and can be disabled for isolated workloads. Services running inside a sandbox can also be exposed through a public URL. Inbound access to services running in the sandbox is controlled separately, through public sandbox URLs or URLs that require a traffic access token. This page covers both directions: outbound rules and inbound access.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

```mermaid theme={null}
flowchart LR
  C[Client] -->|"sandbox URL, traffic access token if allow_public_traffic=False"| SV
  subgraph SB [Sandbox]
    SV[Service on a port]
  end
  SB -->|"allow_out / deny_out"| D[Outbound destinations]
```

## Toggle internet access

When creating a sandbox, use the `allowInternetAccess` or `allow_internet_access` parameter to configure internet connectivity. Internet access is turned on by default, and can be disabled for workloads with stricter security requirements.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()

# Create a sandbox with internet access enabled (default).
sandbox = ppio.sandbox.create(allow_internet_access=True)

# Create a sandbox without internet access.
isolated_sandbox = ppio.sandbox.create(allow_internet_access=False)

sandbox.kill()
isolated_sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// Create a sandbox with internet access enabled (default).
const sandbox = await ppio.sandbox.create({ allowInternetAccess: true })

// Create a sandbox without internet access.
const isolatedSandbox = await ppio.sandbox.create({ allowInternetAccess: false })

await sandbox.kill()
await isolatedSandbox.kill()
```

```bash CLI theme={null}
# Create a sandbox with internet access enabled (default behavior, no extra arguments)
ppio sandbox create base -d

# Create a sandbox without internet access
ppio sandbox create base --no-internet -d
```

## Fine-grained network control

Network configuration gives finer-grained control over outbound traffic through allowlists and denylists.

| Goal | Setting |
| - | - |
| No outbound internet at all | `allow_internet_access=False` or `allowInternetAccess: false` |
| Only specific destinations | `network.allow_out` or `network.allowOut` with domains, where wildcards such as `*.github.com` work, plus `deny_out: ["0.0.0.0/0"]` or `denyOut: ["0.0.0.0/0"]` |
| Block specific destinations | `network.deny_out` or `network.denyOut` with domains or CIDRs |
| Expose a service on a port | `sandbox.get_host(port)` or `getHost(port)`, which gives the host of `https://{port}-{sandboxId}.{domain}` |
| Require a traffic access token to reach that service | `network.allow_public_traffic=False` or `network.allowPublicTraffic: false`, then send the `Sandbox-Traffic-Access-Token` header |

Set these options when creating the sandbox.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()

# Deny all traffic except specific IPs.
sandbox = ppio.sandbox.create(
    network={
        'deny_out': ['0.0.0.0/0'],
        'allow_out': ['1.1.1.1', '8.8.8.0/24'],
    }
)

# Allow only traffic to selected domains.
domain_sandbox = ppio.sandbox.create(
    network={
        'allow_out': ['api.example.com', '*.github.com'],
        'deny_out': ['0.0.0.0/0'],
    }
)

sandbox.kill()
domain_sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// Deny all traffic except specific IPs.
const sandbox = await ppio.sandbox.create({
  network: {
    denyOut: ['0.0.0.0/0'],
    allowOut: ['1.1.1.1', '8.8.8.0/24'],
  },
})

// Allow only traffic to selected domains.
const domainSandbox = await ppio.sandbox.create({
  network: {
    allowOut: ['api.example.com', '*.github.com'],
    denyOut: ['0.0.0.0/0'],
  },
})

await sandbox.kill()
await domainSandbox.kill()
```

```bash CLI theme={null}
# Deny all traffic except the allowed IPs
# (--allow-out / --deny-out accept comma-separated CIDR lists and can be repeated)
ppio sandbox create base -d \
  --deny-out 0.0.0.0/0 \
  --allow-out 1.1.1.1,8.8.8.0/24
```

## Expose a service through the sandbox URL

Services in a sandbox can be reached through the sandbox URL for a port.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

host = sandbox.get_host(3000)
print(f'https://{host}')

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

const host = sandbox.getHost(3000)
console.log(`https://${host}`)

await sandbox.kill()
```

```bash CLI theme={null}
# Create a sandbox and allow public traffic to access its URL directly
# (--public-traffic makes the sandbox URL accessible without an access token)
ppio sandbox create base --public-traffic -d
```

> [!WARNING]
>
> A sandbox URL with public traffic enabled is reachable without a traffic access token. Set `network.allow_public_traffic` to `false` when a service should require the traffic access token; see [Secured access](https://docs.ppio.ai/sandbox/secured-access.md).

## Connect to a server inside the sandbox

Start a server in the background, read its sandbox URL, then request the URL from outside the sandbox.

**1. Start a server in the background**

```python Python theme={null}
process = sandbox.commands.run('python -m http.server 3000', background=True)
```

```javascript Node.js theme={null}
const process = await sandbox.commands.run('python -m http.server 3000', { background: true })
```

**2. Read its sandbox URL**

```python Python theme={null}
url = f'https://{sandbox.get_host(3000)}'
```

```javascript Node.js theme={null}
const url = `https://${sandbox.getHost(3000)}`
```

**3. Request the URL from outside the sandbox**

```python Python theme={null}
response = requests.get(url)
```

```javascript Node.js theme={null}
const response = await fetch(url)
```

### Full example

```python Python theme={null}
import requests
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

process = sandbox.commands.run('python -m http.server 3000', background=True)
url = f'https://{sandbox.get_host(3000)}'
print('Server started at:', url)

response = requests.get(url)
data = response.text
print('Response from server inside sandbox:', data)

process.kill()
sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

const process = await sandbox.commands.run('python -m http.server 3000', { background: true })
const url = `https://${sandbox.getHost(3000)}`
console.log('Server started at:', url)

const response = await fetch(url)
const data = await response.text()
console.log('Response from server inside sandbox:', data)

await process.kill()
await sandbox.kill()
```

## Mask request Host headers

Use the `maskRequestHost` or `mask_request_host` option to customize the `Host` header sent to services running inside the sandbox.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create(
    network={
        'mask_request_host': 'localhost:${PORT}',
    }
)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({
  network: {
    maskRequestHost: 'localhost:${PORT}',
  },
})

await sandbox.kill()
```


## Related topics

- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)
- [Secure access to sandbox services](https://docs.ppio.ai/sandbox/secured-access.md)
- [Use Git in a sandbox](https://docs.ppio.ai/sandbox/git.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.