add-sandbox-provider - SKILL.md Agent Skill

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          # confirm it exists, get the version
cd /tmp && npm pack @computesdk/<name>        # then inspect the type defs:
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):

// {
//   name: '<name>',
//   requiredEnvVars: ['<NAME>_API_KEY'],
//   createCompute: () => <name>({ apiKey: process.env.<NAME>_API_KEY! }),
// },

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).