Skip to main content
The Sandbox Provider Spec (SPS) is an open standard interface for sandboxes. A provider that implements SPS 1.0 works with any consumer that speaks it: an SDK, an agent framework, an evaluation harness, or a router. This page is everything you need to implement it. The OpenAPI file defines every request and result, and the rules page holds the rules that span several operations.

Two Ways To Conform

Both ways carry the same operations, fields, and rules, and pass the same tests. An operation’s Python method and OpenAPI operationId are its dotted name with underscores (files.read is files_read). Any adapter can be served over the HTTP API unchanged, so you can start with an adapter and move to a native API later.

Required Operations

Every provider implements these eleven operations. Paths are relative to your base URL. Inside a sandbox, commands and the file operations see the same filesystem. A sandbox created without an image has bash and python3 on its path, outbound HTTPS works, and sandbox code cannot reach instance metadata or host credentials. These rules most often catch implementers:
  • Credentials. The bearer token is the only credential, and it decides the account. Never put it in a result, an error message, or a log line, and never send it to another host.
  • Unknown fields. Refuse a request field that the contract does not define, with invalid_request. Add result fields only with the prefix x-<provider_id>-.
  • Formats and ids. Times are RFC 3339 strings in UTC with a Z suffix, and money is a decimal string such as "0.000014". You choose each id and never reuse it for another sandbox or process.
  • Idempotent create. Within 24 hours, a repeated create with the same Idempotency-Key returns the first sandbox. A repeat with a different body, or one sent while the first create is still in progress, gets conflict.
  • Lifetime and destroy. End the sandbox in its at_end state no later than lifetime_seconds (default 300) after create returns, even if the consumer has gone away. Return from destroy once you have accepted the request; a repeated destroy succeeds.
  • Commands. run takes argv and runs it without a shell. A nonzero exit code or a timeout is a result, not an error. At the timeout, end the command and every process that it started.
  • Files and processes. Move the whole file or fail: a read whose connection ends early has failed and never yields a short file. When the parent directory of a write is missing, either create every missing directory on the path, as mkdir -p would, and write the file, or refuse with not_found and create nothing; a consumer relies on neither. A process has exited only when state is exited with an exit_code; closed output streams do not mean that it exited.
Discovery’s limits object states your limits, and each has a floor that you must meet: file_bytes 1 GiB, run_timeout_ms 60000, output_bytes 16 MiB, wait_ms 30000, process_output_bytes 1 MiB, process_retention_seconds 600, and list_limit 100.

Discovery And Prices

GET /v1/discovery needs the same token as every other request, because two accounts on different plans may see different classes, regions, sizes, and prices. A class is a wholesale different kind of sandbox, such as a container or a microVM; the main class has the id default.
resources, lifetime_timer, and gates use the SPS vocabulary and the declaration schema; gates lists the optional sections that you claim. ready: false means that the class takes no new sandboxes now, while existing sandboxes keep working. Prices. You can write your price list in minutes by copying your own price page. Each item has four required fields:
  • item is what is charged: cpu, memory, disk, gpu, machine (a whole fixed-size machine), create (each sandbox), egress, snapshot, volume, start (each start or resume), request, or feature (a recurring fee for an enabled feature).
  • price_usd is the price of one unit in US dollars, as a decimal string.
  • unit is the unit as you state it, such as vcpu_second, gib_hour, gb, each, or month. A month is 730 hours, and a gb is 10^9 bytes (write gib if you bill binary gigabytes).
  • basis is what is measured: allocated, used, max_allocated_used, fixed, or count.
Optional fields cover billed states, increments, minimums, allowances, and prices for one size, region, GPU model, or variant. An item that you do not list has an unknown price, never a zero price, so list a free item with "price_usd": "0" and "included": true.

Cost

GET /v1/sandboxes/{sandbox_id}/cost returns what a sandbox cost:
source is reported when your billing system states the amounts, or calculated when you multiply quantities from your own usage records by the prices in discovery. Quantities come from your records, never from a clock in the consumer or in an adapter, and every sandbox has a cost. The status is accruing while the sandbox exists. The cost becomes final within 7 days after the sandbox ends and stays readable for at least 7 days after that. If your usage records disappear with the sandbox, read the usage during destroy and return the final cost in its result.

Errors

Every error has one of twelve codes, and each code is fixed as the caller’s fault or yours. A consumer treats the fault as fixed by the code, whatever the message says.
outcome is failed when the operation had no effect and unknown when it may have taken effect. Set retry_after_seconds, and the same value in a Retry-After header, when retrying later can work. Keep message under 1024 characters, with no credentials and no other system’s response body. An adapter raises SpsError(code, message); any other exception, like any response without a valid error body, counts as provider_error with outcome unknown.

Get Started

1. Copy The Template Or Start Your Endpoint

The tester and a reference server ship in the sandbox-provider-spec package. The package and the template are in the GitHub repository; the commands below run the package straight from it, so there is nothing else to install. Add @ and a release tag after the URL (git+https://github.com/boxrouter/sandbox-provider-spec@<tag>) to pin a release. Adapter. The template is a complete adapter for Example Cloud, a small fake provider API that runs each sandbox as a local Docker container. Example Cloud is deliberately not shaped like SPS, so each method shows a real translation. Copy the template, rename the package and the provider id in pyproject.toml and src/<package>/sps-provider.yaml, and replace each Example Cloud call with yours. template/README.md shows how to run it on your machine.
Each method translates one operation to your API and raises SpsError for an error:
Native API. Serve the eleven operations under your base URL, as the OpenAPI file defines them. To see a working server, serve the template adapter over the HTTP API. The serve command serves any installed adapter, and it needs the http extra:
Use your own provider id in place of example after you rename the template.

2. Write The Manifest (Adapter Only)

The adapter’s Python package holds sps-provider.yaml. Tools read it without importing your code, and the Provider class reads it when your subclass is defined (schema).
Register the class under the entry-point group sandbox_provider_spec.providers in pyproject.toml (example = "sps_provider_example:ExampleProvider"), and declare several credential fields when your API needs several values, such as a key and a team id. The adapter calls only the hosts in api_domains (an exact name, or a suffix such as .example.com), with only the credentials that it was given. It reads no environment variables, no files outside its package, and no global state, and its dependencies are your own SDK and httpx. It never logs or returns a credential, and it keeps nothing that a later call needs, because a consumer may make a new instance for every call.

3. Run The Tester

Run the tester against your own test account. It reads each credential from the environment variable that you name, never from the command line.
The tester runs the baseline and contract tests, then the tests of every optional section that your discovery claims, and deletes every sandbox that it created. It prints one line per test, then one per required operation and per claimed section, such as operation create passed; a status is passed, differs, unsupported, not_run, or error. It writes a JSON report (sps-report.json) and exits 0 only when every test that it ran and the required cost operation passed. --quick skips the 1 GiB round trip and the wait for a final cost while you iterate; a quick pass exits 3, never 0. A consumer runs the same tester. To state that you conform, name the spec version, the class, and the passing report (GOVERNANCE.md).

Optional Sections

An optional section is a feature from the SPS vocabulary that you claim in discovery’s gates (or in resources, for a resource fact). A claim alone turns nothing on: a section is on only when the tester passes it. Refuse a request for a section that you do not offer with unsupported; in an adapter, each optional method raises unsupported until you implement it.

Directory operations

Four operations list, make, test and remove paths: files.list, files.mkdir, files.remove and files.exists. They are a fast path for what every program can already do with commands such as ls -A, mkdir -p, rm -rf and test -e, so they are not an SPS section and no request can ask for them: commands give the same result on every provider, and a consumer that finds the operations off runs the commands instead. You claim all four, or none, in the operations list of a class in discovery (classes[].operations), and they turn on when the tester passes its directories. tests. Each result must be the one that the equivalent commands, run as the class’s default user at the same moment, would give: files.list returns the immediate entries sorted by the bytes of their names and never follows a symbolic link, files.remove removes a link and never its target, and files.exists reports a dangling link as existing. Other sections are set at create, with no operation of their own: custom_images, network_lockdown, idle_shutdown, hidden_secrets, and resource asks such as arch, cpu_min, memory_min_mib, region, and gpu_model. Desktops and volumes wait for later 1.x releases.

Versioning

SPS follows semantic versioning. The URL path carries the major version (/v1), and the spec_version in discovery and in the manifest carries major.minor. A 1.x release only adds optional operations, optional request fields, result fields, and vocabulary. The twelve error codes stay fixed for all of 1.x, so nothing that a 1.0 provider does becomes wrong in a later 1.x. A consumer sends only the fields of the minor that you declare. A 2.0 would be a new path, /v2.