Provider requirements
This guide is for teams that want their sandbox platform to integrate with Sandbox Router. It covers the baseline API contract, optional capabilities and the information we review before an integration goes live.
Apply to become a provider, or email contact@coresource.ai with questions.
What to submit
Start with your product name, website, engineering contact and public API or SDK documentation. Describe your deployment model, available locations, sizes, pricing and the capabilities you want to highlight.
Hosted services and self-hosted software use the same introduction form. For self-hosted offerings, explain who operates the compute, the supported environments and how customers install or connect the software. An introduction does not automatically create a public listing or enable routing.
For a more complete catalog profile, use the hosted-provider JSON template or self-hosted JSON template. Keep unknown values as null and include documentation links for claims. These product facts are separate from the API requirements below.
Share public documentation in the application. We arrange credentials and disposable test resources separately during review.
Integration principles
Native capabilities. Features must be available through the provider's own APIs. An extra guest agent, control image or in-sandbox workaround does not count as a native capability.
Truthful declarations. Declare only the features the API actually supports, including any restrictions by account, plan, image or isolation mode. A workload is eligible only when its requirements are met.
A clear division of responsibility. Sandbox Router selects eligible pools and their order. The sandbox coordinator manages lifecycle, retry and failover. The provider performs the requested operation and reports the result accurately.
A reachable API. HTTPS with JSON works directly with the adapter runtime in Cloudflare Workers. Tell us about other transports. Calls must work from that runtime and must not redirect credentials to a different host.
Accounts and authentication
Each key identifies one provider account. Multiple accounts can be represented by separate pools, with separate credentials and instance tracking.
Provide a cheap authenticated read for verifying a key. It must create nothing and change nothing. Distinguish an invalid key (401) from a valid key without permission (403), rate limiting (429), and temporary unavailability.
Document the minimum scopes needed for the integration: the lifecycle calls and every declared optional capability, including image or snapshot operations and webhook registration where used. Access should be confined to the provider account's resources.
Baseline API contract
These describe operations and behavior, not mandatory URL paths. The adapter maps your API onto this contract.
| Operation | Required behavior |
|---|---|
| Resolve a size | State the allocation rules for CPU, memory and disk: fixed shapes, granularity, ranges/ratios or image-defined sizing. Return the actual shape, or explain why no shape fits. |
| Resolve an image | State which image references you can boot and how an image is prepared for the requested shape. Support cleanup of images or snapshots created for the integration. |
| Create | Create under a stable name or idempotency key, with the requested image, allocation and supported configuration. Return the instance identity and truthful state. |
| Get | Return the instance's current state, allocation and metadata, or indicate that it no longer exists. |
| Delete | Delete by ID. Deleting an instance that is already gone succeeds. Remove dependent resources belonging to that instance. |
| Start and stop | Make repeated starts/stops safe, report when transitions finish, and declare what state survives a stop. |
| List and synchronize | List the account's instances with pagination and retained integration tags so external stops, failures and deletions can be reconciled. |
Safe creation and retries
A repeated create after a timeout or uncertain response must resolve to the instance already created under the same identity. Use a provider idempotency key, a unique instance name with lookup, or retained metadata that supports reliable lookup. Keep that identity valid throughout the configured provisioning window.
Creation must retain integration tags and supported customer labels. Requested network restrictions must be enforced before the workload runs. Ports are private by default; declare the authorization and exposure behavior of port endpoints.
Report the allocation actually provided. State all provider-enforced runtime caps, idle behavior, archival rules and retention limits; these must not be hidden behind an apparently unlimited lifecycle.
State transitions
Distinguish starting, running, stopping, stopped and failed states. A transition in progress must be distinguishable from its successful or failed end.
An operation can return once settled, offer a wait operation, or provide documented status reads that let the adapter wait for completion. Do not report a sandbox as running before it is ready.
For stop/start, document which behavior applies:
Memory, processes and disk survive, and start resumes them.
Disk survives and start boots it again; identify any directories that are excluded.
Nothing survives and start boots the image afresh.
State how long stopped instances are retained and whether the provider can remove them independently.
Errors and failover
Use machine-readable error codes and state whether retrying can succeed. Include Retry-After when you can specify a retry interval.
| Failure class | Meaning |
|---|---|
| Capacity | The provider has no available capacity for the request |
| Rate limited | The account is temporarily rate-limited |
| Quota | An account quota, plan limit or provider balance is exhausted |
| Region | The requested location is unavailable |
| Outage | A persistent provider or transport failure |
Distinguish these from permanent request errors and permission failures. A retryable transition conflict is different from a permanent conflict. Keep credentials, environment values and command contents out of error messages.
These distinctions drive retry and creation failover. A provider that cannot serve the create can be passed over for the next eligible pool; an authorization or policy refusal cannot be bypassed by selecting another provider. See Creation failover.
Instance synchronization
A provider reached through an external API must support listing and lookup so state changes made at the provider can be observed.
The preferred list API filters by exact metadata pairs and uses cursor-based pagination. Each result should include identity, state, allocation and retained labels. If a list is temporarily incomplete, an individual lookup must distinguish a missing list entry from a deleted instance.
The integration writes these identity tags. Preserve them exactly:
| Tag | Value to support |
|---|---|
constal-tenant, constal-namespace | Full identifiers, up to 128 characters |
constal-account | A 52-character lowercase base32 account hash, or deployment |
constal-sandbox-id | A DNS label of at most 63 characters |
constal-sandbox | A 40-character instance name, where the adapter uses it |
Customer and Router labels can add up to 16 entries beside those integration tags, with values up to 256 characters and Kubernetes-style keys. Publish any tighter limits on count, syntax or length; values must be refused rather than silently truncated. Cloning tags onto another instance can also clone the integration's ownership markers, so describe that behavior explicitly.
Signed lifecycle webhooks are optional and help changes arrive sooner. If offered, support registration and removal by API, signature verification, replay protection and notifications for creation, state changes and deletion. Periodic reconciliation still verifies current state.
Optional capabilities
You do not need to implement every capability. Report native support and its limits so matching workloads can use it.
| Capability | Details to document |
|---|---|
| Command execution | Arguments, exit status, complete output, stdin, environment, working directory, timeouts, streaming, terminals, cancellation and detached execution |
| File API | Read/write/delete support, permitted paths, transfer limits and missing-file behavior |
| Custom images | Accepted formats and registries, build steps, account ownership, size constraints and cleanup |
| Port access | Forwarding or endpoint URLs, authentication, supported protocols and public/private exposure |
| Egress rules | Allow-all, block-all and destination rules; domains, IP ranges, ports and live updates where supported |
| Credential injection | How a real credential is added outside the guest and restricted to its destination |
| Snapshots | Filesystem or memory contents, whether capture interrupts the sandbox, retention, restore constraints and deletion |
| Labels | Which metadata can be written at creation or updated later, and its limits |
| Metrics | Available CPU, memory and disk measurements, units, sampling and retention |
| GPU and isolation | Available shapes, accelerators, isolation modes, account/plan restrictions and locations |
Each capability must work as declared for the pool offering it. If a plan or isolation mode changes what is supported, identify that boundary explicitly.
Useful additional signals
If your API exposes these, include their documentation:
Available capacity and account quota by shape and region.
Capacity suggestions and maintenance notices for pools you operate for Sandbox Router.
Current pricing, including minimum/maximum prices and the conditions that change them.
Region discovery and creation in a selected region.
Richer signed events for capacity, price, quota, maintenance and instance changes.
Snapshot sizes, expiry, renewal and provider-supported filesystem export.
Distinct pause/resume and stop operations, live snapshots and native fork.
These are additional integration signals, not a claim that every provider must implement every one before applying.
Validation before launch
We review the documented API and test its behavior through an adapter. Verification includes retries and typed failures, then a disposable sandbox's lifecycle on the real API: verify, create, execute where supported, exercise declared features, stop, start and delete.
State synchronization, ownership tags and webhooks are checked where applicable. Test resources are cleaned up. Capabilities and limits are recorded from the behavior that was verified.
Accurate lifecycle reporting also makes performance measurements meaningful: creation latency ends when the sandbox is running, and creation success reflects whether a provider could serve the attempt.
Start the conversation
Submit a provider application. For technical questions or a platform that does not fit the usual hosted-service model, email contact@coresource.ai.