Skip to main content
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.
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 and Install and authenticate.

Access modes

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.
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.
Clients send the traffic access token in the Sandbox-Traffic-Access-Token header.
string
required
Requests without it, or with a wrong token, are rejected.
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.
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.
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

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

2

Pass the new values to connect()

Full example

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.

Disable secured access

Disabling secure lets anyone who knows the sandbox ID run commands and read or write files in the sandbox. It is not recommended.
Last modified on November 19, 2026