Run a task with selected Vault credentials

Start with an existing SSH-accessible, personally owned enrolled process host. Private runs clone an allowed public HTTPS repository at a full commit, prepare its uv.lock environment, deliver only reviewed credentials to the task, and clean owned credential staging afterward. They do not enroll a host or install persistent SSH access.

Availability, 2026-09-15: CLI 0.20.0 is published on native downloads and npm; Python 0.16.0 is published on PyPI. Public artifacts and fresh installs were verified. Nymph 0.1.6 is published to GitHub and latest downloads, with a fresh default-installer check.

Hosted execution remains a separate gate. Staging backend task 163 is deployed with private execution disabled. UI #269 is deployed to staging and its authenticated disabled-capability review passed; an enabled browser-to-host run has not been accepted. Installing a client does not enable the server or upgrade an existing host. Verify main/control-plane configuration, the worker version and a fresh signed capability poll before submission. See the delivery status and evidence.

Check server support

Install the native CLI using the pinned command in its tab. SDK users first install the published package:

python3 -m pip install 'dreamlake==0.16.0'

Then inspect the authenticated server. A private-enabled response describes server support; the exact enrollment, fresh worker evidence and original signing key are checked again when submitting.

curl -fsSL https://dl.dreamlake.ai/install.sh | bash -s -- 0.20.0
dreamlake --version
dreamlake runs capabilities alice --json

# client is an authenticated DreamLake client; library methods do not prompt.
capabilities = client.runs.capabilities("alice")
if not capabilities["privateSetup"]["enabled"]:
    raise RuntimeError("This server has not enabled private execution")

The operator must configure the direct HTTPS API origin, exact repository-origin allowlist and private-run gate on the main API, plus the matching private tracked-run configuration on Nymph. The installed runtime must include Nymph32 and termination fix45, with a fresh signed capability poll. Unknown, disabled or denied discovery is a prerequisite failure, not permission to fall back to ordinary logged execution. The operator configuration documents the settings; this page does not activate them.

Pin metadata and submit

Read entry metadata with vault show / client.vault.show, then review the exact entry ID, revision and field selection. Save this example as setup.json, replacing the explicit placeholders with your reviewed values. A scalar entry uses valueShape: "string" and selection: {"kind":"whole"}; a named field uses valueShape: "map" and explicit selection.names. No credential values belong in this file.

{
  "repository": "https://github.com/OWNER/REPOSITORY.git",
  "commit": "FULL_40_CHARACTER_COMMIT",
  "destination": "research-check",
  "dependencies": "uv-lock",
  "mappings": [
    {"id":"api", "entryId":"REVIEWED_ENTRY_ID", "revision":3, "valueShape":"map", "selection":{"kind":"fields","names":["token"]}, "output":{"kind":"env","name":"SERVICE_TOKEN"}},
    {"id":"config", "entryId":"REVIEWED_CONFIG_ID", "revision":2, "valueShape":"string", "selection":{"kind":"whole"}, "output":{"kind":"file","path":"service.txt","format":"utf8"}}
  ]
}

# All DreamLake options precede workload argv. No secrets in argv or URLs.
dreamlake run --target alice/research/host \
  --enrollment-id REVIEWED_ENROLLMENT_ID \
  --setup setup.json --allow-vault-delivery \
  --request-id research-check-001 --timeout-seconds 3600 \
  --no-wait --json --uv-run python verify_service.py

import json
from pathlib import Path
setup = json.loads(Path("setup.json").read_text())
run = client.runs.submit(
    "alice/research/host", enrollment_id="REVIEWED_ENROLLMENT_ID",
    kind="uv-run", argv=["python", "verify_service.py"],
    setup=setup, allow_vault_delivery=True,
    request_id="research-check-001", timeout_seconds=3600,
)

destination is a checkout label under the configured private root, not an absolute host directory. The task reads SERVICE_TOKEN from its environment and service.txt under DREAMLAKE_SECRETS_DIR; Git/dependency preparation does not receive those credentials. Workload stdout/stderr is discarded at source. Frozen dependencies are not a sandbox: review repository and dependency code before granting access. Private repositories, Slurm/Kubernetes execution and persistent credential installation are outside this process-host slice.

Recover, inspect and cancel

If submission times out, repeat the same command or SDK call with unchanged setup, argv, target, enrollment, timeout, consent and request ID. Do not generate a new ID to resolve an uncertain result. A changed payload with the same ID conflicts. There is no public per-mapping retry command; status exposes each mapping's pending/materialized/cleaned receipt.

dreamlake runs status alice/RUN_ID --json
dreamlake runs cancel alice/RUN_ID --json
dreamlake runs status alice/RUN_ID --json

status = client.runs.status("alice", run["id"])
client.runs.cancel("alice", run["id"])
status = client.runs.status("alice", run["id"])

Cancellation records intent until termination is acknowledged. Disconnection, a submitted cancellation or a cleaned mapping does not prove all task-created copies or detached descendants are gone. Credential retirement is separate from run cleanup and never happens implicitly.

Browser recovery export

In the merged UI candidate, choose entries explicitly, review revisions and mappings, specify the same run metadata and consent. Submission locks the reviewed request. Export and recover this exact request downloads the complete metadata-only POST, including setup, arguments and request ID; the ID alone is insufficient. Its CLI/Python toggle supplies file-based recovery recipes for a later session against the same server and owner. Closing an unresolved submission asks before discarding local recovery; no request or credential is automatically persisted in browser storage. Mapping status names the entry/field and output alongside its stable mapping ID. UI evidence and screenshots cover real HTTP/Mongo with a controlled CP, not deployed browser execution.