sandcovery
v0.7.0
Published
One API for every sandbox provider. Better prices, better uptime.
Maintainers
Readme
Sandcovery
TypeScript client for the Sandcovery API: one API and one key for ephemeral sandboxes across every routed provider, running on your own provider accounts.
Install
npm install sandcoveryNode.js 24.14 or later. The package has no runtime dependencies.
Quick start
Create an API key and add your provider credentials in the dashboard at https://www.sandcovery.com/app, then set SANDCOVERY_API_KEY.
import { Sandcovery } from 'sandcovery'
const sandcovery = new Sandcovery()
const sandbox = await sandcovery.sandboxes.create({
disk_mib: null,
egress: null,
env: null,
gpu: null,
idle_timeout_seconds: null,
image: null,
os: null,
ports: null,
provider: null,
region: null,
slug: 'sandcovery/2x4:cheapest',
slugs: null,
snapshot_id: null,
ttl_seconds: 600,
})
const { exit_code, stdout } = await sandcovery.sandboxes.exec(sandbox.id, {
command: 'node --version',
cwd: null,
env: null,
timeout_seconds: null,
})
for await (const event of sandcovery.sandboxes.execStream(sandbox.id, {
command: 'npm test',
cwd: null,
env: null,
timeout_seconds: null,
})) {
if (event.type === 'stdout') {
process.stdout.write(event.data)
}
}
await sandcovery.sandboxes.destroy(sandbox.id)Sandcovery destroys every sandbox at its ttl_seconds, even when your process exits first.
Command line
The package also installs the sandcovery command. Each operation in the OpenAPI document is one command, sandcovery <group> <operation>, named as the document names it, and each of its parameters and body fields is a flag of the same name.
npm install --global sandcovery
export SANDCOVERY_API_KEY=sand_...
id=$(sandcovery sandboxes createSandbox --slug sandcovery/2x4:cheapest --ttl_seconds 600 | jq -r .id)
sandcovery sandboxes execSandbox --sandbox_id "$id" --command 'npm test'
sandcovery sandboxes destroySandbox --sandbox_id "$id"- A command prints the API's answer body on stdout. An error answer goes to stderr as the API sent it, and the command exits 1.
- It sends
SANDCOVERY_API_KEYas the key, and callsSANDCOVERY_BASE_URLwhen it is set, or https://www.sandcovery.com. - A flag for a field that is not text, such as a number, a list, or an object, takes JSON. An operation whose body is a file, such as
sandboxes uploadFile, reads that body from stdin. --helpworks on every command.
Docker, kubectl, and T3 Code
The package installs three more commands that run your tools on sandboxes through this client. Each reads the key from SANDCOVERY_API_KEY and the API origin from SANDCOVERY_BASE_URL, keeps its state in ~/.config/sandcovery, and passes an API error through unchanged.
sandcovery-docker <args>runsdocker <args>in a sandbox on a provider that runs Docker, streams its output, adds nothing to Docker's stdout or stderr, and exits with its exit code, soalias docker=sandcovery-dockerlets a computer with no Docker build and run containers. Later commands reuse that sandbox until its TTL ends. Before Docker runs, it copies the local files the command reads into the sandbox at the same absolute paths, up to 100 MiB packed, and runs Docker in the same working directory there: build contexts without what.dockerignoreleaves out, bind mount sources, env files, the filescp,load -i, andimportread, and a Compose project's files, build contexts, and bind mounts. It copies only paths under your home folder or the working directory. When stdin is not a terminal and Docker reads it, as withlogin --password-stdinorload, it hands stdin to Docker, and when stdout is not a terminal and Docker writes an archive there, as withsave, the archive arrives byte for byte. Docker gets a terminal wherever yours is one, sodocker run -it,docker exec -it, anddocker attachwork, and a command runs until it exits. The variables Docker reads come from your computer's environment, such as a name given to-ewith no value,DOCKER_DEFAULT_PLATFORM, and the shell variables a Compose file names, and the command sends the sandbox only those. A TCP port a container publishes answers on the same address and port of your computer.sandcovery-kubectl <args>runs your ownkubectl <args>against a one-node Kubernetes cluster in a sandbox on Freestyle, or on boxd when Freestyle cannot create it, adds nothing tokubectl's stdout or stderr, and exits with its exit code, soalias kubectl=sandcovery-kubectlrunskubectlon the sandbox's cluster. The first command that reaches the cluster starts it, which takes a few minutes, and later commands reuse it. It stops 15 minutes after the last command that reached it ends, or at its TTL, whichever comes first, and a command that keeps running, such asport-forwardorlogs -f, keeps it running.kubectlmust be onPATHand runs on your computer, so local files,port-forward,exec -it, andlogs -fwork as they do with a local cluster.completion,config,version --client, and--helpstart no cluster.sandcovery-t3creates a sandbox with port 3773, installs the same version of T3 Code there as your localt3, and links it to your T3 Code as an environment witht3 environment link, so an agent in T3 Code can delegate work to that sandbox.--accesssets what agents on your computer may do there, each--env NAME=valuereaches only T3 Code and the agents it runs,--providernames a provider to use, and--ttlsets the sandbox's TTL in seconds. It prints the sandbox's ID, and destroys the sandbox when any step fails.
Routing
A slug names a provider and a size, written <provider>/<vcpu>x<memory_gib>, in the shape of OpenRouter model slugs. boat/2x4 pins boat at 2 vCPU and 4 GiB, and sandcovery/2x4 routes across every candidate provider. Either number may be n for any value, so sandcovery/nx16 runs each provider's cheapest size with 16 GiB. A slug routes as :cheapest, sorting candidates by list price. Add :fastest or :most-reliable to sort them by measured create latency or uptime over the last 15 minutes instead. With no slug, a create runs sandcovery/2x4.
slugs takes up to 8 slugs to try in order, as OpenRouter takes models, and slug goes first when both are set. Within a sandcovery/ slug, a failed create falls back across that slug's candidates first, then moves to the next slug. provider takes order, only, ignore, sort, and allow_fallbacks and applies them to every slug. Every create attempt is listed in sandbox.attempts, and sandbox.slug is the provider and size it runs on.
Provider, region, and slug names are open strings, so a name the API adds later works with this version. The names known at release are exported from sandcovery/types as PROVIDERS, REGIONS, STANDARD_SIZES, SLUGS, and EGRESS_MODES.
Keys and provider credentials
keys, credentials, usage, and billing need a management key, which an organization owner mints in the dashboard. An API key receives 403 there.
const admin = new Sandcovery({ apiKey: process.env.SANDCOVERY_MANAGEMENT_KEY })
await admin.credentials.set('e2b', { api_key: process.env.E2B_API_KEY })On Pro or the Enterprise plan, an organization holds as many credentials per provider as it needs: credentials.add(provider, fields) adds another, a create tries a provider's credentials in the order they were added, and credentials.deleteOne(provider, id) deletes one. A Free organization routes one of its own keys per provider, so adding a second key of the same provider receives 403. When an organization leaves Pro or the Enterprise plan, it keeps every key, routes the oldest key of each provider, and paused is true on the others until it is on Pro or the Enterprise plan again.
The fields each provider takes are its credential_fields on sandcovery.providers.get(provider). sandcovery.providers.catalog() lists every provider on the provider board, where routed is false for a provider that is coming soon. credentials.offer() reads the free vCPU-hours your keys have earned, credentials.countXPost({ url }) counts your post on X that tags @Sandcovery as one key, billing.get() reads the plan, the credit balance, and auto top-up, billing.buyCredits({ amount_micro_usd }) answers the Stripe Checkout page that takes a credit payment, billing.setAutoTopUp({ amount_micro_usd, threshold_micro_usd }) sets the amount Sandcovery charges the saved card each time the credit balance falls below the threshold and answers the Stripe Checkout page that saves a card when none is saved, and billing.stopAutoTopUp() turns auto top-up off.
X account
xAccount.get() reads the X account linked to you and whether Sandcovery links X accounts now, xAccount.link() answers the dashboard page where you link one, since X confirms the link in the browser, and xAccount.unlink() unlinks it and deletes its ID, handle, and X token. An X account belongs to a person, so these need a management key, which acts for the owner who minted it. An API key receives 403 there.
Interfaces
This client, the sandcovery command, and the Python client each reach every operation of the REST API, and a test of each fails when one of them leaves an operation out.
Errors
A failed call throws an Error with the API's message and, as its cause, the API error it received, with its error code, such as unsupported, no_provider_available (with every attempt in attempts), provider_error (with the provider in provider), or spend_limit_reached. Types of every request and answer are exported from sandcovery/types.
Reference
The API reference and the OpenAPI document are at https://www.sandcovery.com/docs/api.
