
computesdk-router
Run code in cloud sandboxes across providers, drive your Actions CI, manage provider keys and read benchmark results.
- version
- 0.2.0
- GitHub stars
- 298
Install
/plugin install computesdk-router@computesdkRun it inside Claude Code after adding the marketplace with /plugin marketplace add computesdk/computesdk.
Contents
Discovered from sourceSkills 5
ComputeSDK Actions (CI)
Actions runs GitHub-Actions-style workflows on ComputeSDK sandboxes. The org's repos are connected through the ComputeSDK GitHub App — only repos already synced there are visible; there is no GitHub auth in chat.
If the org has never connected anything, list/get tools return a setup
block (reason: "no_git_connection") with a message and an
actionsSettingsUrl. Surface it to the user as-is — an org owner or admin
must install the GitHub App and enable repos there before any actions tool
returns data.
Core workflow
actions_list_repos— the org's connected repos (enabled or not, with their discovered workflow paths). Thenactions_list_workflows(optionally scoped byrepoFullName) for the runnable workflows — each carriesdispatchableand itsinputs.actions_list_runs— recent runs, newest first. Filters:repo,refs,statuses(passed|failed|running|cancelled|none),query.actions_get_runreturns one run with jobs, steps, and the output tail.actions_get_job_logs— a job's log. Defaults to the last 64 KB; logs can be huge — read the tail first. For earlier lines, read forward fromfromOffset: 0and keep going from eachnextOffset(offsets increase toward newer output — you cannot page backward from the tail).stepOrdinalnarrows to one step (0-based). Output is already secret-redacted.actions_list_job_artifacts— a job's artifacts with sizes and expiry.
Dispatching and managing runs (org owners/admins only)
actions_dispatch_workflow— pass a storedworkflowId, orrepoFullName+workflowPathfor a file that exists only on the dispatch ref.refis required;inputsare the workflow_dispatch values.manual: trueruns a workflow that doesn't declareworkflow_dispatch.actions_rerun_runandactions_cancel_runtake arunId.
Dispatching and re-running consume real compute. When the user asked for the run, that is the go-ahead; when you decide to start one yourself, confirm first.
A 403 is one of two things: insufficient_scope means the connection was
authorized before actions:write existed — the user must reconnect the
connector and re-consent; a permission message means the user isn't an org
owner/admin — tell them, don't retry.
Setup and settings
actions_list_installations— connected GitHub accounts and repo counts. To connect another,actions_get_install_linkreturns the Settings → Actions page; the install is the user's to do. Slack works the same way (actions_get_slack,actions_get_slack_install_link).actions_get_settings,actions_list_providers,actions_list_vault(names only, never values) — owners/admins only; changing settings is done in the dashboard orcompute actions settings.actions_poll_repo,actions_update_repo,actions_sync_reposdescribe the change until called withconfirm: true; confirm with the user first.actions_get_run_state— how a run was configured and placed, when asked why.
Workflow details
- Runs are org resources: the user sees every run in the org, including ones other members started. "Not found" on an id from another org is expected.
- A dispatched run may take a moment to start reporting jobs — poll
actions_get_run, don't re-dispatch. A duplicate dispatch with the samerequestIdreturns the existing run instead of a second one. - A run's
blockedReasonexplains refusals (e.g. no usable provider, fork-PR policy); a job'sfailureReasonexplains a refused placement. - Never print, echo, or write secrets — not in commands, inputs, files, or tool output.
ComputeSDK benchmarks (read-only)
Benchmarks measure sandbox providers on speed and reliability. In chat they are
read-only: creating, archiving, pausing and re-running benchmarks happens in the
dashboard or the compute bench CLI.
Workflow
benchmarks_list— benchmarks the org can read, with run counts. Entries markedlocked: trueare catalog benchmarks the org isn't entitled to yet.benchmarks_list_runs— runs of one benchmark, newest first. Narrow withparticipants,since/until(withtimeZonefor date-only bounds).benchmarks_get_results(several runs) orbenchmarks_get_run_results(one run) — success rates and latency p50/p95/p99 per participant. Latency covers successful tasks only: report success rate beside it.benchmarks_get_run_iterations— per-iteration rows, where outlier tasks show.benchmarks_get_reliability— uptime and missed slots for a reliability benchmark.benchmarks_get_participant_logs— one participant's worker logs for a run. Lines are capped to protect context: raisemaxLinesor narrow withworkerId.
Rules
- Compare providers on the same benchmark and the same date range only.
- Quote numbers from the tool output, with their units (ms, percent).
- Never print, echo, or write secrets, including any that appear in logs.
Driving ComputeSDK sandboxes from code
Two paths, depending on who provides the compute.
First-party: @computesdk/platform
npm install computesdk @computesdk/platform — the provider talks to the
hosted platform (the same API the compute CLI uses), authenticated with an
org API key or a compute login session:
import { compute } from 'computesdk';
import { platform } from '@computesdk/platform';
// Reads the org API key from COMPUTE_API_KEY (or a `compute login` session).
compute.setConfig({ provider: platform({}) });
// Creates are idempotent — the SDK mints an idempotency key per call
const sandbox = await compute.sandbox.create({ label: 'my-job', timeout: 30 * 60 * 1000 });
// Run a command (buffered; ~290s cap — longer work uses { background: true })
const { stdout, stderr, exitCode } = await sandbox.runCommand('python -c "print(1+1)"');
// Files (absolute paths, ~4 MB per call)
await sandbox.filesystem.writeFile('/tmp/out.txt', stdout);
const entries = await sandbox.filesystem.readdir('/tmp');
// Always clean up — wrap real programs in try/finally
await sandbox.destroy();
Auth precedence: apiKey > COMPUTE_API_KEY > BENCHMARKS_PLATFORM_API_KEY
a
compute loginsession (needs@benchsdk/cliinstalled). Hosted sandboxes place on the org's provider order — the org's own provider keys, or ComputeSDK's managed accounts billed from prepaid credit; see the package README forsizeand the error codes (insufficient_credits, …) onerr.code.
BYOK: the computesdk SDK + provider package
npm install computesdk + a provider package, e.g. @computesdk/e2b:
import { compute } from 'computesdk';
import { e2b } from '@computesdk/e2b';
// Reads the provider key from its environment variable (E2B_API_KEY here).
compute.setConfig({ provider: e2b({}) });
const sandbox = await compute.sandbox.create();
const result = await sandbox.runCommand('python -c "print(\'Hello\')"');
await sandbox.filesystem.writeFile('/tmp/out.txt', result.stdout);
await sandbox.destroy();
Other providers swap in the same way (@computesdk/modal,
@computesdk/blaxel, @computesdk/namespace, @computesdk/tensorlake,
@computesdk/archil, …) — but each takes its own config fields (Modal uses
tokenId/tokenSecret; blaxel wants apiKey + workspace; namespace a
token). Check the provider's package for its config shape.
Rules for generated code
- Read keys from the environment (
COMPUTE_API_KEY— the same env var thecomputeCLI uses — provider env vars) — never write a key, token, or secret into generated source. - Always destroy sandboxes —
DELETE /sandboxes/{id}orsandbox.destroy(), in try/finally for real programs. runCommand/commands return stdout, stderr, and an exit code — check the exit code before treating output as success.
ComputeSDK providers (BYOK)
An org can bring its own key for a provider; sandboxes and Actions jobs then place on it and bill the provider directly. Without a key, a provider's sandboxes run on ComputeSDK's managed accounts and bill from prepaid credit.
Read
providers_list— every provider the org may bring a key for:regions, the key's state (statusconnected / unconfigured / error, maskedkeyHint,lastCheckedAt,statusDetail) and its rates.rateis what sandbox costs are reported at,customRateis the org's own (or null),platformRateis the platform's. Quote prices to the user per hour.providers_get— the same for one provider.actions_list_providers— the providers Actions can place on and the effectiveproviderOrder.
Change (org owners/admins only)
providers_verify_keyplaces a real sandbox with the stored key to test it. It uses real compute: confirm first.providers_remove_key— new sandboxes and Actions jobs stop placing on that key. Live sandboxes keep the credential until they are destroyed. Confirm first.providers_set_custom_rate/providers_clear_custom_rate— the org's own reporting rate. It only changes how the org's costs are reported; it never changes what the platform charges.
Rules
- A key value never passes through chat. There is no tool to read or set one:
tell the user to add or rotate keys in the ComputeSDK dashboard
or with
compute byok. - Never print, echo, or write secrets.
- A 403 with a permission message means the user is not an org owner/admin: say so, don't retry.
ComputeSDK sandboxes
ComputeSDK places cloud sandboxes through the ComputeSDK gateway. All usage bills the ComputeSDK org selected when the connection was authorized — no provider setup is needed or possible in-chat.
Core workflow
create_sandbox— returns a sandboxid. Args:size(small1 vCPU/2 GB,medium2/4 GB,large4/8 GB,xlarge8/16 GB,2xlarge16/32 GB,3xlarge32/128 GB; defaultmedium; not every provider sells every size,sandboxes_get_optionsshows which),label,image,timeoutMs(lifetime in ms; default 30 minutes, max 6 hours), andproviderOrder(camelCase routing preference). Pin one provider withprovider(mutually exclusive withproviderOrder), plusregionandcredentialSource:auto(default) uses the org's own key for that provider, else a ComputeSDK managed account billed from prepaid credit;byokrequires the org's key;housealways uses a ComputeSDK managed account. The result'splacementsays where it landed and the rate it bills at. What it can run on:sandboxes_get_optionslists everything a create can land on, in the router's order: managed accounts (ComputeSDK-run, billed from prepaid credit, with a price per size) and the org's own provider keys (billed by the provider,readysays whether the key can place now). The first usable row is where a plaincreate_sandboxgoes (strategysays how managed accounts are ordered: ComputeSDK's recommended order by default, cheapest first, or the org's own order). A size withrate: nullisn't sold on that account. Call it when the user asks what they can run on or what it costs, before suggesting a provider.byokoncreate_sandbox/get_quoteoverrides the router for one call:only= the org's own keys only,off= managed accounts only (not withprovider). Pricing:get_quote(same size/region/timeout inputs; it creates nothing) walks the same router a create would and returns the provider it would place on, the rate in every unit (rateUsd.perHour— hourly is what users compare against) and the credit balance. Use it for long timeouts, large sizes, or whenever the user asks what one create will cost, and tell the user the hourly price;sandboxes_get_optionsshows the price of every size on every provider. For provider-specific pricing before creation, checksandboxes_get_optionsfor the provider, size, and account type. If no rate is available, explain that and wait for the user to authorize creation before checking the actualplacementandrateUsdon the result.insufficient_creditsmeans the org is out of prepaid credit: tell the user to add credit in the ComputeSDK dashboard. Don't share a top-up or checkout link.- Do the work:
write_file,read_file,make_directory,remove_path;run_commandorstart_process;sandbox_urlfor anything that listens on a port. File tools take absolute paths;read_fileon a directory lists its entries. destroy_sandboxwhen the task is finished — sandboxes bill for runtime, so always clean up unless the user wants it kept alive.
get_sandbox fetches one sandbox's details; list_sandboxes lists the visible ones. get_profile returns the connection's identity — an opaque id, and nickname, which is the name of the billed org.
Choosing the execution tool
run_command— one-shot commands under about 290 seconds. Returns buffered stdout/stderr/exit code.start_process— anything that outlives that: servers, watchers, builds, training. ReturnsjobId; follow up withwait_process,process_status(buffered output),kill_process, orlist_processesto see all jobs on a sandbox. For interactive programs (REPLs, CLIs), spawn withstdin: true, then usewrite_process_stdinto send input; passclose: trueto signal EOF.
Workflow details
- Scope: users see every sandbox they created through this plugin in that org — including ones from earlier sessions or other connected assistants. Sandboxes belonging to other org members, the warm pool, or CI are never visible; "sandbox not found" on someone else's id is expected.
sandbox_urlfails when the provider the sandbox was placed on has no ingress — say so, and offer to recreate pinned to a provider that supports preview URLs.- Previewed servers must listen on
0.0.0.0and on the exact port passed tosandbox_url. Dev servers usually default tolocalhost, and the preview proxy then returns 502 even though the server is running. Per-framework:- Flask:
app.run(host="0.0.0.0", port=N) - Vite:
vite --host 0.0.0.0 --port N --strictPort, and add the preview host toserver.allowedHosts(Vite 5+ blocks unknown hosts) - Next.js:
next dev -H 0.0.0.0 -p N
- Flask:
- Argument names: sandbox tools take
id; process tools takejobId. - Never print, echo, or write secrets — not in commands, files, env values, or tool output.
Spend and settings
sandboxes_get_costs— the org's running and settled spend, by provider. Open to any member.sandboxes_get_settings— placement settings (provider order, sizes, warm pool). Owners/admins only; read-only here, changes are made in the dashboard orcompute sandboxes settings.
MCP servers 1
Sponsors
Details
- Marketplace
- computesdk/computesdk
- Source
- plugins/computesdk-router
- Category
- Development