Skip to main content
Explain routing without creating

Authorizations

Authorization
string
header
required

BoxRouter API key; never an upstream provider key.

Body

application/json

The creation body without request-only secret_values; omission is an empty object.

The creation request shape without request-only secret values. registry_credentials is accepted, as on create, so a private_oci body can be sent unchanged to match.

lifetime_seconds
integer | null

The sandbox's lifetime in seconds, starting when BoxRouter begins creation on the selected route. Creation time counts, so less time may remain when the sandbox is ready. The minimum is 60 seconds. The requested value is matched against the route's max_lifetime_seconds, and a credit-funded sandbox reserves credits for all of it.

Leave it out for a credit-funded sandbox on a route that can extend a lifetime (extendable_lifetime) and the sandbox runs for as long as the workspace's credit balance covers it: credits are reserved one hour at a time and renewed before each hour ends. funded_until on the sandbox says when the current reservation ends; the sandbox ends then if the balance could not cover another hour. Left out on any other create (a route that cannot extend a lifetime, or a sandbox paid with the workspace's own provider account), it is 300 seconds.

Null asks for a sandbox with no lifetime: it runs until you destroy it. Only a provider that never ends a sandbox serves it, and only on the workspace's own provider account; leave at_end out with it.

Required range: x >= 60
at_end
enum<string>
default:destroy

What happens when the lifetime is used up. pause needs pause_resume in requirements. Refused with invalid_request when lifetime_seconds is null, because nothing ends that sandbox.

Available options:
destroy,
pause
requirements
object
required if secret_values is set

The gates this sandbox may use, each holding its knobs and its settings side by side. A sandbox may use only the baseline and the gates named here: a call to any other gate is refused with not_named, on every adapter. Every gate the spec names is accepted here, including the ones no adapter implements yet: whether one can be granted is matching's answer, so a gate nothing declares, or no loaded report proves, leaves the request without a route rather than making it invalid.

resources
object

Resource constraints, execution limits, and environment facts that must hold for this sandbox. The matcher compares each named value with declared resources and capabilities; fields left out impose no requirement.

preferences
object
conditionally required

The one provider-preference contract shared by sandbox creation, launch placement and Actions policy settings. Every property is optional; omitted properties inherit. Precedence, narrowest last: workspace restrictions are the ceiling, then a repository default or named Actions policy, then a workflow, then request controls. Hard restrictions (provider allowlists, route, account, supply, region, privacy, origin and spend) intersect and can only narrow; request ignore unions with workspace exclusions. A request true never lifts a workspace allow_fallbacks false. When workspace prevent_overrides is on, containing order, sort or allow_fallbacks is refused with routing_overrides_forbidden even if the value matches the workspace; only still narrows as a set and cannot reorder workspace ranking. Otherwise soft preference values replace inherited values without widening authority. order: [] and ignore: [] are valid empty soft arrays that name no preference and no exclusion; inherited hard authority is unchanged. Each list must hold distinct values; null is never valid for any property. order prioritizes named providers in listed order; eligible providers omitted from it remain candidates afterward, ranked by the existing router order. When only is supplied, it remains the hard ordered allowlist and caps eligible providers; order may rearrange its members, while omitted members retain only order. ignore excludes providers even when named by only or order. sort ranks routes within a provider. allow_fallbacks defaults to true and controls whether creation may dispatch a later eligible route after a provider definitively refuses before creating a sandbox. This includes another account for the same provider. False stops after the first route dispatch. Eligibility and preparation may skip a route before dispatch. Provider, account, supply, payer and requirements constraints remain binding.

privacy
object

Optional privacy requirements for a sandbox request. Omitted values inherit the workspace and customer-key floors; omission never resets them. Supplied values may only tighten those floors. data_collection: deny requires both no model training and zero provider data retention; a route that retains logs does not satisfy deny, even when zdr is false. zdr: true independently requires zero retention and is not a training-policy predicate. Neither setting consents to BoxRouter capture or promises that an eligible provider or end-to-end zero-retention route exists. boxrouter_content_retention separately restricts BoxRouter sandbox-content handling. Transient wins over ordinary across workspace, key, request and immutable origin floors; an ordinary request cannot relax an inherited transient floor. Unsupported transient operations and unqualified routes are refused. Omission preserves inheritance and the legacy combined meaning of request zdr: true; explicitly choosing ordinary separates BoxRouter retention from provider ZDR.

route
object

The remaining route filters. Each singular value is a hard pin: id and account_id name exactly one route or connected account and supply one funding authority. Fallback never moves a pin, a volume remains attached to its selected route, and these filters only narrow workspace restrictions.

volume
object
image

Omitted selects BoxRouter's standard image. "provider_default" opts out and runs the provider's own default. Any other string is an OCI image reference. Use a one-key dockerfile or provider_artifact object for those artifact sources; the latter requires exactly one value in preferences.only. Use {private_oci} for an image whose registry needs a login, together with registry_credentials; it runs only on routes that use your own provider keys. Every selected image must contain bash and sha256sum.

Allowed value: "provider_default"
registry_credentials
object

Request-only login for the registry named by a private_oci image; required with it and refused without it. Both strings are non-empty, at most 64 KiB UTF-8 bytes together (enforced outside JSON Schema). It is passed to the provider to set up a copy of the image and is never stored, logged, traced, returned or included in idempotency records.

env
object

Creation-time environment, limited by the server to 64 KiB total UTF-8 bytes. This byte limit is enforced outside JSON Schema validation. Never returned, logged or stored.

secret_refs
object

Explicit saved workspace secret references by destination environment name.

secret_values
object

Request-only values delivered through the hidden_secrets gate. Values are sent once during sandbox creation. The server enforces a 16 KiB per-value and 64 KiB total UTF-8 byte limit outside JSON Schema validation. Values are never stored, logged, traced, returned, or included in idempotency records. Use the matching placeholder from the response in configuration.

labels
object

BoxRouter labels, returned on the sandbox; not implicitly provider tags.

Response

Routing explanation for this body. An empty eligible list is not an error when candidates were considered and excluded; a workspace with no candidate at all answers 409 no_eligible_route.

What creating with the same body would do, without provisioning, reserving or recording anything. An empty eligible list is a 200 for ordinary capability exclusions. With a payer, typed funding refusals appear as exclusions when another funding candidate remains eligible; if every funding candidate is refused, the request returns the selected typed refusal as an error. A workspace with no provider key and no credits gets a 409 no_eligible_route naming both remedies; a workspace with no candidate at all also gets a 409 no_eligible_route. Matched classes omitted by the one-class-per-route selection appear in excluded.

spec_version
string
required
Pattern: ^(boxspec|sandbox-provider-spec)/[0-9]+\.[0-9]+(-draft(\.[0-9]+)?)?$
request
object
required

The body as matched, with profiles expanded and defaults filled in.

eligible
object[]
required

The eligible candidates, in the order creation would try them.

excluded
object[]
required
nearest
object[]
required

The smallest changes that would make a route eligible, fewest changes first, then most routes gained. A change maps a dotted path in the request to its new value, null meaning remove it.

closest
object | null
required

The excluded candidate that failed the fewest checks, or null when none was excluded.