Configure a sandbox policy

This page shows how to author the policy that governs sandboxes on a cluster: bounding compute, images, network access, and security posture, and setting the defaults every sandbox inherits. It is written for administrators who manage runners. A policy is carried on the runner, so you author it by updating the runner. There is no separate policy resource and no policy endpoint. For how a sandbox resolves against a policy, see Policies overview.

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

Before you begin

You need the sandbox_admin role in your organization. Reading or writing a policy without it returns PermissionDenied. To use the CLI examples, install and authenticate the CoreWeave Intelligent CLI. To use the REST examples, you need a CoreWeave API token. Examples use $TOKEN for that token and prod-us-east-1 for the runner. Every runner carries exactly one policy, and the policy is required. A policy with no base and no constraints is valid and declares a fully permissive posture, so an operator always states the posture explicitly rather than inheriting one by accident.

Read the current policy

Start from what the runner has now, rather than from an empty document.

CLI
curl

cwic sandbox runner policy get prod-us-east-1

Add describe for a detailed view, which names the not-configured state explicitly when a runner has no policy:

cwic sandbox runner policy describe prod-us-east-1

With -o json, a runner that has never been configured returns null rather than {}, so automation can tell “never configured” apart from “configured and permissive”.

Read a runner and its policy

curl https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN"

Update a policy

A policy is a field on the runner, so you set it by updating the runner with an update mask of policy. A policy update always replaces the entire document. Only policy is implemented as an update mask path, so you cannot patch one constraint group and leave the rest untouched. Read the current policy, change what you need, and send the whole document back.

CLI
curl

Edit the policy in $EDITOR, seeded with the runner’s current document:

cwic sandbox runner policy edit prod-us-east-1

Apply a document from a file, or from stdin with -:

cwic sandbox runner policy edit prod-us-east-1 -f policy.yaml

To start from a scaffold rather than the current document, print a template:

cwic sandbox runner policy edit prod-us-east-1 --print-template

Check a document before sending it:

cwic sandbox runner policy validate -f policy.yaml

Set the policy on a runner

curl -X PATCH https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "managedRunner": {
      "policy": {
        "displayName": "Shared agent pool",
        "constraints": {
          "resources": { "maxCpu": "8", "maxMemory": "32Gi", "requireLimits": true },
          "lifecycle": { "maxLifetimeSeconds": 86400 }
        }
      }
    },
    "updateMask": "policy"
  }'

Three rules apply to every policy write:

A policy must bound sandbox lifetime. Set constraints.lifecycle.maxLifetimeSeconds to a value greater than zero, which guarantees that every sandbox on the runner self-terminates. cwic rejects a policy without one before it calls the API. Lifetime is the one constraint that clamps rather than rejects: a sandbox asking for longer receives the maximum.
A configured policy cannot be cleared. There is no delete operation, and the API rejects an update that sets the policy to null. To loosen a posture, replace the document with a more permissive one.
A policy document is capped at 256 KiB once encoded.

Because every write replaces the whole document, two administrators editing the same runner can overwrite each other. Read immediately before you write.

Policy changes apply to sandboxes created after the update. Running sandboxes keep the policy they resolved against at launch, and the gateway’s cached copy can lag briefly, so a placement made moments after a write may still resolve against the previous policy.

Policy commands read and write the v1 API, while the other cwic sandbox runner and cwic sandbox profile commands still use v1beta2. Both are reached through the same --api-url.

Set a default policy for new runners

A runner that has never been used has no policy, and a sandbox that lands on it is rejected with CWSANDBOX_POOL_POLICY_NOT_CONFIGURED. To avoid configuring every runner by hand, a deployment can define a default that is written to a runner the first time v1 placement selects it. The default lives in the gateway infrastructure configuration at gateway.infraConfig.default_runner_policy, and changing it requires a gateway restart. There is no built-in default. When the setting is absent or null, nothing is written and the sandbox is still rejected with CWSANDBOX_POOL_POLICY_NOT_CONFIGURED. Two behaviors are worth knowing before you rely on it:

The default is a snapshot, not a link. Once materialized onto a runner, the policy is an ordinary runner policy. Later changes to default_runner_policy do not reach runners that already have one. Update those with UpdateManagedRunner.
An invalid default degrades creation. The gateway validates the configured policy at startup. If it does not validate, the gateway still starts, but sandbox creation fails with CWSANDBOX_SERVERLESS_MISCONFIGURED.

Constrain compute

resources bounds what a container may request, and supplies the values used when a sandbox asks for nothing.

{
  "constraints": {
    "resources": {
      "minCpu": "500m",
      "maxCpu": "8",
      "defaultCpu": "2",
      "minMemory": "1Gi",
      "maxMemory": "32Gi",
      "defaultMemory": "4Gi",
      "requireLimits": true
    }
  }
}

Set requireLimits to true to reject sandboxes that do not declare both CPU and memory limits. Use cpuCeiling and memoryCeiling to cap the resolved total for a sandbox, which matters when the base layer contributes containers of its own.

Constrain images

image restricts where sandbox images may come from. An empty group permits any image.

{
  "constraints": {
    "image": {
      "allowedRegistries": ["ghcr.io/[YOUR-ORG]"],
      "allowedImages": ["ghcr.io/[YOUR-ORG]/agent-base:2024.11"]
    }
  }
}

Constrain network access

Network constraints work as an envelope. A sandbox declares the access it needs, and the policy decides whether that request fits. The policy never adds access a sandbox did not ask for. Two settings do separate jobs:

allowedEgress is the entitlement envelope, checked when a sandbox is created. When it is non-empty, every rule the sandbox declares must fit inside it, and a rule outside it is rejected rather than narrowed. Empty means anything is declarable.
defaultEgress is what an absent request means. It applies only when the sandbox declares no egress of its own, and any declaration displaces it entirely.

A rule names one destination. Use cidr with optional except carve-outs, tenant for a relationship to other sandboxes, or any. Optional ports narrow the rule further.

{
  "constraints": {
    "network": {
      "allowedEgress": [
        { "cidr": { "cidr": "0.0.0.0/0", "except": ["10.0.0.0/8", "169.254.169.254/32"] } },
        { "tenant": "TENANT_SCOPE_SAME_ORG" }
      ],
      "defaultEgress": [
        { "tenant": "TENANT_SCOPE_SAME_ORG" }
      ]
    }
  }
}

The example permits the public internet while carving out private space and the instance metadata address, and permits sandboxes to reach other sandboxes in the same organization. A sandbox that declares nothing gets same-organization access only. Tenant scopes are TENANT_SCOPE_SAME_USER and TENANT_SCOPE_SAME_ORG. A third value, TENANT_SCOPE_SANDBOX_NETWORK, is not supported yet and an egress rule using it is rejected. Ingress follows the same shape through allowedIngress and defaultIngress, for ports the sandbox exposes. Ingress rules accept cidr, tenant, or any, and never name-based sources, because inbound packets carry no name.

Ingress is not enforced yet. A sandbox that declares ingress rules is rejected, so setting allowedIngress or defaultIngress has no effect today.

DNS-name destinations are not enforced yet. A sandbox that declares one is rejected, so grant access by address range instead.

Constrain security posture

security governs in-guest privilege and the isolation the sandbox runs under.

{
  "constraints": {
    "security": {
      "allowPrivileged": false,
      "allowedCapabilities": ["NET_BIND_SERVICE"],
      "allowedSeccompProfiles": ["RuntimeDefault"],
      "allowedRuntimeClasses": ["kata-qemu"],
      "defaultCpuRuntimeClass": "kata-qemu"
    }
  }
}

allowedRuntimeClasses fails closed. An empty or absent list permits no runtime class pin at all, so a sandbox can only select a class when you list one explicitly. Set defaultCpuRuntimeClass and defaultGpuRuntimeClass to choose what a sandbox gets when it pins nothing.

Constrain instances, lifetime, metadata, and volumes

The remaining groups are small.

Group	Fields	Effect
`instance`	`allowedInstanceTypes`	Restricts which node instance types a sandbox may land on.
`lifecycle`	`maxLifetimeSeconds`, `defaultLifetimeSeconds`	Caps how long a sandbox may live, and what it gets when it asks for nothing. `maxLifetimeSeconds` is required and must be greater than zero. A sandbox asking for more is clamped to it.
`metadata`	`deniedAnnotationPrefixes`, `maxAnnotationCount`	Rejects annotation keys by prefix and caps how many a sandbox may set. `0` means no limit.
`volumes`	`allowedMedia`, `maxSize`	Restricts storage media and caps per-volume size. Omit `STORAGE_MEDIUM_MEMORY` to forbid RAM-backed volumes.

{
  "constraints": {
    "lifecycle": { "maxLifetimeSeconds": 86400, "defaultLifetimeSeconds": 3600 },
    "volumes": { "allowedMedia": ["STORAGE_MEDIUM_DISK"], "maxSize": "100Gi" }
  }
}

The base layer

Constraints bound what a sandbox may ask for. The base layer is intended to supply what every sandbox gets without asking: defaults and attachments such as the scheduler, node selectors, tolerations, service accounts, and image pull secrets. Its shape depends on the runner runtime, and on a Kubernetes runner it is a pod specification fragment.

base is not applied today. The policy engine passes it through untouched and leaves enforcement to the runtime, so a base fragment you set has no effect on the sandboxes a runner places.To pin a scheduler, node selectors, or tolerations now, use a profile template on the v1beta2 surface. See SUNK Pod Scheduler integration for a worked example.

Next steps

Policies overview: how a sandbox resolves against a policy, and what changed from profiles.
Deploy and manage a runner: the runner lifecycle and the rest of the runner configuration.
Control plane API overview: authentication, field masks, and the endpoint contract.

​Before you begin

​Read the current policy

​Update a policy

​Set a default policy for new runners

​Constrain compute

​Constrain images

​Constrain network access

​Constrain security posture

​Constrain instances, lifetime, metadata, and volumes

​The base layer

​Next steps

Before you begin

Read the current policy

Update a policy

Set a default policy for new runners

Constrain compute

Constrain images

Constrain network access

Constrain security posture

Constrain instances, lifetime, metadata, and volumes

The base layer

Next steps