Runtimes

A runtime is mutable state used while authoring a DAG or tracking execution. Finalizing it creates an immutable DAG. Use the CLI to inspect and administer open work; use named committed DAGs for completed research.

Freeze and resume authoring

runtime_ref="$(dml runtime create)"
printf '["scalar",42]\n' | dml runtime put-literal "$runtime_ref" - --name answer >/dev/null
frozen_ref="$(dml runtime freeze "$runtime_ref" --message "Review staged input")"

dml runtime list | jq -e --arg frozen "$frozen_ref" '.[] | select(.id == $frozen)'
dml runtime describe "$frozen_ref" | jq -e '.state == "frozen" and .frozen_message == "Review staged input"'
answer_ref="$(dml runtime get-node "$frozen_ref" answer)"
dml dag get-node "$answer_ref" | jq -e '.[1] == 42'

resumed_ref="$(dml runtime unfreeze "$frozen_ref")"
dml runtime freeze "$resumed_ref" --message "Leave the demonstration read-only" >/dev/null
{
  "author": "runner@runnervmwuk1x",
  "created": "2026-11-09T16:47:53.703507+00:00",
  "dag": "dag:fddaecd49ea1cbf67fd367bdb95372f57c42aaed9439a5b009d28c598331470e",
  "frozen_message": "Review staged input",
  "id": "frozenindex:01a1c135892c79aebc767ff78d27c8e4",
  "message": "",
  "parents": [
    "commit:ed5bba27c6095fe0d9bdaa3867e02a96528143f2b2b8e3f96999fc76776ff6ee"
  ],
  "state": "frozen",
  "tree": "tree:9a0344396c7fb09ca4422bf107301dd9c2cb62c200f5628ba2590cae2ee70dfc"
}
true
true

Freezing preserves partial nodes, tags, and execution identity, but does not create a result. Its message is a reason, not a durable name. Dag.freeze() and Dag.unfreeze() manage the normal Python wrapper; dml.resume(frozen, name=..., message=...) resumes it in another process. Runtime and execution identities are complete Ref values (index: or frozenindex:), never bare IDs.

Dump and load runtime graph data

Dump an active or frozen index to JSON on stdout, then load it from stdin or a file in another initialized project:

dump_ref="$(dml runtime create)"
printf '["scalar",42]\n' | dml runtime put-literal "$dump_ref" - --name answer >/dev/null
dml runtime dump "$dump_ref" > runtime.json
dml runtime load - < runtime.json
dml runtime load runtime.json
index:01a1c13595b379c88508ce280feae7c8
index:01a1c13595b379c88508ce280feae7c8

Loading preserves the dumped index ID. It overwrites an existing index with that ID or creates it if absent; loading a frozen index replaces its active counterpart and vice versa. The JSON contains schema, root, and objects, using the same object encoding as dagpacks and including the complete local dependency closure, including parent history. Immutable graph-object identities are checked during loading.

In Python, dag.dump() or dml.runtime.dump(index_ref) returns a JSON-compatible dictionary. Pass that dictionary to dml.runtime.load(data) to obtain the restored index ref. Dumping does not require freezing, including for function runtimes.

These operations only transfer local repository objects. They do not transfer execution records, locks, cache ownership, executor handles, Python stacks, or external artifact bytes. No remote access or matching remote.root is required to dump or load. Normal runtime mutations still use the project’s existing execution coordination; loading does not initialize or repair that state. The caller is responsible for concurrent writers and any execution handoff. Treat dumps as trusted project data, and ensure every referenced repository object is local before dumping (deepen shallow history if needed).

Inspect, cancel, and refresh deliberately

runtime describe, describe-graph, and read-execution-record report graph, lifecycle, lineage, cancellation, invalidation, adapter continuation, shared retry deadlines, and cleanup. Cleanup may remain pending or fail without making an otherwise reusable result unavailable.

For script and local Docker, the launching effective user and hostname must participate in polling, cleanup, and cancellation. Other users/hosts return retry without touching local resources; there is no automatic takeover. A published result remains reusable while owner-dependent cleanup is pending.

course_ref="$(dml show | jq -er '.dags["course-execution"]')"
first_ref="$(dml dag get-node-by-name "$course_ref" script-first)"
execution_dag_ref="$(dml dag describe-node "$first_ref" | jq -er '.dag')"
cache_key="$(dml dag describe "$execution_dag_ref" | jq -er '.cache_key')"
cache_description="$(dml cache describe "$cache_key")"
execution_ref="$(jq -er '.execution' <<< "$cache_description")"

jq -e --arg dag "$execution_dag_ref" '.dag == $dag and .lifecycle == "succeeded"' <<< "$cache_description"
printf '%s\n' "$execution_ref" > "$DOCS_WORKSPACE_ROOT/invalidated-course-execution"
dml cache invalidate "$execution_ref"
true
{"invalidations":[{"cache_key":"fe612bf7a9a547ba609acb7d75c197744abb456e6b0d46725e8d8c4aeec2ad8e","execution_id":"01a1c135550f77c8bc340008beb9fcab","requested_at":1794242879,"requested_by":"runner@runnervmwuk1x"}],"total_time":0.1096501350402832}

Rerunning the same stored runnable and argument produces a new execution for the same normalized cache key:

import daggerml as dml

course = dml.load("course-execution")
with dml.new("course-refresh", message="refresh invalidated course work") as dag:
    runnable = dag.put(course["script"], name="script")
    source = dag.put(course["source"], name="source")
    refreshed = runnable(source, name="refreshed")
    dag.commit(refreshed)

assert dml.load("course-refresh").result.value() == {"count": 3, "total": 10}
refreshed_ref="$(dml show | jq -er '.dags["course-refresh"]')"
refreshed_result="$(dml dag get-node-by-name "$refreshed_ref" refreshed)"
refreshed_dag="$(dml dag describe-node "$refreshed_result" | jq -er '.dag')"
refreshed_key="$(dml dag describe "$refreshed_dag" | jq -er '.cache_key')"
new_execution="$(dml cache describe "$refreshed_key" | jq -er '.execution')"
old_execution="$(cat "$DOCS_WORKSPACE_ROOT/invalidated-course-execution")"
test "$new_execution" != "$old_execution"

Invalidate exact execution refs, not cache keys or DAG refs. This affects every caller sharing remote.root, so inspect the returned identity and coordinate before refreshing work. Cancellation first selects the complete unreferenced set as cancel-pending, conditionally removes matching cache pointers, then cancels adapters concurrently. Retry responses share not_before; repeated dml runtime cancel index:... --max-retries 3 resumes pending cancellation. An execution that already finished is a successful no-op. Continue with Sharing; cache invalidation is deliberately last among workflows that need the original cached result.