Skip to content
Registry

code-runner

v0.1.4

Run untrusted Node.js and Python in-process — V8 isolates and CPython-on-WebAssembly behind one run/register_function/teardown API, with no microVM and no /dev/kvm. Code gets a global `iii` and a private scratch directory.

license: Apache-2.0javascriptpythonrunsandboxv8wasm

Install

bash
iii trigger compose::add worker=code-runner@0.1.4

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions6

code-runner::inject-guidance

Function

Internal pre_generate hook: appends code-runner usage guidance to the agent system prompt. Bound to harness::hook::pre-generate at worker startup; not called directly. Silenced by inject_guidance: false in the code-runner configuration.

Request
  • generateobject
    • system_promptstring

      The system prompt assembled so far (base + any prior hook's mutation).

Response
  • mutationsobjectrequired

    The harness applies `system_prompt` only when the key is present, so `None` serializes to an empty object: the safe no-op that preserves the harness's assembled prompt.

    • system_promptstring

      Full replacement system prompt (base + appended guidance). The harness overwrites, it does not merge.

code-runner::on-config-change

Function

Internal: reload code-runner settings from the authoritative configuration on change. Output caps and timeouts hot-apply; runtime/memory/scratch limits apply at the next worker restart.

Request
Empty object
Response
  • okbooleanrequired

code-runner::register_function

Function

Publish a bus function whose handler runs in a sandbox; no runtime_id needed. source must define handler(payload) in lang; each call runs it and returns its JSON result. The namespace (function_id before `::`) shares one runtime per lang; its functions stop resolving once torn down or idle-reaped.

Request
  • descriptionstring

    What `engine::functions::info` shows a caller — write one.

  • function_idstringrequired

    Bus id, e.g. `my-app::greet`; the segment before the first `::` is the namespace, which holds one persistent runtime per lang.

  • langall ofrequired

    Language of the namespace runtime this handler runs in.

    all of (1)
    Variant 1
    valuestringenum node, python
  • request_formatunknown

    Optional JSON Schema object (≤ 16 KiB, must constrain: `type`/`properties`/`$ref`) for the payload; shown by `engine::functions::info`, not enforced.

  • response_formatunknown

    Optional JSON Schema for the handler's return value; same rules as `request_format`.

  • sourcestringrequired

    Source that defines `handler(payload)` in `lang`: `export function handler(payload) {…}` (node) or `def handler(payload): …` (python).

Response
  • function_idstringrequired
  • registeredbooleanrequired

code-runner::run

Function

Run code in a sandbox (no network, host filesystem or packages). One-shot by default: nothing persists and no runtime_id is returned. keep: true keeps the runtime and returns its runtime_id to reuse until code-runner::teardown or the idle TTL reaps it. A failing script is a response, not an error.

Request
  • codestringrequired

    Node: an async function body (`return x` sets `result`; `await` works). Python: a module (assign `result = x`). A global `iii` is in scope.

  • keepboolean

    When `runtime_id` is omitted: `true` leaves the runtime running and returns its `runtime_id`; `false` destroys it after the run.

  • langany of

    Required when `runtime_id` is omitted; on an existing runtime omit it or pass the runtime's own language.

    any of (2)
    Variant 1
    valuestringenum node, python
    Variant 2
    valuenull
  • runtime_idstring

    Run in this existing runtime (from a keep: true run), sharing its globals and scratch; it is not destroyed afterwards. Omit to run one-shot.

  • timeout_msinteger· uint64min 0

    Wall-clock budget in milliseconds, clamped to the configured maximum.

Response
  • duration_msinteger· uint64requiredmin 0
  • exit_codeinteger· int64required
  • resultunknownrequired

    The completion value: what the code returned (node) or assigned to `result` (python). Null when it returned nothing, when it returned something JSON cannot represent, or when the run failed. Always present, never skipped — unlike `runtime_id`, a null result is information ("the code returned nothing") rather than an absence.

  • runtime_idstring

    Present when this run addresses a runtime that outlives the call — a `keep: true` run that SUCCEEDED, or a `runtime_id` echoed back. Absent, not null, otherwise: there is nothing to address. Treat a present value as a secret.

  • stderrstringrequired
  • stdoutstringrequired
  • successbooleanrequired

code-runner::teardown

Function

Destroy a runtime: unregister its bus functions, kill it and free its slot. Pass exactly one of runtime_id (from a keep: true run) or namespace (a register_function namespace, e.g. "app" for app::greet).

Request
  • namespacestring
  • runtime_idstring
Response
  • namespacestring

    Set when addressed by `namespace` — echoed in its canonical `app::` form, since more than one runtime (one per language) can back it and there is no single `runtime_id` to report.

  • runtime_idstring

    Set when this teardown was addressed by `runtime_id`.

  • torn_downbooleanrequired
  • unregisteredstring[]required

    Bus function ids this teardown unregistered, across every runtime it destroyed.

code-runner::ui-content

Function

Serve the code-runner worker's injected console UI assets (content function for its console:script / console:style triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

Triggers0

No triggers registered

Search the registry

Find workers, kits and executables, or jump to a page.