Direct sandbox connections

A direct sandbox connection carries exec, log, and file operations straight from your client to the sandbox over mutual TLS (mTLS), instead of relaying them through the CoreWeave Sandbox gateway. Removing the gateway hop lowers latency and raises throughput for workloads that move large amounts of data in and out of a sandbox. Lifecycle and management operations, such as starting a sandbox, listing sandboxes, and stopping one, always use the CoreWeave Sandbox API. A direct connection applies only to data operations on a sandbox that is already running. This page is for developers who use the cwsandbox Python SDK to launch and manage sandboxes. It explains how to choose a transport policy for data operations, how the SDK establishes a direct connection, and how to confirm which transport an operation used.

Overview

The DataPlaneMode enum sets the transport policy for data operations. The SDK uses AUTO unless you choose otherwise, so most callers get direct connections without changing any code.

Mode	Behavior	When to use it
`AUTO`	Prefers a direct mTLS connection and transparently falls back to the gateway when direct access is unavailable.	The default. Use it unless you need to pin one transport.
`DIRECT`	Requires the direct mTLS connection and raises an error when it can’t be established.	Validating that direct connectivity works in your environment.
`GATEWAY`	Always routes data operations through the gateway.	A deterministic rollback path when you need to rule out the direct transport.

Set the transport policy

To set the transport policy for a single sandbox, pass data_plane_mode to Sandbox.run(). To set it for a group of sandboxes, pass data_plane_mode to SandboxDefaults.

from cwsandbox import DataPlaneMode, Sandbox, SandboxDefaults

# AUTO is the default: prefer direct, fall back to the gateway.
with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
    print(result.stdout)

# Require the direct path. Useful when validating connectivity.
with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    print(sandbox.read_file("/etc/hostname").result().decode())

# Force the gateway path for every sandbox that uses these defaults.
defaults = SandboxDefaults(data_plane_mode=DataPlaneMode.GATEWAY)
with Sandbox.run(defaults=defaults) as sandbox:
    print(sandbox.exec(["echo", "gateway"]).result().stdout)

How a direct connection is established

When a sandbox is running and you issue its first data operation, the SDK generates a P-256 private key in memory and sends only a certificate signing request to the CoreWeave Sandbox API. The API returns a certificate scoped to that sandbox, which the SDK uses to open an mTLS connection to the sandbox itself. Two properties of this exchange matter when you reason about credentials:

The private key never leaves the client process. The SDK transmits a certificate signing request, not the key.
Your API bearer token is never sent to the sandbox data endpoint. The sandbox authenticates the client by certificate alone.

The SDK creates credentials lazily, so a sandbox that only ever runs lifecycle calls never requests them. The SDK uses the certificate expiry that the server issues rather than imposing a shorter session lifetime of its own.

Timing and fallback

AUTO and DIRECT differ in how long they wait and in what happens when setup doesn’t finish in time.

In AUTO, credential issuance plus channel readiness share a 1-second budget. If that budget runs out, the operation proceeds over the gateway and the SDK waits 30 seconds before attempting a direct connection again. Falling back is transparent: the operation still succeeds.
In DIRECT, connection setup gets up to 10 seconds, with no fallback. If setup doesn’t complete, the operation raises an error.

Connection reuse

The SDK keeps a process-wide pool of idle direct channels, bounded at 64. Bounding the pool means a program holding a large collection of inactive sandbox objects doesn’t retain one socket per sandbox. An active stream keeps the channel it started on. When a channel is marked stale, existing streams drain on it while new calls create a replacement channel.

Verify which transport an operation used

To confirm that direct connectivity works from your environment, run an operation under DIRECT. Because that mode never falls back, an operation that returns successfully used the direct transport. An operation that can’t establish the connection raises an error instead of silently using the gateway.

from cwsandbox import DataPlaneMode, Sandbox

with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    result = sandbox.exec(["echo", "direct"]).result()
    print(result.stdout)

If this raises an error while the same call under GATEWAY succeeds, the sandbox data endpoint isn’t reachable from your network. Keep callers on AUTO so they keep working over the gateway while you check egress restrictions between your client and the sandbox.

​Overview

​Set the transport policy

​How a direct connection is established

​Timing and fallback

​Connection reuse

​Verify which transport an operation used

​See also