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 prefixx-<provider_id>-. - Formats and ids. Times are RFC 3339 strings in UTC with a
Zsuffix, 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
createwith the sameIdempotency-Keyreturns the first sandbox. A repeat with a different body, or one sent while the first create is still in progress, getsconflict. - Lifetime and destroy. End the sandbox in its
at_endstate no later thanlifetime_seconds(default 300) aftercreatereturns, even if the consumer has gone away. Return fromdestroyonce you have accepted the request; a repeated destroy succeeds. - Commands.
runtakesargvand 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 -pwould, and write the file, or refuse withnot_foundand create nothing; a consumer relies on neither. A process has exited only whenstateisexitedwith anexit_code; closed output streams do not mean that it exited.
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:
itemis 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, orfeature(a recurring fee for an enabled feature).price_usdis the price of one unit in US dollars, as a decimal string.unitis the unit as you state it, such asvcpu_second,gib_hour,gb,each, ormonth. Amonthis 730 hours, and agbis 10^9 bytes (writegibif you bill binary gigabytes).basisis what is measured:allocated,used,max_allocated_used,fixed, orcount.
"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 thesandbox-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.
SpsError for an error:
serve command serves
any installed adapter, and it needs the http extra:
example after you rename the template.
2. Write The Manifest (Adapter Only)
The adapter’s Python package holdssps-provider.yaml. Tools read it without importing your code,
and the Provider class reads it when your subclass is defined
(schema).
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.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’sgates (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.