Registering providers

dreamlake providers stores provider configuration in DreamLake and associates it with your host enrollment. Use CLI 0.14.0 or Python 0.11.0 with the deployed provider registration API.

Install the clients:

bash

npm install -g @dreamlake/dreamlake-cli@0.14.0
pip install dreamlake==0.11.0

For a native CLI installation, follow the CLI installation guide.

Register a provider

Save this declaration as provider.json. Replace the cluster, partitions and Vault entry with your values. Omit credentialRef if no reference is needed; never put credential contents in the declaration.

json

{
  "version": 1,
  "name": "research-slurm",
  "kind": "slurm-ssh",
  "config": {
    "cluster": "research",
    "partitions": ["cpu"],
    "credentialRef": {"namespace": "team", "entryName": "research-ssh"}
  }
}

Python tab: The same declaration can be registered with Python:

bash

dreamlake providers register team --file provider.json \
  --request-id research-register-001 --json
dreamlake providers list team --json
dreamlake providers show team/research-slurm --json

python

import json
from dreamlake import DreamLakeClient

client = DreamLakeClient()
with open("provider.json") as file:
    declaration = json.load(file)
registration = client.providers.register(
    "team", declaration=declaration, request_id="research-register-001"
)
provider_id = registration["resource"]["id"]

Keep the returned resource.id, resource.revision, operationId and your request ID. Every write requires an explicit request ID. Repeating the same request returns its original receipt. Reusing the ID with a different payload returns a conflict.

Associate your Slurm enrollment

Save an association as association.json, using your enrollment ID and the provider revision. Paths must be literal absolute paths. submissionRoot is the shared directory as seen by the submission host; computeRoot is that directory as seen by the compute node. Executable paths must be valid on compute nodes.

json

{
  "providerRevision": 1,
  "enrollmentId": "0123456789abcdef01234567",
  "runner": {
    "kind": "slurm",
    "partition": "cpu",
    "staging": {
      "submissionRoot": "/export/work/alice",
      "computeRoot": "/work/alice"
    },
    "environment": {
      "uvExecutable": "/opt/tools/uv",
      "pythonExecutable": "/usr/bin/python3"
    }
  }
}

Replace PROVIDER_ID below with the registration's resource.id.

bash

dreamlake providers associate team/PROVIDER_ID --file association.json \
  --request-id research-associate-001 --json
dreamlake providers status team/PROVIDER_ID --json

python

with open("association.json") as file:
    association_input = json.load(file)
association = client.providers.associate(
    "team", provider_id, association=association_input,
    request_id="research-associate-001",
)
status = client.providers.status("team", provider_id)

The enrollment must belong to you in the same namespace. The partition and optional account must be permitted by the declaration. Status reports not_checked until readiness checks exist; registration does not test SSH, paths or executables, provision machines, or submit jobs. Kubernetes declarations are accepted, but Kubernetes runner associations are not yet supported.

Recover a missing response

After a timeout or lost connection, look up the receipt using the original request ID:

bash

dreamlake providers operations find team --request-id research-register-001 --json
dreamlake providers operations show team/OPERATION_ID --json

python

receipt = client.providers.operations.find("team", "research-register-001")
receipt = client.providers.operations.get("team", receipt["operationId"])

The client does not retry writes automatically. If no receipt is found, retry the original command with exactly the same input and request ID. A receipt is a historical snapshot; use status for current state. Receipts are visible to their creating user.

Retire configuration

Use the current revision of the resource being retired. To retire only an association, include its ID and revision:

bash

dreamlake providers retire team/PROVIDER_ID --association ASSOCIATION_ID \
  --revision 1 --request-id research-association-retire-001 --json
dreamlake providers retire team/PROVIDER_ID \
  --revision 1 --request-id research-provider-retire-001 --json

python

client.providers.retire(
    "team", provider_id,
    association_id=association["resource"]["id"],
    revision=association["resource"]["revision"],
    request_id="research-association-retire-001",
)
client.providers.retire(
    "team", provider_id, revision=registration["resource"]["revision"],
    request_id="research-provider-retire-001",
)

Retirement changes metadata. It does not stop jobs, remove hosts or delete Vault entries. Retire associations separately when you want their records marked retired. Declarations and associations are immutable in this version; editing declarations and upgrading legacy provider records are not yet supported.

Errors and API reference

CLI --json errors include the request ID and, for HTTP failures, status and a recognized error code. Python API and transport failures raise ProviderError subclasses with request_id; HTTP failures also carry status and code. ProviderConflictError identifies a conflicting request or revision, and ProviderNotFound identifies an unavailable resource or receipt.

See the HTTP contract and error codes for request shapes and limits.