---
title: "Durable code mode"
description: "Deterministic and durable runs: the same code and files give the same result, a paused run resumes later by its id, and a retry is safe."
canonical: "https://shotcup.dev/docs/durable-code-mode"
last_updated: "2026-11-01"
---
# 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

| Part | In the request | What keeps it the same |
|---|---|---|
| Code and files | `code`, or `files` and `entry` on `POST /api/v1/runs` | The run sees only the files you send, or a saved sandbox's workspace, or a drive version you mount |
| The engine's switches | `engine` (`compat`, `ast`, `vitest`, `canvas`) | A closed set of switches, recorded with the run |
| Time and randomness | `deterministic`, `true` by default | A fixed clock (`Date.now()` and `performance.now()` return 0), file times counted from 0 (its files at 0), UTC, and seeded `Math.random` |
| Tool answers | `tools` | The program reaches the outside world only through tools you declare and answer |
| What it fetched | `allowedHosts` | A 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](#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:

```sh
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](https://shotcup.dev/pricing)).
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](https://shotcup.dev/docs/streaming#watching-a-run).

## Resume it

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

```sh
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](https://shotcup.dev/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](https://workflow-sdk.dev),
[Temporal](https://temporal.io) and [Restate](https://restate.dev) 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:

```ts
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](https://shotcup.dev/docs/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.
