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.

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 (unless allowlisted, see below)
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 an EKS Pod Identity scoped to a single hosted zone, so the sandbox domain needs its own public hosted zone in the cluster’s AWS account. A parent zone such as acme.com doesn’t work.

In the Route53 console, create a public hosted zone named exactly the sandbox domain (internal.sandbox.acme.com for a domain of internal.sandbox.acme.com). Note the four NS values Route53 assigns to it.
In the parent zone (acme.com), add an NS record for the sandbox domain with those four values. This delegates the subdomain to the new zone.
Enter the same domain in the networking settings and save. Porter resolves the zone on the next cluster update and provisions the pod identity.
When you create the wildcard record in the next step, put it in the new zone, not the parent. Records for a delegated subdomain that sit in the parent zone aren’t served.

This is the same hosted zone rule as the private load balancer’s Route53 setting, which covers it in more detail.

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.The record must be a wildcard. Each sandbox is served at its own hostname under the domain, so a record for the bare domain or for a single hostname only routes that one name. On most providers this is a CNAME. On Route53, prefer an alias A record pointing at the load balancer: it resolves in one lookup and Route53 doesn’t bill alias queries. A CNAME is also supported if you’d rather use one.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. On a cluster with no networking configured, the port is served at the sandbox’s cluster-internal address only (see below).

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.

Serve a port inside the cluster only

Set internal: true on the networking entry to keep the sandbox off both load balancers. It gets no hostname; instead the port is served at a stable cluster-internal address, reachable only from workloads on the same cluster. This needs no networking configured on the cluster and can’t be combined with domains:

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

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

The address is in the sandbox’s status as internal_address, a host:port like sandbox-route-<id>.porter-sandbox.svc.cluster.local:8080. Traffic to it doesn’t go through the load balancer, so it isn’t TLS-terminated: the connection carries the protocol the workload serves on that port. Reaching it from another sandbox requires an egress allowlist entry for the address’s hostname (see the allowlist section); other workloads on the cluster reach it subject to their own network policy.

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}`);

Every sandbox that opens a port also gets internal_address in its status, even when it’s also served on a hostname.

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

Serve a port inside the cluster only

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

​Serve a port inside the cluster only

​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

Serve a port inside the cluster only

Find the sandbox URL

Next steps