# Routing and policies

Sandbox Router separates **where a sandbox can run**, **which eligible pool to try first**, and **whether each operation is authorized**. Those decisions carry through creation, failover and runtime access.

This guide explains the full routing model. For the fields accepted by a particular API or client, use [The API](/docs/api) and [The TypeScript SDK](/docs/sdk).

## Providers, accounts and pools

A **provider** is the sandbox service. An **account** supplies the credentials and account-specific capacity. A **pool** represents capacity configured on a provider and account, with its supported resources, network and other constraints.

Separate pools can use different accounts on one provider or accounts across providers. For example, a route can try an E2B pool on account A, another E2B pool on account B, then a Daytona pool on account C. These are illustrative accounts, not a recommended provider ranking.

Each attempt uses the selected pool's own credentials and controls. A different pool does not inherit another account's authority. Multiple accounts on the same service can share a provider-wide outage, so they offer a different kind of fallback from using another provider.

## Requirements and preferences

Routing first filters eligible pools, then ranks them. A preference never relaxes a requirement.

### Hard requirements

A pool must satisfy every applicable requirement:

- **Resources and capabilities:** the requested size, image, GPU, execution, snapshot and networking needs.
- **Location:** a geography, normalized region or provider-specific zone.
- **Provider and isolation:** selected providers or an isolation mode such as a particular microVM hypervisor.
- **Security and compliance:** requirements expressed through the pool's published labels, including tenancy, compliance and confidential computing.
- **Network placement:** a bound VPC restricts placement to its topology. Routing cannot move that sandbox to an unrelated network.

A pool that does not satisfy a requirement is excluded, even if it is cheaper or starts faster. If none qualifies, creation cannot proceed with a weaker requirement.

### Ranking preferences

| Priority | What it compares | Preferred direction |
| --- | --- | --- |
| Price | The pool's configured price | Lower |
| Startup latency | Measured time from a creation attempt to the sandbox running on that pool | Lower |
| Creation success | The share of eligible creation attempts that reached a running sandbox | Higher |

Startup latency is not network round-trip latency. Creation success measures provisioning reliability, not the uptime of a process after it starts.

Priorities are ordered. For example, **startup latency, creation success, price** favors faster starts first, uses creation success to distinguish comparable candidates, then considers price. **Price, startup latency** favors lower cost first.

Measured values are compared in bands so small differences do not overwhelm the next priority. A measured metric uses its median. Within a band, the next metric ranks the tied candidates. Pools without a value for a requested metric follow those that have one. Ranking applies when placing the sandbox; changing measurements does not continuously move a running sandbox.

### Combining location and cost

“Lowest cost in US East” means:

1. Keep only pools in US East that satisfy the image, size, capabilities and other hard requirements.
2. Rank those pools by price, followed by any secondary priorities.
3. Attempt creation in that order, subject to each pool's admission checks.

If the cheapest matching pool is full, failover can try the next matching pool. It cannot leave US East unless the requirements permit another region.

## Placement choices

| Choice | Purpose |
| --- | --- |
| Pin a pool | Use one exact destination; capability, capacity and authorization checks still apply |
| Select pool labels | Require matching provider, geography, region, isolation or security properties |
| Pool affinity | Express required matches and weighted preferences over pool labels |
| Sandbox affinity | Place near matching sandboxes within a provider, region or zone |
| Sandbox anti-affinity | Keep away from matching sandboxes within the chosen topology |
| Spread | Balance matching workloads across providers, regions or zones, as a hard rule or a preference |
| Route by metrics | Rank eligible pools by ordered price, startup latency and creation-success priorities |

Pool requirements combine. An isolation requirement must match one complete isolation mode offered by the pool, rather than mixing properties from different modes.

Hard spread rules filter candidates; soft spread and affinity preferences help rank candidates left tied by the route metrics. Capacity and a deterministic name order resolve remaining ties. A pinned pool leaves no alternative pool to rank or fail over to.

The explicit-order interface also supports a workspace Auto order, a per-create override and a named provider. An explicit order is the order supplied by the caller; it does not implicitly sort providers by price. A provider omitted from that order is not used. The Standby Pool is a fallback only when the order includes it and it satisfies the request.

## Creation failover

Creation failover walks an ordered list of eligible pools. The same sandbox ID identifies every attempt.

1. **Filter and rank.** Build the candidate list from the request's requirements and routing preferences.
2. **Admit the first pool.** Check the caller's access, pool controls, account credentials and billing standing before provisioning.
3. **Attempt creation.** Provision on that pool. Retryable provider failures can be retried within the configured provisioning window.
4. **Advance if the pool cannot serve.** Admit the next pool when the attempt reaches it, using the caller's current authority and that account's credentials. Check the whole request again for that pool.
5. **Keep the first successful placement.** Once the sandbox runs, that pool becomes its placement. If every candidate is exhausted, the create reports the failure.

### What advances the route

Capacity limits, rate limits, exhausted provider quota, unavailable regions and provider outages can cause the route to advance. A provider error, an unsupported pool configuration, an unbound provider account, or an instance that fails before it ever runs can also make that pool unusable.

A refusal of the caller's authority, an applicable policy, billing standing or the request itself ends the operation. Failover does not grant permission to bypass those checks.

### Retries and abandoned attempts

Repeating the same creation request with the same idempotency key returns the same sandbox. Creation can continue after an initial response while the coordinator owns the remaining attempts.

Each pool attempt creates its own provider instance. An instance that failed before running is deleted where possible; abandoned attempts are tracked against their original account so an instance that appears late can be cleaned up. The successful attempt never adopts another account's failed instance.

### Creation failover and saved-state recovery

Creation failover starts fresh attempts before a sandbox has run. It is not live migration of a running process.

Saved-state continuation creates a new sandbox from a snapshot taken before the original stopped or failed. Restoring a provider snapshot stays within its supported provider and account. Cross-provider continuation requires a supported filesystem export and image materialization; memory state does not transfer across providers. A failure cannot retroactively save state that was never checkpointed.

## Policy at every layer

| Layer | What it governs | Example |
| --- | --- | --- |
| Creation | Permission to create and use the selected resources and pools | A service may create only in approved pools |
| Lifecycle | Start, stop, update, snapshot and delete | An operator may restart a sandbox without deleting it |
| Provider and account | Rules attached to a provider's pools and account boundaries | Production capacity is reserved for production workloads |
| Individual actions | Command execution, files, ports and credential use | An agent can execute commands without receiving every sandbox permission |
| Egress proxy | Outbound destinations and credential use for matching requests | An API credential may be attached only for its authorized destination |

Policy scopes can include the platform, workspace, customer or principal, agent, resource, binding and delegated capability. Applicable rules compose: every required layer must allow the operation, and an explicit deny wins. Narrower permissions cannot restore authority denied by another applicable layer.

Routing selects candidates; authorization decides whether an attempt or action may proceed. Failover admits each later pool when it reaches it, rather than assuming that approval of the first pool authorizes every other account.

## Egress and credential policies

Network requirements restrict where the sandbox can connect. The pool's network boundary is the outer limit; sandbox-level rules can narrow it. Enforcement mechanisms and supported destinations depend on the provider.

For credential injection, the sandbox selects connections belonging to its workspace or user. A credential defines the destinations where it may be used. For a matching outbound request, the egress path checks the destination and authorizes credential use before adding the credential outside the sandbox. Unrelated accounts' credentials are not available to that request.

Through the egress proxy, credential use is evaluated for the matching request with destination context. Network permission alone does not grant permission to use a credential. The provider must support the required proxy or injection mechanism.

See [Connectors](/docs/connectors) for connected accounts and [Outbound access](/docs/sandboxes#outbound-access) for sandbox network settings.