DreamLake

CI/CT with GitHub Actions

dl cict manages CI/CT channel A: GitHub Actions jobs that ask for a DreamLake label (runs-on: dreamlake-<pool>) run on DreamLake machines through single-use runners, and their declared evidence is written to a Source. How the flow works, the workflow contract and the evidence files are described in the product guide, CI/CT with GitHub Actions.

These commands need a server with the GitHub runner integration enabled; otherwise every command returns HTTP 404 github_runners_disabled. The same operations are available in TypeScript as dl.cict(namespace) and in Python as client.cict.

Where a namespace stands

bash
dl cict status my-team
dl cict status my-team --json

status lists every setup step (GitHub, DreamLake GPU, and the six steps for your own Slurm cluster), marks which are done and prints the next one with the page, command and API call that does it. Once ready it prints the runs-on line to use. It is the starting point for an agent setting up CI/CT: repeat it and do the next step. Only installing the GitHub App needs a person in a browser; enrolling a login node needs SSH, and binding its service account needs a namespace owner. TypeScript: dl.cict(ns).onboarding().

Connect GitHub

bash
dl cict github connect my-team
dl cict github installations my-team
bash
dl cict github connect my-team

connect prints a GitHub App install link. Open it within 15 minutes in a browser signed in to DreamLake as the same user, install the App on an organization or account and select repositories. GitHub returns to the DreamLake setup page, which binds the installation to the namespace after checking that your GitHub user can access it. Starting the binding requires the namespace's execution-admin permission.

bash
dl cict github installations my-team --json

An installation is bound to one namespace. Uninstalling or suspending the App on GitHub deletes or suspends the binding.

Runner pools

A pool maps runs-on labels to a Slurm provider and, optionally, to a Source for evidence. Jobs whose labels match no pool are recorded as unmatched and get no runner.

bash
dl cict pools create my-team --name bos14-gpu \
  --provider 0123456789abcdef01234567 \
  --evidence-source 1123456789abcdef01234567
dl cict pools list my-team
dl cict pools delete my-team/2123456789abcdef01234567
bash
dl cict pools create my-team --name bos14-gpu \
  --provider 0123456789abcdef01234567 \
  --evidence-source 1123456789abcdef01234567 --evidence-prefix ci \
  --env DREAMLAKE_ROBOT_ASSETS_CACHE=/work/assets
  • --name is lowercase letters, digits and hyphens. Without --label, the pool serves the single label dreamlake-<name>. Each --label must be dreamlake or start with dreamlake-; self-hosted, linux and x64 are implicit. When several pools match a job, the most specific wins.
  • --provider is a Slurm provider in the namespace on which you have your own association. Runners start as you (the pool creator) until service-account grants replace this.
  • --evidence-source receives each run's evidence under <prefix or ci>/<owner>/<repo>/<YYYY-MM-DD>/<HHMMSS>_<job>_<sha7>_<jobId>.
  • --env NAME=value adds a machine fact every job sees, such as a cache path on the cluster. Values are visible to anything running on the pool; never pass secrets. Names starting with DREAMLAKE_GITHUB, DREAMLAKE_RUN, DREAMLAKE_RESULTS, DREAMLAKE_METRICS, DREAMLAKE_JOB, DREAMLAKE_CACHE, GITHUB_, RUNNER_ or SLURM_ are refused. At most 32.
bash
dl cict pools list my-team --json
bash
dl cict pools delete my-team/2123456789abcdef01234567

Deleting is refused with runner_pool_busy while the pool still serves running jobs or collects their evidence; delete it after they finish.

bash
dl cict pools update my-team/2123456789abcdef01234567 --provider 0123456789abcdef01234567
dl cict pools update my-team/2123456789abcdef01234567 --no-evidence --clear-env

update changes a pool for the next job; running jobs keep the provider, evidence location and environment they started with. --env replaces every variable. The name cannot change.

bash
dl cict pools targets my-team

targets lists the namespace's Slurm providers and whether a pool can start runners on each: usable, or the reason it cannot (no_association: no host is bound to it; no_launch_layer: no GPU, memory and time settings; legacy_provider).

Runs

A run is one GitHub Actions job that asked for a DreamLake label, joined with the runner that served it. Its ID is <installationId>-<jobId>.

bash
dl cict runs list my-team --limit 20
dl cict runs show my-team/91234567-48812345678 --result
bash
dl cict runs list my-team --limit 20 --json

Each line shows the run ID, status or conclusion, repository, job, commit, routing (pool name, unmatched, unbound or rejected:<reason>) and the evidence state (pending, written, failed or none).

bash
dl cict runs show my-team/91234567-48812345678
dl cict runs show my-team/91234567-48812345678 --result --json

show adds the GitHub job link, the runner and its Slurm job, a runner error code when start failed, and the evidence location. --result also reads the run's result.json from the evidence Source; it is null when the run wrote none or evidence is not written yet.

bash
dl cict runs compare my-team/91234567-48812345678
dl cict runs compare my-team/91234567-48812345678 --all --json

compare lists the cases that changed against the baseline: the latest earlier run of the same repository, workflow and job on the default branch whose evidence was written. Each case is regressed, fixed, still_failing, unchanged, added or removed, with the change in its score (such as normalized return) when both runs report one.

DreamLake GPU

DreamLake GPU runs jobs on machines DreamLake provides, chosen by runs-on label; no pool is needed. The DreamLake team enables it for a namespace.

bash
dl cict platform show my-team
dl cict platform start my-team
dl cict usage my-team
bash
dl cict platform show my-team --json

show prints the machine catalog with each machine type's price per GPU-hour, whether the namespace may use it (not enabled, enabled but not started, in use, or paused), its concurrency limit, running and queued jobs, where results go and this month's GPU time. With prepaid billing on it adds what this month was charged; otherwise what the GPU time is worth (not charged).

dl cict runs show adds a cost line for a DreamLake GPU job: the credit it holds while it runs (its time limit at its price), then what it was charged (the GPU time Slurm measured), or why it was not charged. Billing runs on sandboxes for now: no real money moves.

bash
dl cict platform start my-team
dl cict platform start my-team --source 1123456789abcdef01234567

start creates the cict-evidence Source for results, or uses --source, and records you as the person who authorizes those writes. Creating a Source needs the namespace admin role.

bash
dl cict platform source my-team --source 1123456789abcdef01234567
bash
dl cict usage my-team
dl cict usage my-team --month 2026-10 --json
dl cict usage my-team --jobs --sender octocat --limit 20

usage reports a month of DreamLake GPU time, from each job's start to its end, by the GitHub user who triggered each job and by repository and workflow. --jobs lists the jobs newest first instead; --sender LOGIN keeps one person's and --limit caps how many (1–500). The month line and each job show what was charged (or charge pending until Slurm reports), or what the GPU time is worth when DreamLake GPU is not billed.

Administer DreamLake GPU

These commands are for admins of the platform namespace.

bash
dl cict platform admin list
dl cict platform admin allow robotics-lab --limit 2
dl cict platform admin pause robotics-lab
bash
dl cict platform admin list --json
bash
dl cict platform admin allow robotics-lab --limit 2

allow lets a namespace use DreamLake GPU, or resumes a paused one. A namespace whose admin already started keeps its results Source.

bash
dl cict platform admin pause robotics-lab
bash
dl cict platform admin limit robotics-lab 4
bash
dl cict platform admin providers

providers lists the Slurm providers in the platform namespace and what one job gets on each, read from its launch layer. A provider without a bound host, a launch layer or a GPU in it cannot back a machine type.

bash
dl cict platform admin machine gpu-rtx5090 --label dreamlake-gpu-rtx5090 \
  --provider 0123456789abcdef01234567 --limit 6 --enable \
  --env DREAMLAKE_ROBOT_ASSETS_CACHE=/work/shared/robot-assets
dl cict platform admin machine gpu-rtx5090 --disable
dl cict platform admin machine gpu-rtx5090 --price 240

machine creates or changes a machine type. A machine type is what one job gets, not one machine: jobs land on any free node of the provider's partition. The GPUs, CPUs, memory and time limit come from the provider's launch layer, so they always match what Slurm allocates; --limit caps jobs at once across all namespaces. Runners start with the provider's association. --price sets the price in credits per GPU-hour (one credit is $0.005, so 240 is $1.20); --price 0 makes it free and --price none clears it. A job keeps the price it started at, so a change applies to later jobs only. A machine type without a price cannot run jobs while billing is on.

Troubleshooting

SymptomMeaning
routing unboundThe repository's App installation is not bound to a namespace; run dl cict github connect.
routing unmatchedNo pool or DreamLake GPU label covers every label in runs-on; check dl cict pools list and dl cict platform show.
queued #NA DreamLake GPU job waiting for a slot in the namespace or on the machine type.
held: insufficient_creditThe namespace's credit cannot cover what the job holds while it runs; add credit in Settings → Billing and it starts within a minute.
held: billing_budget_exceededThe namespace's spending limit is reached (a new account's limit is zero); a namespace owner raises it in Settings → Billing.
held: billing_setup_requiredThe namespace has no billing account yet; a namespace owner sets it up in Settings → Billing.
held: machine_unpricedThe machine type has no price; a platform admin sets one with --price.
held: evidence_authorizer_invalidThe person who authorized result writes can no longer write; run dl cict platform source.
routing refused:platform_not_activatedDreamLake GPU is enabled but not started; run dl cict platform start.
routing refused:platform_not_allowedDreamLake GPU is not enabled for the namespace.
routing rejected:public_repositoryPublic repositories are refused unless the server allows them.
runner failed with target_not_supportedThe pool targets a host; only Slurm pools start runners today.
evidence failedThe run declared no readable results.json, or a declared path was invalid. See the product guide.