| name | add-sandbox-provider |
| description | Prep a new sandbox provider for the ComputeSDK benchmarks (wire up the dependency, env var, providers list, and CI workflow). Use when asked to add, onboard, or stage a new sandbox/compute provider — e.g. "add provider X", "onboard the foo sandbox", "set up bar for benchmarks". |
Add a sandbox provider to the benchmarks
This repo benchmarks ComputeSDK sandbox providers. A provider is wired across four
files. New providers are staged (every change commented out) until the provider's
API secret exists as a GitHub repo secret — then they're activated by uncommenting.
The beam provider is the reference example of a staged provider.
Inputs you need from the user (ask if missing): the provider name (lowercase, as it
appears on npm @computesdk/<name>) and the env var(s) it authenticates with
(e.g. FOO_API_KEY).
1. Verify the package and its factory shape
Never guess the factory name or config keys — confirm against the published package:
npm view @computesdk/<name> version
cd /tmp && npm pack @computesdk/<name>
tar -xzf computesdk-<name>-*.tgz -O package/dist/index.d.ts | grep -nE 'declare const|Config|export'
Note the exported factory (usually <name>) and its config interface — which key holds
the API key, and whether the key falls back to an env var. Most factories take
{ apiKey }; some take { token }, { token, workspace }, etc.
2. Add the dependency
In package.json add "@computesdk/<name>": "^<version>" to
dependencies, in alphabetical order. Then sync the lockfile:
npm install
Confirm the diff only added the new package — git diff --stat package-lock.json
(npm may report removing/changing packages while reconciling node_modules on disk;
that's fine as long as the committed lockfile only gained the new entry).
3. Document the env var(s)
In env.example append a section (staged providers live near the
bottom, by BEAM):
######### <NAME> ########
<NAME>_API_KEY=your_<name>_api_key
4. Stage the provider entry (commented)
In src/sandbox/providers.ts:
- Add a commented import near the other imports:
// import { <name> } from '@computesdk/<name>';
- Add a commented entry in the
providers[] array (direct-mode section, alphabetical):
Keep the entry minimal — only name, requiredEnvVars, createCompute. Do NOT
copy sandboxOptions, destroyTimeoutMs, etc. from a neighboring provider; those are
provider-specific (e.g. autoStopInterval is Daytona-only). Add an option only if the
factory's own config documents it.
5. Stage the CI workflow (commented)
In .github/workflows/sandbox-benchmarks.yml,
two spots, both commented like the beam lines:
- The
matrix.provider list: # - <name>
- The
Run benchmark step's env: block: # <NAME>_API_KEY: ${{ secrets.<NAME>_API_KEY }}
What you do NOT need to touch
GATEWAY_PROVIDERS in src/sandbox/generate-svg.ts — only for automatic-mode
providers routed through the ComputeSDK gateway (railway/render), not direct-mode SDKs.- A
bench:<name> script in package.json is optional; CI invokes
--provider ${{ matrix.provider }} directly. Skip it unless asked.
- No tests enumerate providers.
Why staged (and why it's safe to activate later)
The runner gracefully skips any provider whose requiredEnvVars are missing — it
returns a skipped: true result rather than failing (see
src/sandbox/benchmark.ts, the missingVars check).
So activating without the secret wouldn't break CI; staging is a convention to keep the
provider list reflecting what's actually being benchmarked until the secret is added.
Activation (later, once the repo secret exists)
Uncomment all four staged blocks: the import and providers[] entry in providers.ts,
the matrix line, and the workflow env: line. Add the <NAME>_API_KEY secret in the
repo settings first.
Final check
Run git diff and confirm the change set is exactly: package.json, package-lock.json,
env.example, src/sandbox/providers.ts, .github/workflows/sandbox-benchmarks.yml — and
that every provider-specific line is commented out (staged).
