feat: implement the code mode runtime Actor

[MQ37]

For reviewers: apify-mcp-server PRs #1123 and #1124 exercise this Actor through Code Mode.

What

code-runtime runs one JavaScript program per Actor invocation inside a sandboxed workerd isolate. It exposes a typed apify binding for Store, Actor runs, datasets, and key-value stores, then writes { stdout, stderr, exitCode, statusMessage } to the default dataset.

User code can fetch only http(s)://apify.com and *.apify.com. Internal API calls use a separate env.INTERNAL_API service binding and never expose the platform token-bearing capability to user code.

Why

This provides Code Mode for the Apify MCP Server without adding a dedicated MCP tool. The runtime now closes the reviewed capability-theft, SSRF, redirect, prototype-poisoning, path-injection, token-exposure, and concurrent run-limit bypasses.

Execution safeguards support maximum spawned runs, aggregate committed charge, and default child-run timeout. Spawned run IDs are scoped to the current script; unfinished runs are best-effort aborted when the script throws.

Syntax errors in generated user code become diagnostic dataset output with exitCode: 1 and statusMessage: "Failed to compile: ...". Infrastructure failures still fail the Actor run.

Data: does Code Mode actually help?

Ran a paired A/B eval using apify-mcp-server's evals/workflows harness: the same task, agent, and judge model were used for both arms. One arm used regular MCP Actor/storage tools directly; the other routed work through this Actor. Each arm ran 5 repeats across 3 task shapes.

Task	Items	Runtime vs standard
Single small lookup (5 Instagram posts)	5	+78% slower, +46% more tokens — loses
Bulk filter/sort/aggregate over one dataset (100 Google Maps places, top 10)	100	-35% faster, -19% fewer tokens — wins
Fan-out over many sub-resources (20 places, about 20 pages each)	20 places × about 20 pages	-59% faster, -75% fewer tokens — wins decisively

Conclusion, encoded in the Actor description and README:

• Don't use it for a single lookup under about 10 items; the sandbox's round-trip overhead, about 20K tokens, is not paid back.
• Use it for filtering, sorting, or aggregating 50+ dataset records.
• Use it at modest counts, about 10+, when work fans out over multiple sub-resources with sizeable payloads, such as visiting pages or chaining Actor calls. Each skipped round trip avoids sending a raw document through the model.

Testing

• pnpm run typecheck
• pnpm build
• pnpm run test — 44 unit tests
• pnpm run test:integration — 10 real-workerd tests with a local API mock
• ./test.sh — live Actor binding and sandbox probes

The latest changes also remove redundant comments while preserving security and ordering invariants.

[jirispilka]

I wanted to add myself as an a reviewer, but I can't, so here we go.

First: nice work. The big calls are right, and the ones that are easy to get wrong you got right.
To be honest I spent a while wanting to push back on the hand-rolled apify binding and to use apify-client or CLI but after some back and forth and after understanding the constraint (neither runs in workerd without nodejs_compat, which reopens exactly the holes this PR closes) I dropped it. The binding is justified. So everything below is refinement, not a rethink.

The rest is written mostly by Claude with my edits.

Things I want to agree on

1. Write the Actor's own code in TypeScript.
The image is already built on the platform, and that build already runs Node (Dockerfile stage 1). Compiling worker/*.ts → *.js there is one command in a build that already exists — workerd embeds the compiled JS either way. This is ~300 lines of security-critical code with no CI and no type-checking right now. I don't see the case for plain JS here — what am I missing?

2. code input should be JS only — drop "TypeScript" everywhere.
The user script is fetched at container runtime and wrapped verbatim into usercode.js (entrypoint.sh:32-38); nothing transpiles it and workerd doesn't strip types, so a type annotation today is a SyntaxError at load. Clean split: Actor source = TS (build-time); user code = JS only — keeps the runtime image Node-free. Remove "TypeScript" from the README, actor.json, and the input-schema description.

3. Give the runner a real status message.
exitCode 0/1 is the only signal, and the most common failure an LLM will cause — bad syntax — doesn't even reach it. A parse error in usercode.js fails the worker load before the try/catch at runner.js:283, so the run dies as an opaque 10s health-check timeout with no diagnostic. Two small changes:

• Import the user module inside the try/catch (await import('./usercode.js') instead of the static import at runner.js:13) so a SyntaxError is catchable.
• Add a statusMessage field next to {stdout, stderr, exitCode}: "Script completed" / "Script threw: …" / "Failed to compile: …".

4. The binding docs have to live in the Actor.
Right now the real guide lives in the MCP repo (code_docs_content.ts). Anyone connecting this Actor from a non-Apify client gets only the README. For an Actor whose whole input is "write code against a binding you can't see," the reference needs to be self-contained here — README + docs/API.md + a proper input-schema description — and the MCP tool should mirror it, not own it.

Stop renaming the Apify vocabulary and this is not bike-shedding, it is important for LLMs

The binding renames a lot of apify-client methods and params. LLMs already know apify-client — and our own MCP server uses it (actor().start(input, {memory, timeout}), run().waitForFinish({waitSecs}), keyValueStore().listKeys()). Every rename is a fact the model has to unlearn from a docs page instead of recall for free, and it directly hurts point 4: the closer the surface is to apify-client, the less any docs are even needed.

Rule I'd propose: match the API / apify-client surface by default; rename only where the original name is actively wrong (store→search). The single-options-object shape (get({ storeId, key }) instead of positional) is a fine, separate choice — keep it. This is only about names.

Note: I like kvs rather than keyValueStore but still, at public surface, it is better to provide clear names.

Binding (now)	apify-client / API	Proposed	Note
actor.search({ query })	store().list({ search })	keep actor.search; param query→search	the one good rename
actor.getDetails()	actor().get()	actor.get
actor.run() (start+wait)	actor().call()	actor.call	avoids a 3rd verb; matches CLI apify call + MCP call-actor
actor.start()	actor().start()	keep
actor.runAndGetItems()	(none)	keep; verb → actor.callAndGetItems	genuine helper
run.get / run.abort	same	keep
run.wait()	run().waitForFinish()	run.waitForFinish	see wait-param note below
run.getLog()	log().get()	keep	limit-tail is a useful extra
kvs.*	keyValueStore	keyValueStore
kvs.get()	keyValueStore().getRecord()/getValue()	keyValueStore.getRecord	returns the value directly today — pick getRecord vs getValue and match the return shape
kvs.set()	keyValueStore().setRecord()	keyValueStore.setRecord
kvs.list()	keyValueStore().listKeys()	keyValueStore.listKeys
dataset.listItems / pushItems	same	keep
dataset.iterate / dataset.getSchema	(none)	keep; maybe getSchema → inferFields	avoids confusion with the Actor's declared schema

The run-option params

Here's the full picture across every layer, because it's the confusing bit:

Concept	MCP tool	binding (now)	REST query	apify-client
memory (MB)	memory	memoryMbytes	memory	memory
timeout (s)	timeout	timeoutSecs	timeout	timeout
wait (s)	waitSecs	waitForFinishSecs	waitForFinish	waitForFinish (.start()) / waitSecs (.call(), run().waitForFinish())
max items	maxItems	maxItems	maxItems	maxItems
max charge	maxTotalChargeUsd	maxTotalChargeUsd	maxTotalChargeUsd	maxTotalChargeUsd

• memory / timeout: drop the Mbytes/Secs suffixes — use memory / timeout. The units belong in the param description, not the name. (memoryMbytes/timeoutSecs isn't invented — it's the Run object / defaultRunOptions vocabulary — but the binding is setting run input, so match the input side: REST + client + our MCP all use memory/timeout.)
• wait: rename waitForFinishSecs → waitForFinish. Your binding maps it straight to the REST waitForFinish query param (runner.js:68-76,100-103), so this is a plain passthrough — match it and drop the invented Secs.
• One thing to not do: don't try to unify this with the MCP's waitSecs. They're genuinely different: REST/binding waitForFinish is a single server-side block capped at 60s; the MCP's waitSecs is a client-side poll ceiling that returns early. Apify has two names for two behaviors on purpose — the binding is the block (waitForFinish), the MCP tool is the poll (waitSecs). Leave both as they are.

Findings

Security — I'd fix these before it leaves experimental

• Redirects escape the allowlist. guard.js only checks the initial URL; fetch defaults to redirect: 'follow' (guard.js:47). An allowlisted *.apify.com 302 to any host gets followed out. Fix: redirect: 'manual' + re-check isAllowedHost on each Location.
• globalThis.fetch isn't locked. It's a plain assignment (guard.js:32) while WebSocket/EventSource use defineProperty({writable:false}). Lock fetch the same way — not exploitable today, just inconsistent and fragile.

Robustness

• Syntax errors crash the run instead of returning exitCode:1 (same fix as point 3).
• No retries / 429 / backoff. apiCall (runner.js:39-49) is a single fetch that throws on any non-2xx — a multi-call script dies on the first transient 500 or rate-limit. This is the real cost of not using apify-client.
• No spend ceiling, no orphan cleanup. No default timeout in actor.json; inner actor.start loops don't force maxTotalChargeUsd/maxItems; and a killed run leaves its sub-runs billing (no cascade-abort).
• run.abort({ runId }) takes any runId (runner.js:105) — account-wide, not scoped to runs this script started. Low severity, but it's an unreviewed capability.

Contract / maintainability

• No CI. The probes only run via test.sh → live apify push + token. Add tsc --noEmit + lint once it's TS.

Minor

• package.json:4 description is stale ("via the Worker Loader API" — runner.js says the opposite).
• actor.json output description says { stdout, stderr }, drops exitCode.
• apify/console aren't frozen — a script can reassign console.log and corrupt its own capture. Trivial Object.freeze.
• The egress claim oversells: even a perfect allowlist doesn't stop exfil (actor.start({input}) → any Actor with open internet; dataset/KV writes + webhooks). Say "no direct fetch-based exfil from this container," not "contained."

Confirmed good — leave these alone
Correct host label-matching (parsed via new URL().hostname, look-alikes tested); WebSocket/EventSource removed; single-use container, no isolate pooling; token held in a closure, unreachable from the script (process undefined); binding method surface matches the guide; not standby; docs/API.md exists.

[RobertCrupa]

I tested it and tried to break it, but it held up :D

However, there is an inacurate comment that should be fixed before merging:

Issue

The }-escape in entrypoint.sh works and ES post-order runs guard → usercode → runner body, so user top-level code executes before runner.ts:29 claims. A script can call claimRealFetch() first:

// run-code input
}
globalThis.__rf = (await import('./guard.js')).claimRealFetch();
;{
→ run FAILS with realFetch already claimed - guard.js imported out of order (runner is starved). And a claim-only probe returns rf_type=function rf_is_fn=true.

So the comments at guard.ts:18-25 and runner.ts:17-18 ("runner.js … always claims first") are inverted. User code claims first.

Fix direction (either):

• Claim realFetch inside guard.js at guard-eval time and expose it to runner.js through a channel user code cannot import (e.g. a module-private closure), dropping the standing claimRealFetch export entirely; or
• Run user code as a new Function('apify', 'console', userCode) body invoked from runner.ts after line 29, so there is no module-scope window and no importable claimRealFetch.

Either removes both the false comment and the self-DoS. Worth adding a sandbox-isolation.ts case that exercises the claimRealFetch path to keep this covered.

[MQ37]

@RobertCrupa Thank you! Should be fixed now and I also added this regressions test.

[jirispilka]

Thanks for the changes!

This PR is getting slightly out of hand.
If you please take a look at the security issue by Claude.
If valid, let's fix it and merge.

For the rest of the comments, please create an issue and we can fix it in the next PR.

[jirispilka]

I'm sorry for AI copy paste, but I think this explanation is better than mine.
I found it using Opus. I've tried to verify it usgin Favle and GPT 5.6 Sol. both refused :D. But Kimi 3 was ok with it :)

Security invariant bypass: exported gate setter lets user code steal the one-shot realFetch

Verified live against commit 8930b95.

Issue

markRequestHandlingStarted() is exported from worker/guard.ts, while usercode.js is statically imported by worker/runner.ts and evaluated in the same module realm. User code that escapes the generated export async function run(...) { ... } wrapper can therefore import guard.js, open the gate itself, and consume the unrestricted one-shot fetch:

}
const guard = await import('./guard.js');
guard.markRequestHandlingStarted();
globalThis.__stolenRealFetch = guard.claimRealFetch();
;{

claimRealFetch() returns the real, un-allowlisted fetch function rather than null. When /run subsequently executes, the runner's own claim receives null and throws:

realFetch already claimed.

The /run request returns HTTP 500, and the curl -f invocation in worker/entrypoint.sh fails the Actor run. This is a deterministic run failure with the current code.

The documented invariant in worker/guard.ts is therefore false:

A claim attempted before that (legitimate or injected) gets null without consuming the resource, so the real claim still succeeds afterward.

That statement holds only when user code calls claimRealFetch() without first invoking the exported setter. An injected caller that flips the gate first consumes the one-shot.

The shipped tests/fixtures/realfetch-escape.js regression exercises only the naive claim without the gate flip, so it passes while leaving this path uncovered.

Security impact

The confirmed impact is:

• User code can acquire a capability intended to remain available only to trusted runner code.
• User code can consume that capability before the runner and deterministically fail the Actor run.
• The guard's documented security invariant does not hold.

Unrestricted egress or SSRF is not confirmed on the pinned workerd version. workerd rejects asynchronous I/O during global-scope module evaluation:

Disallowed operation called within global scope. Asynchronous I/O
(ex: fetch() or connect()) ... are not allowed within global scope.

The stolen function cannot therefore make a request from module scope. It also cannot be used inside run(), because the runner fails while claiming realFetch before it invokes run().

This means there is no demonstrated exfiltration path today. However, during request handling, guard.js is the only hostname restriction on fetch; worker/config.capnp permits public, private, and local destinations. If global-scope I/O behavior changes through a workerd upgrade or compatibility/configuration drift, a usable stolen fetch would provide unrestricted egress and SSRF access to internal or metadata addresses.

The issue is best characterized as a security invariant bypass with deterministic self-DoS and latent unrestricted-egress risk. It should be fixed before the runtime leaves experimental status.

Fix

Make ordering the security boundary: trusted runner code must consume the capability before any user-controlled module is evaluated.

1. Simplify worker/guard.ts

Delete requestHandlingStarted and the exported markRequestHandlingStarted(). Keep claimRealFetch() as a plain one-shot:

const realFetch = globalThis.fetch.bind(globalThis);

let unclaimedRealFetch: typeof realFetch | null = realFetch;

export function claimRealFetch(): typeof realFetch | null {
    const fetchFn = unclaimedRealFetch;
    unclaimedRealFetch = null;
    return fetchFn;
}

2. Remove the static user-code import

Remove this import from worker/runner.ts:

import { run } from './usercode.js';

3. Claim first, then dynamically import user code

Call requireRealFetch() as the first statement after /run route validation, before any await, callback, or user-module evaluation. Dynamically import usercode.js only after the claim:

realFetch = requireRealFetch();

try {
    const { run } = await import('./usercode.js');
    await run(
        makeApifyBinding(token, apiV2, env.PARENT_ORIGIN),
        captureConsole,
    );
} catch (err) {
    // Existing user-error handling.
}

The resulting ordering is:

/run route validated
  -> runner consumes realFetch
  -> usercode.js evaluates
  -> any user claim receives null

This ordering is load-bearing and should be documented in both guard.ts and runner.ts. No await, user callback, or user-module evaluation may be introduced between route validation and the trusted claim.

Important workerd parsing behavior

Dynamic import does not defer parsing of modules embedded in config.capnp on workerd 1.20260402.1. A syntax error in usercode.js still kills workerd during service startup, before /run:

service main: Uncaught SyntaxError ... at usercode.js:2:6

The grep 'usercode.js' compile-failure branch in worker/entrypoint.sh must remain. It is the only available detection point for this failure and converts the startup error into the expected succeeded Actor run with a compile-failure dataset item.

Behavior change

After the fix, user module-scope code evaluates during the /run request rather than during worker startup. Module-scope guarded fetch() is consequently allowed where workerd previously rejected it as global-scope I/O.

This is security-neutral as long as the claim-before-import ordering holds: user code receives only the locked, allowlisted globalThis.fetch, while the unrestricted one-shot has already been consumed by the runner.

Verification

The fix was validated end-to-end on workerd 1.20260402.1:

• The original attack calls a setter that no longer exists. Its resulting TypeError is caught as a user error, /run returns 200, and no outbound request occurs.
• A strengthened escape fixture confirms that no gate setter is exported and claimRealFetch() returns null; the result has exitCode: 0.
• The sandbox-isolation probe passes all 17 checks through the dynamic-import path.
• /health does not consume the one-shot.
• A second /run receives HTTP 500 with realFetch already claimed., preserving the documented single-run assumption.
• Syntax-error user code kills workerd during startup and names usercode.js; the entrypoint detection matches it.
• Type-checking and compilation pass.

Tests to add

Strengthen tests/fixtures/realfetch-escape.js

The fixture should assert both required security properties. A thrown assertion rejects the dynamic import and produces exitCode: 1, making either regression visible:

}
const guard = await import('./guard.js');

if ('markRequestHandlingStarted' in guard) {
    throw new Error('Security regression: request gate setter is exported');
}

const stolen = guard.claimRealFetch();
if (stolen !== null) {
    throw new Error('Security regression: unrestricted fetch was claimable');
}
;{

Expected result: a succeeded Actor run whose output dataset item has exitCode: 0.

Add a syntax-error fixture

Add an intentionally invalid fixture such as:

const = ;

Expected result: the Actor run succeeds and its output dataset contains exitCode: 1 and Failed to compile.

Assert dataset output

Tests must assert the pushed dataset item rather than merely checking that the Actor process survived:

apify call -f "$input_json" -o

Do not combine -o with --json; Apify CLI 1.7.1 treats --output-dataset and --json as mutually exclusive.

Run the complete verification:

pnpm run typecheck
pnpm build
sh -n worker/entrypoint.sh
sh -n test.sh
./test.sh

Expected results:

• Binding smoke probe passes.
• Sandbox isolation passes all 17 checks.
• Strengthened realFetch escape fixture produces exitCode: 0.
• Syntax-error fixture produces the expected compile-failure dataset item.
• /health does not consume the one-shot.
• A second /run is rejected with realFetch already claimed.

[RobertCrupa]

Codex always refused to test this for me, but when I asked Claude Opus, it initially declined, and when I asked him again to do it, it worked fine :)

[jirispilka]

Consider addition of tests into CI:

Claude:

Testing gap: no behavioral tests in CI — the sandbox boundary itself is ungated

CI runs typecheck only (.github/workflows/typecheck.yml — one job, pnpm run typecheck). Every behavioral test in test.sh requires apify push + apify call + a token, so nothing about the
security boundary runs in CI. Locally, the guard logic has no token-free test at all: the allowlist paths of isAllowedHost/validateUrl are only exercised live on-platform
(tests/sandbox-isolation.ts), and guardedFetch's redirect re-validation — the entire reason that function exists — has no test of any kind, live or local.

[MQ37]

Fixed. Added token-free unit tests and real-workerd integration tests with a local API mock to CI.

[jirispilka]

Most smoke-test checks don’t validate returned values

tests/binding-smoke.ts:14-23 marks a check as passed whenever its callback does not throw. Most callbacks only return a diagnostic string, so incorrect or empty results can still produce ALL_TESTS_PASSED.

For example, keyValueStore.get never verifies the round-tripped values, and the paginated dataset.listItems check never confirms that both pushed items were yielded. An early-stop regression could therefore
pass silently.

Please assert the expected results, for example:

  const obj = await apify.keyValueStore.get({ storeId, key: 'obj' }) as { hello?: unknown } | null;
  if (obj?.hello !== 'world') {
      throw new Error(`kvs.get returned ${JSON.stringify(obj)}`);
  }

  let n = 0;
  for await (const _ of apify.dataset.listItems({ datasetId, limit: 1 })) n++;
  if (n !== 2) throw new Error(`expected 2 items, iterated ${n}`);

[MQ37]

Fixed. Smoke tests now verify KVS round-trips, dataset contents, pagination, run statuses, and returned values.

[jirispilka]

Consider aborting still-active tracked runs when handling a script exception

[MQ37]

Fixed. Tracked non-terminal child runs are best-effort aborted when the user script throws; cleanup errors do not hide the original failure.

[jirispilka]

callAndGetItems can return undocumented partial results

If the called Actor is still RUNNING when the 60-second API wait expires, callAndGetItems() immediately reads its dataset and returns whatever has been written so far. The returned items may therefore be empty or partial while the child run continues.

Please document this behavior in both README.md and docs/API.md.

[MQ37]

Fixed. README and docs/API.md now explain that callAndGetItems can return empty or partial results while the child run remains non-terminal.

[jirispilka]

The 60-second API limit is repeated. Consider defining DEFAULT_WAIT_FOR_FINISH_SECS = 60 and reuse it

[MQ37]

Fixed. Defined DEFAULT_WAIT_FOR_FINISH_SECS = 60 and reused it for call, callAndGetItems, and waitForFinish.

[jirispilka]

apify.actor.start, actor.call, and actor.callAndGetItems expose timeoutSecs, maxTotalChargeUsd, and maxItems, but all are optional and simply forwarded by createRun() when present.

The Code Runtime’s 900-second timeout applies only to the Code Runtime run. Likewise, waitForFinishSecs: 60 only limits how long the API request waits; it neither stops nor limits the cost of the Actor it started. A script can also start an unrestricted number of Actors, with no shared spending budget.

Can we add Code Runtime-level safeguards:

• Add a configurable maximum number of Actor runs per script.
• Apply a configurable default timeoutSecs when one is not supplied.
• Provide an execution-level spending limit and propagate an appropriate maxTotalChargeUsd to each started Actor.
• Reject new Actor starts once the configured run-count or spending budget is exhausted.
• Document that waitForFinishSecs is not an execution or cost limit.

[MQ37]

Fixed. Added configurable run-count, default-timeout, and execution-spending limits with synchronous reservations, rejection, rollback, and documentation.

[jirispilka]

I haven't tested it yet, will do tomorrow

[MQ37]

Thanks for detailed review. Personally, I don’t think it’s worth obsessing over making this security boundary perfect. There will probably always be another bypass unless we add an infrastructure-level egress proxy, which doesn’t seem worth it for this Actor.

That said, I summoned an army of agents to review the implementation from security, quality, standards, and blast-radius angles. We went through four iterative rounds and fixed the findings, then hardened the runtime further so we can ship this confidently.

Your points about cancelling tracked runs and handling syntax errors were especially useful. I originally wanted to ship a minimal version first, validate whether people actually use this approach, and iterate afterward. We can ship those improvements now instead, so I implemented them. Thanks.