Sandbox Networking

A sandbox that opens a port can be served over HTTPS on a hostname under your own domain. You configure networking on the cluster once, and every sandbox that exposes a port gets a URL under your domain, either minted automatically from the sandbox name or chosen by you at create time.

Sandboxes are in a private beta. Please reach out to us at support@porter.run or over Slack if you are interested in joining.

How it works

You bring a domain you own (for example sandbox.acme.com), and Porter provisions a load balancer and a wildcard HTTPS certificate for it on your sandbox cluster. A cluster supports two kinds of networking, each with its own domain:

Networking	Load balancer	Who can reach sandboxes
Public	Internet-facing	Anyone on the internet
Private	Internal	Clients inside your VPC

Enable public networking, private networking, or both. Each sandbox that opens a port is served at a hostname one label under the configured domain, such as my-app.sandbox.acme.com, with TLS handled by the wildcard certificate.

What sandboxes can reach

Sandboxes run untrusted code, so their outbound traffic is isolated by default, whether or not networking is configured. A sandbox can resolve DNS and reach the public internet, and nothing else:

Destination	Reachable
Public internet	Yes
Cluster DNS	Yes
In-cluster services and other pods (including other sandboxes)	No
Kubernetes API server and the sandbox control plane	No
Cloud metadata endpoint (`169.254.169.254`)	No
Private address space (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `100.64.0.0/10`)	No

Because private address space is blocked, this includes services behind a private load balancer. If a sandbox needs to call a service you run on the same cluster, either expose that service on a public domain and call it over the internet, or give the sandbox an egress allowlist that includes the service’s cluster-internal hostname (see below).

Restrict egress with an allowlist

Beyond the default isolation, a sandbox can be limited to an explicit list of outbound destinations. Pass egress when creating a sandbox and it can only reach the destinations it lists; all other outbound traffic is blocked. Enforcement happens transparently at the network layer, so any protocol and client works without proxy configuration. Egress enforcement is off by default. To turn it on for a cluster, go to the Sandbox tab, open Settings, and enable Enforce egress allowlists under Egress controls. This installs network policy enforcement on the sandbox nodes. Sandboxes created without an egress entry keep unrestricted internet access even when enforcement is on.

sandbox = porter.sandboxes.create(
    image="ghcr.io/example/agent:latest",
    name="restricted",
    egress={"allowed_destinations": ["api.stripe.com", "*.github.com"]},
)

const sandbox = await porter.sandboxes.create({
  image: "ghcr.io/example/agent:latest",
  name: "restricted",
  egress: { allowed_destinations: ["api.stripe.com", "*.github.com"] },
});

An allowed_destinations entry is one of:

Entry	Matches
`api.example.com`	That exact hostname
`*.example.com`	Any host under the domain, but not the domain itself
`203.0.113.7`	That IP address
`203.0.113.0/24`	Any address in the CIDR range
`payments.billing.svc.cluster.local`	The backing pods of the `payments` Service in the `billing` namespace on the sandbox’s cluster

An empty list denies all egress. DNS resolution keeps working inside the sandbox so hostname entries can be resolved and enforced. CIDR entries are honored as written, including private address space, so an allowlist can deliberately grant a sandbox access to internal IPs that the default isolation blocks. A Service entry is how a restricted sandbox reaches another workload on its own cluster: an entry of the form name.namespace.svc.cluster.local allows traffic to that Service’s backing pods and tracks them as they change, so a rolling deploy of the Service doesn’t interrupt connectivity. Service entries aren’t scoped to a port; any port on the backing pods is allowed.

Configure networking on the cluster

Open the sandbox networking settings

In the Porter Dashboard, go to the Sandbox tab for your sandbox-enabled cluster, then open Settings. The Public and Private networking sections each have their own toggle.

Set the domain

Enable the kind of networking you want and enter the domain sandbox hostnames should be minted under, for example sandbox.acme.com for public networking or internal.sandbox.acme.com for private. Each needs its own domain.

Connect your DNS provider

Porter issues the wildcard certificate through a Let’s Encrypt DNS-01 challenge, which needs access to the DNS zone that contains your domain.Cloudflare: create an API token and paste it into the networking settings.

In the Cloudflare dashboard, go to your profile icon > My Profile > API Tokens (or directly at dash.cloudflare.com/profile/api-tokens) and click Create Token.
Use the Edit zone DNS template. It grants the one permission Porter needs: Zone / DNS / Edit.
Under Zone Resources, scope the token to Include / Specific zone and select the zone that contains your sandbox domain (the zone acme.com for a domain like sandbox.acme.com).
Continue to the summary, create the token, and copy it. Cloudflare shows the token value only once.
Paste it into the section’s API token field in Porter and save.

Each networking section stores its own token, so public and private are credentialed separately (one token can be pasted into both).AWS Route53: no token needed. Porter authenticates through the cluster’s pod identity.

Create the wildcard DNS record

Save the settings, then wait for the load balancer to provision. The settings page shows the record target and type once it’s ready: create a DNS record for *.<your domain> (for example *.sandbox.acme.com) pointing at that address.For private networking, the load balancer address only resolves to something reachable from inside your VPC. Point your own private DNS at it if your clients resolve through one; certificates are still issued automatically either way.

Expose a port from a sandbox

Pass networking when creating a sandbox. A sandbox with no networking entry exposes nothing. Currently one entry is supported, and its port is required (1024-65535; privileged ports are not allowed):

sandbox = porter.sandboxes.create(
    image="ghcr.io/example/web:latest",
    name="my-app",
    networking=[{"port": 8080}],
)

const sandbox = await porter.sandboxes.create({
  image: "ghcr.io/example/web:latest",
  name: "my-app",
  networking: [{ port: 8080 }],
});

With no domain specified, the sandbox is served at <name>.<your domain> (falling back to <id>.<your domain> when the sandbox has no name), publicly when public networking is configured on the cluster, otherwise privately.

Choose the hostname and visibility

Add a domains entry to control where the port is served. Currently one entry is supported:

sandbox = porter.sandboxes.create(
    image="ghcr.io/example/web:latest",
    name="my-app",
    networking=[
        {
            "port": 8080,
            "domains": [
                {"domain": "my-app.sandbox.acme.com", "visibility": "public"},
            ],
        }
    ],
)

const sandbox = await porter.sandboxes.create({
  image: "ghcr.io/example/web:latest",
  name: "my-app",
  networking: [
    {
      port: 8080,
      domains: [{ domain: "my-app.sandbox.acme.com", visibility: "public" }],
    },
  ],
});

Field	Description
`domain`	Fully qualified hostname for the sandbox, one label under the domain configured for the chosen visibility (`my-app.sandbox.acme.com` under `sandbox.acme.com`). Unlike sandbox names, domains don’t have to be unique: successive sandboxes can reuse a hostname, though only one may be live on it at a time.
`visibility`	`public` or `private`: whether the sandbox is served publicly or inside your VPC when the cluster has both configured. Omit to default to whichever is configured, public winning. Creating a sandbox that requests a visibility the cluster doesn’t have configured is rejected.

Find the sandbox URL

The sandbox’s status includes host, the hostname it’s reachable at. It’s empty when the sandbox exposes no port or the cluster has no networking configured:

status = sandbox.refresh()
print(f"https://{status.host}")

const status = await sandbox.refresh();
console.log(`https://${status.host}`);

Documentation

Sandbox Networking

How it works

What sandboxes can reach

Restrict egress with an allowlist

Configure networking on the cluster

Expose a port from a sandbox

Choose the hostname and visibility

Find the sandbox URL

Next steps

​How it works

​What sandboxes can reach

​Restrict egress with an allowlist

​Configure networking on the cluster

​Expose a port from a sandbox

​Choose the hostname and visibility

​Find the sandbox URL

​Next steps

How it works

What sandboxes can reach

Restrict egress with an allowlist

Configure networking on the cluster

Expose a port from a sandbox

Choose the hostname and visibility

Find the sandbox URL

Next steps