npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

sandcovery

v0.7.0

Published

One API for every sandbox provider. Better prices, better uptime.

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 sandcovery

Node.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_KEY as the key, and calls SANDCOVERY_BASE_URL when 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.
  • --help works 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> runs docker <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, so alias docker=sandcovery-docker lets 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 .dockerignore leaves out, bind mount sources, env files, the files cp, load -i, and import read, 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 with login --password-stdin or load, it hands stdin to Docker, and when stdout is not a terminal and Docker writes an archive there, as with save, the archive arrives byte for byte. Docker gets a terminal wherever yours is one, so docker run -it, docker exec -it, and docker attach work, and a command runs until it exits. The variables Docker reads come from your computer's environment, such as a name given to -e with 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 own kubectl <args> against a one-node Kubernetes cluster in a sandbox on Freestyle, or on boxd when Freestyle cannot create it, adds nothing to kubectl's stdout or stderr, and exits with its exit code, so alias kubectl=sandcovery-kubectl runs kubectl on 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 as port-forward or logs -f, keeps it running. kubectl must be on PATH and runs on your computer, so local files, port-forward, exec -it, and logs -f work as they do with a local cluster. completion, config, version --client, and --help start no cluster.
  • sandcovery-t3 creates a sandbox with port 3773, installs the same version of T3 Code there as your local t3, and links it to your T3 Code as an environment with t3 environment link, so an agent in T3 Code can delegate work to that sandbox. --access sets what agents on your computer may do there, each --env NAME=value reaches only T3 Code and the agents it runs, --provider names a provider to use, and --ttl sets 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.