Public endpoints - CoreWeave Docs

This page describes how public endpoints work, how to declare one when you create a sandbox, and how to connect to it. A public endpoint gives a service running inside a sandbox an address that clients can reach from the internet. You request one when you create the sandbox, and the platform provisions the routing, DNS, and network access for it. The address belongs to the sandbox for as long as the sandbox runs. Endpoints come in two kinds, which differ in where TLS terminates:

HTTPS: The platform terminates TLS at its edge with a certificate it provisions and renews, then forwards the request to your port as cleartext HTTP.
TLS passthrough: The platform routes the connection to your port by Server Name Indication (SNI) without decrypting it. Your workload terminates TLS and owns its own certificates.

Choose TLS passthrough when the workload must hold the private key itself: mutual TLS, a client that pins a certificate, or a protocol that isn’t HTTP.

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, CoreWeave Support, or email support@coreweave.com.

Compare the two kinds

	HTTPS	TLS passthrough
Terminates TLS	Platform edge	Your workload
Owns certificates	Platform	You
Carries	HTTP, WebSockets over HTTP Upgrade, and Server-Sent Events	Any protocol over TLS
`endpoint.kind`	`HTTPS`	`TLS_PASSTHROUGH`
`endpoint.auth`	`OPEN` (required)	Omit
Read the address from	`service_urls`	`service_addresses`

Both kinds are open to the internet. The platform does not authenticate callers, so the service behind the endpoint is responsible for its own access control.

Declare an endpoint

Declare endpoints in the services list when you create the sandbox. Ports are fixed for the sandbox’s lifetime, and no call exposes a port on a sandbox that is already running. To give a service an endpoint, set visibility=PUBLIC and an endpoint value on it. A service without an endpoint value listens on its port inside the sandbox but gets no public address. For an HTTPS endpoint, set kind=EndpointKind.HTTPS and auth=EndpointAuth.OPEN:

from cwsandbox import (
    Endpoint,
    EndpointAuth,
    EndpointKind,
    Sandbox,
    Service,
    ServiceVisibility,
)

sandbox = Sandbox.run(
    "python3", "-m", "http.server", "8080",
    container_image="python:3.11",
    services=[
        Service(
            port=8080,
            name="web",
            visibility=ServiceVisibility.PUBLIC,
            endpoint=Endpoint(kind=EndpointKind.HTTPS, auth=EndpointAuth.OPEN),
        ),
    ],
)

For a TLS passthrough endpoint, set kind=EndpointKind.TLS_PASSTHROUGH and leave auth unset. The command you run must terminate TLS on the port itself, because the platform forwards the connection without decrypting it:

from cwsandbox import (
    Endpoint,
    EndpointKind,
    Sandbox,
    Service,
    ServiceVisibility,
)

sandbox = Sandbox.run(
    "python3", "/srv/serve_tls.py",
    container_image="python:3.11",
    services=[
        Service(
            port=8443,
            name="tls",
            visibility=ServiceVisibility.PUBLIC,
            endpoint=Endpoint(kind=EndpointKind.TLS_PASSTHROUGH),
        ),
    ],
)

One sandbox can mix both kinds. The following rules apply to every services entry:

Ports must be unique, and any name you set must be unique. Names map to Kubernetes container port names, which require uniqueness.
visibility must be PUBLIC when endpoint is set, and must be left unset when it isn’t. Visibility on its own doesn’t create an endpoint or an address.
protocol must be TCP or unset. The platform rejects UDP and SCTP endpoints.
Omit auth and request_timeout_seconds for TLS passthrough. Pass None rather than 0. A 0 counts as a set value, and the platform rejects the create call.
A platform limit caps how many services one sandbox declares. Operators set the cap, and deployments commonly set it to five.

Read the assigned address

The platform assigns the address. You can’t choose the hostname or supply your own domain. Read it back from the sandbox rather than constructing it, because the DNS zone differs per cluster and isn’t part of the API contract. TLS passthrough addresses arrive on service_addresses as host:port, and HTTPS URLs arrive on service_urls. The two lists stay separate: A TLS endpoint never appears in service_urls.

for endpoint in sandbox.service_addresses:
    print(endpoint.port, endpoint.name, endpoint.address)

You should see output similar to the following:

8443 tls 8443-2f8d41b6-9c3e-4a17-b5d2-7e0a13c64f89.a1b2c3d4.ep2.cwsandbox.com:443

The advertised port is the platform’s TLS listener port, not the port your process binds inside the sandbox. In this example, the workload listens on 8443 and clients connect to 443. The two kinds become readable at different points in the sandbox’s startup:

A TLS passthrough address is assigned when the sandbox is created, so it is on the create response and stays available while the sandbox is creating or running.
An HTTPS URL is empty until the sandbox reaches RUNNING and its route has a hostname. Call get_status() in a loop until the URL appears or your own deadline passes.
Neither one means the application is serving. The platform doesn’t wait for your process to bind the port before reporting the sandbox as running, so retry your first connection.

The platform reports endpoints while a sandbox is creating or running, and clears them in every other state. A paused or completed sandbox has no reachable endpoint.

Connect to a TLS passthrough endpoint

Because the platform doesn’t decrypt the connection, the certificate a client receives is the one your workload presents. Two things follow for the client:

Send the endpoint host as the SNI server name. The platform routes on SNI alone, so a connection that omits it, or sends a different name, doesn’t reach your sandbox.
Trust the workload’s certificate. The endpoint hostname is platform-assigned, so a certificate you issue yourself doesn’t match it unless you issue it for that hostname. Configure the client to trust your own certificate authority, or pin the certificate.

The following client sends the endpoint host as SNI while connecting to the advertised address. Replace [ENDPOINT-ADDRESS] with the address you read from service_addresses, and [PATH-TO-CA-CERT] with the path to the certificate authority that signed your workload’s certificate:

import socket
import ssl

address = "[ENDPOINT-ADDRESS]"  # host:port from service_addresses
host, port = address.rsplit(":", 1)

context = ssl.create_default_context(cafile="[PATH-TO-CA-CERT]")

with socket.create_connection((host, int(port))) as sock:
    with context.wrap_socket(sock, server_hostname=host) as tls:
        print(tls.version(), tls.getpeercert()["subject"])

Endpoint lifetime

An endpoint lives as long as the sandbox that owns it:

It’s keyed to the sandbox, not to a Pod. If the underlying Pod restarts, the address stays the same.
Deleting the sandbox removes the endpoint. The address doesn’t move to another sandbox, and a new sandbox gets a new address.
Nothing is reserved between sandboxes. You can’t hold a hostname for reuse.

Troubleshoot create failures

If no runner in your fleet supports the endpoint kind you requested, the create call fails rather than starting a sandbox with the endpoint silently dropped.

Reason	Meaning
`CWSANDBOX_TLS_PASSTHROUGH_ENDPOINTS_NOT_SUPPORTED`	No runner you can reach is configured for TLS passthrough. Ask your administrator to enable it on a runner.
`CWSANDBOX_NO_SUITABLE_RUNNER`	The sandbox declared both endpoint kinds, and no runner supports both. The response’s `unsupported_endpoint_kinds` metadata names the kinds that are missing.
`CWSANDBOX_INVALID_REQUEST`	A `services` entry breaks one of the rules in Declare an endpoint, such as a duplicate port or `auth` set on a TLS passthrough endpoint.
`CWSANDBOX_NOT_IMPLEMENTED`	The request used a feature that isn’t implemented, such as `auth=TOKEN`.

Sandbox configuration: resources, ports, secrets, and timeouts.
Sandbox architecture: how runners, profiles, and the control plane interact.
Sandbox lifecycle: the states a sandbox moves through.

​Compare the two kinds

​Declare an endpoint

​Read the assigned address

​Connect to a TLS passthrough endpoint

​Endpoint lifetime

​Troubleshoot create failures

​Related pages

Compare the two kinds

Declare an endpoint

Read the assigned address

Connect to a TLS passthrough endpoint

Endpoint lifetime

Troubleshoot create failures

Related pages