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

# Secure access to sandbox services

> Understand secure SDK access and traffic access tokens for sandbox URLs, require a token on every request, and change the settings on a sandbox.

A sandbox can be reached in two ways: through the SDK, which runs commands and reads or writes files, and through the sandbox URLs `https://{port}-{sandboxId}.{domain}`, which expose the services started inside it. Each way has its own option and its own token.

> [!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).

## Access modes

| Option | What it protects | Token | Who uses the token |
| - | - | - | - |
| `secure` | SDK operations: running commands, reading and writing files, PTY sessions, and signed upload or download URLs | Access token | The SDK. It is attached to every request automatically and never needs to be read. |
| `network.allowPublicTraffic` | Sandbox URLs for the services started inside the sandbox | Traffic access token | Your own clients. Read it from the sandbox object and pass it to whoever calls the URL. |

When `secure` is `false`, SDK operations accept requests without a token. Anyone who knows the sandbox ID can run commands and read or write files in the sandbox. Upload and download URLs are no longer signed, so anyone who obtains one can use it. When `allowPublicTraffic` is `true`, anyone who knows the sandbox ID can open the services running in it.

> [!NOTE]
>
> Secure access is turned on automatically whenever a sandbox is created. Sandbox URLs stay public unless `allowPublicTraffic` is set to `false`.

## Private sandbox URLs

Set `network.allowPublicTraffic` to `false` to require a traffic access token on every request to the sandbox URLs. The API issues the token when the sandbox is created, and the SDK exposes it on the sandbox object.

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

ppio = PPIO()
sandbox = ppio.sandbox.create(
    template='code-interpreter-v1',
    secure=True,  # Default. Protects SDK operations.
    network={
        'allow_public_traffic': False,  # Protects the sandbox URLs.
    },
)

sandbox.commands.run('python3 -m http.server 3000', background=True)

url = f'https://{sandbox.get_host(3000)}'
print('Private URL:', url)
print('Traffic access token:', sandbox.traffic_access_token)

sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({
  template: 'code-interpreter-v1',
  secure: true, // Default. Protects SDK operations.
  network: {
    allowPublicTraffic: false, // Protects the sandbox URLs.
  },
})

await sandbox.commands.run('python3 -m http.server 3000', { background: true })

const url = `https://${sandbox.getHost(3000)}`
console.log('Private URL:', url)
console.log('Traffic access token:', sandbox.trafficAccessToken)

await sandbox.kill()
```

Clients send the traffic access token in the `Sandbox-Traffic-Access-Token` header.

**Sandbox-Traffic-Access-Token** `string` *required*

Requests without it, or with a wrong token, are rejected.

```bash theme={null}
# Private URL of the service on port 3000, as returned by getHost(3000)
curl -H "Sandbox-Traffic-Access-Token: $TRAFFIC_ACCESS_TOKEN" \
  https://3000-{sandbox_id}.{domain}
```

> [!WARNING]
>
> The traffic access token grants access to the services in the sandbox. Hand it only to the clients that should reach them, such as a browser session or a backend that proxies requests, and keep it out of logs and public pages.

> [!NOTE]
>
> `trafficAccessToken` is `undefined` in Node.js and `traffic_access_token` is `None` in Python when the sandbox URLs are public.

## Switch an existing sandbox to secured access

`secure` and `allowPublicTraffic` are fixed while a sandbox is running. An existing sandbox can be moved to secured access in two ways: pause the sandbox and pass the new values to `connect()`, or call `reset()` on a running sandbox. Both apply the new values when the sandbox starts again.

> [!WARNING]
>
> Switching to secured access with `connect()` is one-way. Once `secure` is `true`, `connect()` cannot set it back to `false`. Once `allowPublicTraffic` is `false`, `connect()` cannot set it back to `true`. To get a sandbox without these protections, create a new one.

## Pause and connect

> [!WARNING]
>
> `connect()` applies `secure` and `allowPublicTraffic` only when it resumes a paused sandbox. Pause the sandbox first. On a running sandbox, `connect()` keeps the current settings and the new values have no effect.

Pause the sandbox, then pass the new values to `connect()`. They take effect when the sandbox resumes.

**1. Pause the sandbox**

```python Python theme={null}
sandbox.pause()
```

```javascript Node.js theme={null}
await sandbox.pause()
```

**2. Pass the new values to connect()**

```python Python theme={null}
resumed = ppio.sandbox.connect(
    sandbox_id,
    timeout=300,
    secure=True,
    allow_public_traffic=False,
)
```

```javascript Node.js theme={null}
const resumed = await ppio.sandbox.connect(sandboxId, {
  timeoutMs: 300_000,
  secure: true,
  allowPublicTraffic: false,
})
```

### Full example

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

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

sandbox.commands.run('echo hello > /tmp/message.txt')
sandbox_id = sandbox.sandbox_id
sandbox.pause()

# The new options are applied when the paused sandbox resumes.
resumed = ppio.sandbox.connect(
    sandbox_id,
    timeout=300,
    secure=True,
    allow_public_traffic=False,
)

print('Traffic access token:', resumed.traffic_access_token)

result = resumed.commands.run('cat /tmp/message.txt')
print(result.stdout)  # hello

resumed.kill()
```

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

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

await sandbox.commands.run('echo hello > /tmp/message.txt')
const sandboxId = sandbox.sandboxId
await sandbox.pause()

// The new options are applied when the paused sandbox resumes.
const resumed = await ppio.sandbox.connect(sandboxId, {
  timeoutMs: 300_000,
  secure: true,
  allowPublicTraffic: false,
})

console.log('Traffic access token:', resumed.trafficAccessToken)

const result = await resumed.commands.run('cat /tmp/message.txt')
console.log(result.stdout) // hello

await resumed.kill()
```

> [!NOTE]
>
> On `create()`, `allowPublicTraffic` is nested under `network`. On `connect()` and `reset()`, it is a top-level option.

## Reset

`reset()` clears the sandbox memory, applies the new values, and by default starts the sandbox again right away. Processes that were started are gone, so restart any service after the reset. Pass `resume: false` to leave the sandbox paused instead.

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

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

# Clear memory, apply the new options, and start the sandbox again.
ok = sandbox.reset(
    timeout=300,
    secure=True,
    allow_public_traffic=False,
)
print('Reset succeeded:', ok)
print('Traffic access token:', sandbox.traffic_access_token)

# Reconnect to pick up the new access token for SDK operations.
secured = ppio.sandbox.connect(sandbox.sandbox_id)
result = secured.commands.run('echo hello')
print(result.stdout)  # hello

secured.kill()
```

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

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

// Clear memory, apply the new options, and start the sandbox again.
const ok = await sandbox.reset({
  timeoutMs: 300_000,
  secure: true,
  allowPublicTraffic: false,
})
console.log('Reset succeeded:', ok)
console.log('Traffic access token:', sandbox.trafficAccessToken)

// Reconnect to pick up the new access token for SDK operations.
const secured = await ppio.sandbox.connect(sandbox.sandboxId)
const result = await secured.commands.run('echo hello')
console.log(result.stdout) // hello

await secured.kill()
```

## Disable secured access

> [!WARNING]
>
> Disabling `secure` lets anyone who knows the sandbox ID run commands and read or write files in the sandbox. It is not recommended.

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

ppio = PPIO()
sandbox = ppio.sandbox.create(secure=False)  # Explicitly disable.

sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({ secure: false }) // Explicitly disable.

await sandbox.kill()
```

```bash CLI theme={null}
# Explicitly disable secure access (not recommended in production)
ppio sandbox create base --no-secure -d

# Explicitly enable secure access
ppio sandbox create base --secure -d
```


## Related topics

- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)
- [Control internet access and expose ports](https://docs.ppio.ai/sandbox/internet-access.md)
- [Build a template with the SDK](https://docs.ppio.ai/sandbox/templates/build.md)


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