Snapshot & launch
Two commands run a script from this repository somewhere else.
Both submit control requests to the lakeshore control plane. Neither needs
dl login; they need --server (or $LAKESHORE_URL) and the control-plane
token in $LAKESHORE_CLIENT_TOKEN. launch --mount is the exception: it goes
through DreamLake with your login and a mount's stored credential
(below). This transport does
not grant the control plane cloud-launch authority. Workload execution must use
an explicitly user-configured launch server with its appropriate IAM role; verify
the selected queue's execution route before submitting. No control-plane/service
IAM, ambient service credentials, operator Vault IAM user or direct hosted-backend
provider execution may substitute for that server. If the route is unverified,
hold new workload launches; snapshot preparation and read-only inspection may
continue. See the required launch boundary.
This page documents command behavior, not acceptance of that architecture.
Run here, or submit
The usual setup is a Terminal open on a machine you already have. The shell
runs on that machine, and so does everything on this page. Get the project
there first. These examples put each repository in its own directory under
~/public/. That is only a convention: nothing creates it, and the name does
not make anything public.
.dreamrc lives at the project root, in the repository. Every local_path in
it is a path on this machine, the one the Terminal is open on, resolved
from the directory containing .dreamrc. It is not a path on the laptop
running your browser, and nothing is uploaded from the browser.
From that shell there are two different ways to run a script:
- Run it here. For example,
python hello_job.py --message hi. There is no snapshot and no queue, andcode:is not read. Its dependencies must be installed on this machine. - Submit it. For example,
dl launch hello_job.py --queue cpu.- It runs on whichever worker serves the queue, possibly another machine.
- The selected code is archived here, uploaded to the namespace's
code-stagingstorage, and unpacked on the worker. - The worker needs the script's dependencies and
dreamlake-lakeshorealready installed. A snapshot ships code only.
snapshot
Both commands run through the Python SDK's bridge
(python -m dreamlake.lakeshore.bridge), so the interpreter they use must
have a dreamlake-lakeshore that ships it. dreamlake-lakeshore 0.4.0 and
earlier do not, and the command stops at "cannot import dreamlake-lakeshore".
The bridge is merged on the SDK's main
(dreamlake-lakeshore#24)
but is not yet released to PyPI.
With no code: block in .dreamrc, the repository you are standing in is
archived with git archive HEAD: committed files only. A dirty tree is
refused rather than shipped half-done. Commit first, or declare the code you
want shipped in a code: block (below).
The server and namespace are printed before the write, never after. If you are about to hit the wrong control plane, the line that tells you has to come first.
Snapshots dedupe on (remote, commit). Re-running on an unchanged tree
uploads nothing and gives you back the same id — and says so, because an
operator who just edited a file and expected an upload needs to know the tree
was clean:
| Flag | Meaning |
|---|---|
--server <url> | control plane base URL (default $LAKESHORE_URL) |
--namespace <slug> | control-plane namespace (default $LAKESHORE_NAMESPACE, else default) |
--json | one { status, id, remote, commit, sizeBytes, … } object instead of prose |
Choosing the code: .dreamrc code:
A code: block decides what ships: one or more directories or files, from
inside or outside the repository, each placed at a chosen path. Relative
paths resolve from the .dreamrc file, so launching from a subdirectory
ships the same thing. Files are taken as they are on disk, with VCS
directories and your excludes removed.
The worker unpacks the snapshot into a fresh directory, runs the script from
workdir, and puts only the pypath mounts on PYTHONPATH. An unchanged
tree reuses its snapshot. The full key table, bounds and unsupported Jaynes
features are in the SDK's
code mounts reference.
This requires the same SDK bridge, which is not yet on PyPI.
launch
| Flag | Meaning |
|---|---|
--queue <name> | queue to submit to ($LAKESHORE_QUEUE, else queue: in .dreamrc). Never guessed |
--snapshot <ref> | launch an existing snapshot: a 24-hex id, a 40-hex commit, or <remote>@<commit> |
--arg <value> | one argument for the script; repeat for more |
--no-wait | submit and print the invocation id instead of waiting |
--server / --namespace / --json | as above |
Omit --snapshot and the tree is snapshotted implicitly, which uploads
nothing when the commit is already registered.
The target is printed before anything is submitted:
The control plane picks the node
A launch names a queue, never a machine. A queue name that no worker serves is not an error anywhere — the invocation just sits there, waiting for a worker that may never arrive. That is precisely why the queue is resolved from an explicit source and never defaulted. With none of the three available, the launch stops before it spawns anything:
launch exits 0 when the script exited 0 and 1 when it did not. The
script's own stdout and stderr are printed through verbatim. Under --json
they are the stdout / stderr fields and the real number is exitCode —
read that, not $?, if you need to tell "the script failed" apart from "the
launch failed".
Launch through a mount
--mount submits the same launch to a Lakeshore you mounted in DreamLake
(dl queues mounts), using your DreamLake login. The mount's stored
control-plane credential stays on the DreamLake server: this command never
reads, sends or prints a control-plane URL or token, and ignores
$LAKESHORE_URL, $LAKESHORE_NAMESPACE and $LAKESHORE_CLIENT_TOKEN.
| Flag | Meaning |
|---|---|
--mount <[namespace/]prefix> | the mount, in your default namespace unless one is given. Excludes --server and --namespace: the mount names both |
--invocation-id <id> | repeat a launch whose response was lost; returns that invocation instead of launching again |
--timeout-seconds <s> | how long this command waits for the result (default 3600). A client wait only: reaching it does not cancel or kill the run |
- Code. The snapshot is the
.dreamrccode:block, built locally. It must be at most 128 KiB; DreamLake checks it, stores it in the mount'scode-stagingstorage and registers it before submitting. The legacygit archivesnapshot and--snapshotare not accepted with--mount. - Authority. Launching needs
lakeshore:usein the mount's namespace and reading a result needslakeshore:read. Only mounts created with management access can launch; a queue-only mount is refused (queue_mount_execution_unsupported). - Placement. Unchanged: the queue's scheduler picks a worker serving it.
- Identity. The invocation id is printed before anything is submitted
(under
--json, asInvocation: <id>on stderr; stdout stays one JSON object). If the response is lost, repeat the command with--invocation-id, not without it. The repeat must be identical: the same queue, script and arguments, and an unchanged localcode:tree, because the snapshot is rebuilt from it. Then the existing invocation is returned. The same id with anything changed is refused (invocation_conflict) and nothing new runs.
The result is read back through DreamLake, so the JSON record also carries the
mount and the workerId that ran it.
Which provider ran it
launch names a queue; the workers serving that queue were started by a
provider. To see which, and whether anything is currently claiming it:
Zero live workers for a provider is a normal state, not a fault — see Provider lifecycle.