Skip to content

Durable code mode

Shotcup is a deterministic and durable JavaScript and TypeScript sandbox for agents: by default the same code and files give the same answer and the same files, byte for byte, and a run that pauses for a person or a tool resumes later by its id.

A run on Shotcup is its code, its files and the answers its tools gave. Give Shotcup the same code, files and answers on the same runtime and, with the default settings, it gives the same result. That makes a model's program safe to pause and resume: a run that waits for a person or a tool resumes later, a second resume of the same pause is refused (409), a retried request with the same Idempotency-Key reuses the run the first one started unless that run was lost, and a replayed call that differs from the one recorded is refused rather than guessed at.

Durable here means a run survives a pause, not a crash in the middle of a run. A run lost in flight, because its machine or function died, is not resumed. Retrying it with the same Idempotency-Key runs the script again from the start, which is why durable means at-least-once, never exactly-once.

This page describes what Shotcup does today.

What a run is made of

PartIn the requestWhat keeps it the same
Code and filescode, or files and entry on POST /api/v1/runsThe run sees only the files you send, or a saved sandbox's workspace, or a drive version you mount
The engine's switchesengine (compat, ast, vitest, canvas)A closed set of switches, recorded with the run
Time and randomnessdeterministic, true by defaultA fixed clock (Date.now() and performance.now() return 0), file times counted from 0 (its files at 0), UTC, and seeded Math.random
Tool answerstoolsThe program reaches the outside world only through tools you declare and answer
What it fetchedallowedHostsA run that can pause records the response each fetch got, and a resume replays it

There is no network access by default, so with deterministic: true the same code and files give the same output. A run that lists hosts can fetch from them, and a paused run's responses are part of its record (see What a run fetched). Every answer carries the output, a diff of the files the run changed and the files it wrote under /out, so two runs can be compared directly.

GET /api/v1/runs/:id returns what a run ran: its source (the files it was sent and a manifest of every file it used), its entry, tools, engine and deterministic setting, and with recordToolCalls: true the arguments and answers of its tool calls (source.toolCalls). Shotcup keeps it for your plan's run history (Free 1 day, Pro 7 days, Scale 30 days, Platform 90 days).

Pause a run for a person or a tool

A tool declared with approval: true pauses the run at its first call. On POST /api/v1/runs every tool you declare works this way, apart from Shotcup's own server-side tools, because nothing is there to answer it live:

Shell
curl https://shotcup.dev/api/v1/runs \
  -H "Authorization: Bearer $SHOTCUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "const ok = await tools.payments.refund({ order: \"A-1001\", amount: 42 });\nconsole.log(ok);",
       "tools": [{"name": "payments.refund", "approval": true, "description": "refunds an order"}]}'

The answer has status: "interrupted" and the calls the run is waiting for:

JSON
{
  "run": {
    "id": "…",
    "status": "interrupted",
    "interrupt": {
      "requests": [{ "callId": "c1", "name": "payments.refund", "args": [{ "amount": 42, "order": "A-1001" }] }],
      "token": "…"
    },
    "pausedUntil": 1792432800000
  }
}

Shotcup keeps the paused run's record (its code, its files and the answers so far) until pausedUntil, in milliseconds since 1970: as long after the pause as your plan allows (days to months, on the pricing page). The pause is not tied to the request or the process that started the run: any process with a key in the run's scope (your account's key, or for a platform tenant's run, that tenant's key) can resume it by the run's id. The token is only needed for a run paused before resume by id existed.

While a run is live, other clients in its scope can watch it and answer its tool calls (GET /api/v1/runs/:id/events, the SDK's runs.watch(id); the first answer to a call wins), so the person who answers need not be the process that started the run: see Watching a run.

Resume it

Send one answer per pending call, a value or an error:

Shell
curl https://shotcup.dev/api/v1/runs/$RUN_ID/resume \
  -H "Authorization: Bearer $SHOTCUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"results": [{"callId": "c1", "value": true}]}'

A resume is a new run with resumedFromRunId set to the paused one. It runs the same files from the start with the same switches, and each call that has an answer gets it from the record instead of calling anyone again. What the program did inside its sandbox before the pause is done again in the new sandbox; nothing leaves the sandbox except through tool calls, and those are answered from the record. A call the record does not cover, such as the next approval, pauses the run again with a new record that carries every answer so far. Calls the program makes at once pause together and are answered in one resume; calls made one after another pause one at a time.

Divergence is refused

An answer belongs to the exact call it was given for: the call's id, its tool and its arguments as JSON. If the resumed program makes call c1 with another tool or other arguments, Shotcup stops the run before the answer reaches it, and the resume answers 409 with the code continuation-mismatch, the callId and the tool's name. The approval is never delivered to a call nobody approved. The stopped run counts as a run, and the paused run stays resumed: start a new run to ask again.

A program diverges when it picks its arguments from the clock or from Math.random with deterministic: false. Keep the default and a resumed program makes the same calls.

A deterministic program that needs the current time reads it through a tool you answer, such as clock.now declared with replay: "safe". Its answers before the pause are recorded and replayed on resume, so the program reads the same times and asks the same questions; its calls after the resume are answered with the time then.

Answers are delivered in the order the paused run received them, so code that awaits several calls at once sees them in the same order. A resumed run that makes a recorded call with other arguments, skips one or leaves one unclaimed is refused the same way.

A call that was still waiting for its answer when the run paused is handled by its tool's replay class: replay: "safe" (a read, or a tool that dedupes on the call's key) is made again on resume; "never", the default, pauses the run again at once with that call pending and madeBeforePause: true, so you answer with what really happened. Every call carries an idempotencyKey that stays the same across every resume of the run.

A paused run is pinned to the runtime version it ran on. A resume after the runtime was upgraded is refused with 409 continuation-version-mismatch naming both versions; send "onVersionChange": "replay" to replay it on the new version anyway.

It is held to the limits it paused under too (memory, timeouts and the other caps of its plan at the time). If your plan no longer allows one of them, a resume answers 409 continuation-limits-changed naming it, because a replay under smaller caps could end differently. The paused run stays resumable until pausedUntil, so it resumes once the plan allows those limits again.

What a run fetched

A run that lists hosts in allowedHosts can fetch from them (GET and HEAD). When the run can pause, because it declares a tool with approval, Shotcup records the response each request got: its status, headers, body and final URL, or the network error. A resume gives every request the run made before the pause its recorded response without calling the host again, so the resumed program reads what the paused one read. Requests after the pause go to the network and are recorded in turn, for the next pause.

A recorded response belongs to the request it was given for: its place in the order the program made its requests, and the request's method, URL, headers and redirect option. If the resumed program makes another request in that place, Shotcup stops the run before the response reaches it, and the resume answers 409 continuation-mismatch with reason: "fetch-differs" and fetch, the request's number from 1. A resumed program that never makes a recorded request is refused the same way with reason: "unclaimed".

Shotcup waits for a run's requests to be answered before it pauses, so a paused run's requests are recorded; a request your program aborted has no response and is made again when the run resumes. On a resume, responses arrive in the order the requests were made. The recorded responses are kept with the paused run's record and count against its size, which is the size of the files a run may hold on your plan (pricing): a run whose responses would pass it ends with resource-limit. A recorded response is only replayed into the run it was recorded for, and only for a host the run lists.

Retries

  • A second resume of the same pause is refused. Once a resumed run has started, another resume of the same paused run answers 409 with the code continuation-consumed and resumedBy, the run that resumed it. Past pausedUntil a resume answers 410 continuation-expired. If Shotcup refused the resume before the run started (a quota, for example), the paused run stays resumable and you can send the resume again.
  • A retry with the same Idempotency-Key reuses the run it started, unless that run never ran or was lost. Send the header (1 to 255 printable ASCII characters, for example the id of the workflow step) on POST /api/v1/runs, POST /api/v1/runs/stream, POST /api/v1/sandboxes/:id/run or POST /api/v1/runs/:id/resume. A repeat with the same key and the same request gets the run the first one started, with Idempotent-Replayed: true, without running or charging it again (on the stream, one final run event). If that run never ran or was lost, the repeat starts a new attempt under the key instead. While that run still runs, the repeat answers 409 idempotency-in-progress with its runId and Retry-After. The same key with another request answers 422 idempotency-key-reused. A key is scoped to your account (or the tenant), lasts as long as its run is kept, and a run with "retention": "none" takes none. An upload is compared by its storage id, or by its content when the file names its SHA-256 ({ path, upload, sha256 }, checked against the bytes): uploads last 24 hours, so a retry that uploads its files again is the same request only when they name their sha256. The SDK sends a key only when you pass idempotencyKey, names its uploads' sha256 then, and waits while its run still runs, sending the request again when the run cannot be read.
  • Without a key, a retried run runs again. Sending the same POST /api/v1/runs twice makes two runs, and both count. With the defaults and the same files they give the same output, and nothing outside the sandbox changed unless one of your tools changed it.
  • At-least-once, never exactly-once. A run that never ran or was lost in flight is not resumed: it runs again under its key, so a retry after a crash runs the program again from the start. Put the tools that change things behind approval, or make their handlers safe to call twice.
  • Live answers do not make a run resumable. A run on POST /api/v1/runs/stream gets its answers while it runs. If the stream closes before the run ends, the run is cancelled and cannot be resumed. (With recordToolCalls: true its calls and answers are still kept in the run's history, in source.toolCalls.) For a run you want to pick up later, use tools with approval.

With a workflow engine

Workflow engines such as Vercel Workflow, Temporal and Restate run long processes: they keep the state of each step, retry failed steps, wait on timers and wait for events from people or other systems. Shotcup does none of that and does not try to. It gives such a workflow a step that runs a model's program, answers with the same result for the same record and can pause inside the program.

Two things stay with the workflow engine. A paused run never continues on its own: something has to resume it by its id before pausedUntil. And Shotcup has no retry or backoff policy: the caller or the workflow engine owns retries, and a retry is a new request.

The pattern has two steps around a wait. The first step starts the run. If the run pauses, the workflow keeps the run as that step's result, waits for the decision until the run's pausedUntil at the latest, then resumes by the run's id in a second step. With Vercel Workflow:

TypeScript
import { createHook, FatalError, sleep } from "workflow";

type Run = {
  id: string;
  status: string;
  stdout: string;
  pausedUntil: number | null;
  interrupt?: { requests: { callId: string }[] };
};

const api = async (path: string, body?: unknown, key?: string): Promise<Run> => {
  for (;;) {
    const response = await fetch(`https://shotcup.dev/api/v1${path}`, {
      method: body === undefined ? "GET" : "POST",
      headers: {
        Authorization: `Bearer ${process.env.SHOTCUP_API_KEY}`,
        "Content-Type": "application/json",
        // optional: tells Shotcup the run came from this guide
        "X-Shotcup-Integration": "durable-code-mode",
        ...(key === undefined ? {} : { "Idempotency-Key": key }),
      },
      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    });
    const data = await response.json();
    if (response.ok) return data.run;
    const error = data.error ?? {};
    // the key's first attempt is still running: wait for it to end, then send the same request again, which
    // answers that run, or starts a new attempt if it was lost
    if (error.code === "idempotency-in-progress") {
      await settled(error.runId);
      continue;
    }
    // a retried resume that already ran: wait for the run that resumed it
    if (error.code === "continuation-consumed") return settled(error.resumedBy);
    // the pause expired, a replayed call or fetch differed from its record, or the key was sent with another request:
    // retrying cannot help
    if (
      response.status === 410 ||
      error.code === "idempotency-key-reused" ||
      (error.code === "continuation-mismatch" && (error.callId || error.reason))
    ) {
      throw new FatalError(error.code);
    }
    // anything else may pass on the step's next attempt
    throw new Error(error.code ?? String(response.status));
  }
};

/** The run once it has finished or paused again. */
const settled = async (runId: string): Promise<Run> => {
  for (;;) {
    const run = await api(`/runs/${runId}`);
    if (run.status !== "queued" && run.status !== "running") return run;
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }
};

async function startRun(orderId: string, code: string) {
  "use step";
  return api("/runs", { code, tools: [{ name: "payments.refund", approval: true }] }, `refund:${orderId}`);
}

async function resumeRun(runId: string, results: unknown[]) {
  "use step";
  return api(`/runs/${runId}/resume`, { results }, `refund-resume:${runId}`);
}

export async function refundWorkflow(orderId: string, code: string) {
  "use workflow";
  let run = await startRun(orderId, code);
  while (run.status === "interrupted") {
    using approval = createHook<{ approved: boolean }>({ token: `refund:${run.id}` });
    const decision = await Promise.race([
      approval,
      sleep(new Date(run.pausedUntil ?? 0)).then(() => "expired" as const),
    ]);
    if (decision === "expired") return { status: "expired", stdout: "" };
    const results = (run.interrupt?.requests ?? []).map((call) =>
      decision.approved ? { callId: call.callId, value: true } : { callId: call.callId, error: "not approved" },
    );
    run = await resumeRun(run.id, results);
  }
  return { status: run.status, stdout: run.stdout };
}

The workflow code runs on your side, in Node; only the code it sends runs on Shotcup. Shotcup's default profile also accepts function and classic for loops, with strict semantics. Each step sends an Idempotency-Key made from what it is for (the order, the paused run), so when the engine retries startRun or resumeRun after the request reached Shotcup, it gets the run the first attempt started, or waits for it while it still runs and then asks again (a lost attempt starts again under the same key). A resume retried without its key is still safe: Shotcup answers 409 continuation-consumed naming the run that resumed it, and the step waits for that run. A continuation-mismatch with a callId or a reason is final; one with neither was refused before the resumed run started, the pause stays resumable, and the step's next attempt sends the resume again. Temporal and Restate fit the same way: the run and the resume are each an activity or a durable side effect, and the wait is a signal or an awakeable.

Steering, forking and compaction are agent-harness features, not part of durable code mode.

A paused run's history

GET /api/v1/runs/:id/history returns a paused run's chain, by the id of any run in it: its runs in order, when each paused, on which calls and until when, and how each was resumed: from which run, when, and by whom ({"scope": "account"}, or {"scope": "tenant", "tenant": "<external id>"} for a platform tenant, with "label" when the key that sent the resume had a label then; never a key). The answers a resume sent are included when the run records tool calls (recordToolCalls: true), as source.toolCalls keeps them, and are null otherwise; by is null for a resume made before Shotcup recorded who resumed. A tenant's key reads only its own tenant's runs.

One read covers up to 25 runs each way from the one you name. before and after name the next run of the chain the answer leaves out: read the history by that id to continue (truncated is true when the read stopped at its bound). The history lasts as long as the runs do, so the named run may be gone (its run history ran out, or it was deleted: 404). A resume through the run endpoint can take a moment to appear. The SDK's runs.history(id) and the MCP tool run_history read the same.

Saved sandboxes and drives

  • Saved sandboxes keep their files between runs. A run in a saved sandbox records the workspace files it used, readable with GET /api/v1/runs/:id/files?path= for as long as the run is kept, even after the sandbox is deleted.
  • Drives are versioned file trees, and a version never changes. Pin a mount's version and a retried step reads exactly the files the first attempt read. Every version has a treeSha256 over its paths and contents. See drives.

What is kept, and for how long

A run's record, its source and its artifact links last for your plan's run history: Free 1 day, Pro 7 days, Scale 30 days, Platform 90 days. A run with "retention": "none" is deleted right after its answer, so it cannot pause: every tool it declares must be answered live. DELETE /api/v1/runs/:id removes a finished run sooner.

This page as Markdown: /docs/durable-code-mode.md