# 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](https://github.com/dreamlake-ai/dreamlake-cli/releases/tag/v0.20.0) is published on native downloads and npm; [Python 0.16.0](https://github.com/fortyfive-labs/dreamlake/releases/tag/v0.16.0) is published on PyPI. Public artifacts and fresh installs were verified. [Nymph 0.1.6](https://github.com/dreamlake-ai/nymph/releases/tag/v0.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](https://github.com/dreamlake-ai/dreamlake-ai/pull/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](/dev/notes/vault-remote-delivery).

## Check server support

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

```shell
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.

**CLI**

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

**Python**

```python
# 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](https://github.com/dreamlake-ai/nymph/pull/32) and [termination fix45](https://github.com/dreamlake-ai/nymph/pull/45), 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](/dev/notes/vault-remote-delivery#operator-configuration-and-discovery) 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.

```json
{
  "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"}}
  ]
}
```

**CLI**

```shell
# 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
```

**Python**

```python
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.

**CLI**

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

**Python**

```python
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](https://github.com/dreamlake-ai/dreamlake-ai/blob/7f1d264/docs/evidence/vault-private-submission/acceptance.json) cover real HTTP/Mongo with a controlled CP, not deployed browser execution.