How it works

From one request to a running sandbox

ComputeSDK team · Published

The router sits in front of many sandbox providers. You call one API; it decides where each new sandbox runs.

  1. Step 1

    Request

    Your code sends one create request with one API key, through the SDK, CLI or REST.

  2. Step 2

    Walk

    The router builds an ordered provider list from your strategy and rules, and tries each provider in turn.

  3. Step 3

    Placement

    The first provider that creates the sandbox wins. The router records which provider holds it.

  4. Step 4

    Run

    Commands go through the same API to the sandbox on its provider.

  5. Step 5

    Destroy

    Destroy the sandbox through the same API and billing stops.

Choosing the order

Managed accounts are ordered by one of three strategies:

  • Recommended (the default): ComputeSDK's recommended order, ranked by ComputeSDK's benchmark results and price. ComputeSDK bills for sandboxes it runs on these providers through the router, and scores every provider with the same public benchmarks.
  • Cheapest: lowest hourly price for the requested size first. See cheapest-first routing.
  • Custom: your own saved order.

Rules

  • Allowed and excluded providers: keep the walk to providers you trust.
  • Sizes: choose the size per request; providers without that size are skipped.
  • Lock: stop per-request only and ignore from changing your rules.
  • Per request: pass only to keep certain providers, or ignore to skip some, for one create.

If a create fails, the router moves to the next provider. See failover.

Your own provider keys

Optional. Add your provider API keys and choose whether they are tried first (the default) or as a fallback after ComputeSDK's accounts. Sandboxes on your keys are billed by the provider.

In code

TypeScript
const api = "https://platform.computesdk.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.COMPUTE_API_KEY}`,
  "Content-Type": "application/json",
};

// The router picks the provider and fails over if a create fails.
const { sandbox } = await fetch(`${api}/sandboxes`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
}).then((res) => res.json());

try {
  const result = await fetch(`${api}/sandboxes/${sandbox.id}/commands`, {
    method: "POST",
    headers,
    body: JSON.stringify({ command: "echo hello" }),
  }).then((res) => res.json());
  console.log(result.stdout);
} finally {
  await fetch(`${api}/sandboxes/${sandbox.id}`, { method: "DELETE", headers });
}

Full reference in the Sandboxes docs.