computesdk avatar

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@computesdk

Run it inside Claude Code after adding the marketplace with /plugin marketplace add computesdk/computesdk.

Contents

Discovered from source

Skills 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

  1. actions_list_repos — the org's connected repos (enabled or not, with their discovered workflow paths). Then actions_list_workflows (optionally scoped by repoFullName) for the runnable workflows — each carries dispatchable and its inputs.
  2. actions_list_runs — recent runs, newest first. Filters: repo, refs, statuses (passed|failed|running|cancelled|none), query. actions_get_run returns one run with jobs, steps, and the output tail.
  3. 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 from fromOffset: 0 and keep going from each nextOffset (offsets increase toward newer output — you cannot page backward from the tail). stepOrdinal narrows to one step (0-based). Output is already secret-redacted.
  4. 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 stored workflowId, or repoFullName + workflowPath for a file that exists only on the dispatch ref. ref is required; inputs are the workflow_dispatch values. manual: true runs a workflow that doesn't declare workflow_dispatch.
  • actions_rerun_run and actions_cancel_run take a runId.

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_link returns 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 or compute actions settings.
  • actions_poll_repo, actions_update_repo, actions_sync_repos describe the change until called with confirm: 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 same requestId returns the existing run instead of a second one.
  • A run's blockedReason explains refusals (e.g. no usable provider, fork-PR policy); a job's failureReason explains 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

  1. benchmarks_list — benchmarks the org can read, with run counts. Entries marked locked: true are catalog benchmarks the org isn't entitled to yet.
  2. benchmarks_list_runs — runs of one benchmark, newest first. Narrow with participants, since/until (with timeZone for date-only bounds).
  3. benchmarks_get_results (several runs) or benchmarks_get_run_results (one run) — success rates and latency p50/p95/p99 per participant. Latency covers successful tasks only: report success rate beside it.
  4. benchmarks_get_run_iterations — per-iteration rows, where outlier tasks show.
  5. benchmarks_get_reliability — uptime and missed slots for a reliability benchmark.
  6. benchmarks_get_participant_logs — one participant's worker logs for a run. Lines are capped to protect context: raise maxLines or narrow with workerId.

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 login session (needs @benchsdk/cli installed). 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 for size and the error codes (insufficient_credits, …) on err.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 the compute CLI uses — provider env vars) — never write a key, token, or secret into generated source.
  • Always destroy sandboxes — DELETE /sandboxes/{id} or sandbox.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 (status connected / unconfigured / error, masked keyHint, lastCheckedAt, statusDetail) and its rates. rate is what sandbox costs are reported at, customRate is the org's own (or null), platformRate is 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 effective providerOrder.

Change (org owners/admins only)

  • providers_verify_key places 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

  1. create_sandbox — returns a sandbox id. Args: size (small 1 vCPU/2 GB, medium 2/4 GB, large 4/8 GB, xlarge 8/16 GB, 2xlarge 16/32 GB, 3xlarge 32/128 GB; default medium; not every provider sells every size, sandboxes_get_options shows which), label, image, timeoutMs (lifetime in ms; default 30 minutes, max 6 hours), and providerOrder (camelCase routing preference). Pin one provider with provider (mutually exclusive with providerOrder), plus region and credentialSource: auto (default) uses the org's own key for that provider, else a ComputeSDK managed account billed from prepaid credit; byok requires the org's key; house always uses a ComputeSDK managed account. The result's placement says where it landed and the rate it bills at. What it can run on: sandboxes_get_options lists 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, ready says whether the key can place now). The first usable row is where a plain create_sandbox goes (strategy says how managed accounts are ordered: ComputeSDK's recommended order by default, cheapest first, or the org's own order). A size with rate: null isn't sold on that account. Call it when the user asks what they can run on or what it costs, before suggesting a provider. byok on create_sandbox/get_quote overrides the router for one call: only = the org's own keys only, off = managed accounts only (not with provider). 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_options shows the price of every size on every provider. For provider-specific pricing before creation, check sandboxes_get_options for the provider, size, and account type. If no rate is available, explain that and wait for the user to authorize creation before checking the actual placement and rateUsd on the result. insufficient_credits means 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.
  2. Do the work: write_file, read_file, make_directory, remove_path; run_command or start_process; sandbox_url for anything that listens on a port. File tools take absolute paths; read_file on a directory lists its entries.
  3. destroy_sandbox when 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. Returns jobId; follow up with wait_process, process_status (buffered output), kill_process, or list_processes to see all jobs on a sandbox. For interactive programs (REPLs, CLIs), spawn with stdin: true, then use write_process_stdin to send input; pass close: true to 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_url fails 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.0 and on the exact port passed to sandbox_url. Dev servers usually default to localhost, 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 to server.allowedHosts (Vite 5+ blocks unknown hosts)
    • Next.js: next dev -H 0.0.0.0 -p N
  • Argument names: sandbox tools take id; process tools take jobId.
  • 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 or compute sandboxes settings.

MCP servers 1

Sponsors

Details

Marketplace
computesdk/computesdk
Source
plugins/computesdk-router
Category
Development