Run long-running sandboxes

CoreWeave sandboxes can run for up to 30 days (2,592,000 seconds) with either Serverless or CoreWeave Kubernetes Service (CKS) placement. Set the lifetime when you create the sandbox to give an agent, development environment, or batch workload enough time to finish. This guide shows developers how to request a longer lifetime and administrators how to set a default for sandboxes on a CKS runner.

CoreWeave Serverless sandboxes are in public preview.

Before you begin

Complete the sandbox setup for your placement mode. The Python examples require the cwsandbox package and a CoreWeave API access token in the CWSANDBOX_API_KEY environment variable. Replace [API-ACCESS-TOKEN] with your CoreWeave API access token:

pip install --upgrade cwsandbox
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

For CKS placement, you also need a configured runner on your cluster. Replace [RUNNER-ID] in the examples with that runner’s ID.

Choose a lifetime

The lifetime is an upper bound on how long the sandbox can run. The platform terminates it when the lifetime expires, even if work is still in progress. A workload that finishes or a sandbox that you stop can end sooner.

Setting	Serverless	CKS
Per-sandbox lifetime	Set it in the software development kit (SDK) or sandbox create request.	Set it in the SDK or sandbox create request.
Runner-policy default	Managed by CoreWeave.	An administrator can set `constraints.lifecycle.default_lifetime_seconds` in the runner policy.
Maximum lifetime	30 days.	30 days, including on your own cluster.

An explicit lifetime takes precedence over a runner-policy default. If you omit the lifetime, the platform uses the applicable policy default. If no positive default supplies a lifetime, the platform uses 10 minutes (600 seconds). Set the lifetime explicitly for long-running work instead of relying on a default. The platform rejects requests above 30 days. A value of 0 doesn’t mean unlimited runtime. A CKS policy can’t raise the platform maximum. You can’t extend the lifetime after a sandbox starts. Choose enough time at creation, and plan to save your work before the deadline.

Set the lifetime when creating a sandbox

Use max_lifetime_seconds in Python. The following examples request the full 30 days and print the sandbox ID so you can reconnect later. Choose the tab for your placement mode:

Serverless
CKS

Create a Serverless sandbox

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.run(
    "sleep", "infinity",
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="serverless",
    container_image="python:3.11",
    resources={"cpu": "2", "memory": "4Gi"},
    max_lifetime_seconds=30 * 24 * 60 * 60,
)
sandbox.wait()
print(sandbox.sandbox_id)

Create a sandbox on a CKS runner

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.run(
    "sleep", "infinity",
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    runner_ids=["[RUNNER-ID]"],
    container_image="python:3.11",
    resources={"cpu": "2", "memory": "4Gi"},
    max_lifetime_seconds=30 * 24 * 60 * 60,
)
sandbox.wait()
print(sandbox.sandbox_id)

The script prints the sandbox ID. These examples keep the primary process alive with sleep infinity and leave the sandbox running after the script exits. When you finish using the sandbox, stop it. The same lifetime is available through the other client interfaces:

Interface	Lifetime configuration
Python SDK	`Sandbox.run(max_lifetime_seconds=2592000, ...)`. For shared client defaults, use `SandboxDefaults(max_lifetime_seconds=2592000)`. An explicit argument overrides the client default.
TypeScript SDK	Pass `maxLifetimeSeconds: 2592000` in the options to `client.run()`.
REST API	Set `spec.maxLifetimeSeconds` to `2592000` in the JSON body of `POST /v1/sandboxes`.
Compose file import	Set the top-level request field `maxLifetimeSeconds` to `2592000` on `POST /v1/sandboxes:createFromFile`. The lifetime is a request setting, not a Compose service property.

For complete request formats, see the API reference and Create a sandbox from a Compose file. For Python client defaults, see Sandbox configuration.

Set a default for a CKS runner

A runner-policy default applies to new sandboxes that don’t request their own lifetime. Use this when workloads on a CKS runner should normally receive a longer lifetime. You need the SANDBOX_ADMIN Identity and Access Management (IAM) action to edit the policy. Policy updates replace the whole policy document. Don’t submit the excerpt as a replacement for an existing policy: that would remove its other constraints.

In an interactive terminal, open the runner’s current policy with the authenticated CoreWeave Intelligent CLI:
cwic sandbox runner policy edit [RUNNER-ID]
Set constraints.lifecycle.default_lifetime_seconds to the desired number of seconds. The following YAML is an excerpt showing a 30-day default. Preserve the rest of the existing policy:
Runner policy excerpt
constraints: lifecycle: default_lifetime_seconds: 2592000
Save and close the editor to submit the update. Retrieve the policy to verify the value:
cwic sandbox runner policy get [RUNNER-ID]

You can also update the policy through the managed-runner REST API. In JSON, the field is policy.constraints.lifecycle.defaultLifetimeSeconds. Follow Update a policy for the full read, edit, and replace procedure. The default applies to sandboxes created after the update. It doesn’t extend running sandboxes. A sandbox can explicitly request a different lifetime up to 30 days. Don’t add max_lifetime_seconds to the policy: the field was retired, and CoreWeave Intelligent CLI rejects a policy document that still contains it. The policy supplies a default, while the platform enforces the maximum.

Keep working across client sessions

When a sandbox should outlive the Python script that launches it, create a standalone sandbox, as in the preceding examples. A with Sandbox.run(...) context stops the sandbox when the block exits, even if its configured lifetime is 30 days. A Session also manages cleanup of the sandboxes it owns. See Cleanup patterns. To reconnect from another script, replace [SANDBOX-ID] with the ID printed at creation:

Reconnect to a running sandbox

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.from_id(
    "[SANDBOX-ID]",
    auth=AuthStrategy.COREWEAVE_API_KEY,
).result()
result = sandbox.exec(["echo", "Connected"]).result()
print(result.stdout)

The command prints Connected. Reconnecting doesn’t reset the lifetime. When you finish, stop the sandbox explicitly:

Stop a sandbox

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.from_id(
    "[SANDBOX-ID]",
    auth=AuthStrategy.COREWEAVE_API_KEY,
).result()
sandbox.stop().result()

Plan for expiry

Save results or checkpoints outside the sandbox before its lifetime expires. If a workflow needs more than 30 days, create a replacement sandbox and resume from saved state. For supported storage and snapshot options, see Sandbox volumes and File system snapshots. The sandbox lifetime is separate from the timeout for a command or API request. Increasing timeout_seconds or request_timeout_seconds doesn’t extend the sandbox lifetime. For the differences, see Timeouts.

​Before you begin

​Choose a lifetime

​Set the lifetime when creating a sandbox

​Set a default for a CKS runner

​Keep working across client sessions

​Plan for expiry

Before you begin

Choose a lifetime

Set the lifetime when creating a sandbox

Set a default for a CKS runner

Keep working across client sessions

Plan for expiry