# DreamLake — Full documentation

> DreamLake is ML experiment tracking for robotics and embodied AI — record, store, browse, and search multimodal data, publish renderable artifacts, and run remote compute.

Generated from https://docs.dreamlake.ai. 111 pages.

---

Source: https://docs.dreamlake.ai

# DreamLake

  ML experiment tracking for robotics and embodied AI. Record, store, browse,
  and search multimodal episode data — video, audio, tracks, logs, and
  parameters — from one CLI, one Python SDK, and one dashboard.

## Install

One command, and there is no runtime to install first. The `dreamlake` CLI is a
single native binary that lives in your home directory and keeps itself up to
date.

**macOS, Linux, WSL**

```bash file="terminal"
curl -fsSL https://dl.dreamlake.ai/install.sh | bash
```

**Windows (PowerShell)**

```powershell file="terminal"
irm https://dl.dreamlake.ai/install.ps1 | iex
```

**Windows (CMD)**

```batch file="terminal"
powershell -NoProfile -Command "irm https://dl.dreamlake.ai/install.ps1 | iex"
```

Then open a new terminal and check it worked:

```bash file="terminal"
dreamlake --version
```

> **Note:** Downloads the binary for your platform, checks its SHA-256 against the
> release manifest, and installs entirely under `$HOME`:
>
> - `~/.local/share/dreamlake/versions/<version>` — the binary
> - `~/.local/bin/dreamlake` — symlink to the active version
> - appends one line to your login shell's rc file if `~/.local/bin` isn't
>   already on `PATH`
>
> No `sudo`, and nothing outside your home directory. The installer refuses
> to run under `sudo` for exactly this reason.

Platforms, release channels, version pinning, troubleshooting, and uninstall
steps are in the [install reference](#install-reference) at the bottom of this
page.

## Your first episode

The walk-through below takes about five minutes. Every command assumes
`dreamlake` is on your `PATH`.

### Authenticate

```bash file="terminal"
dreamlake login
```

Opens your browser for OAuth device auth and stores a token locally — you only
do this once per machine. On headless machines, add `--no-browser` to get a QR
code instead. Point at a self-hosted server with `--url <server>`.

### Upload

```bash file="terminal"
dreamlake upload ./run01.mp4 \
  --episode alice@robotics:run-042 \
  --to /camera/front
```

That single command chunks the file, uploads it to S3-backed storage, registers
the asset on the server, and (for video) triggers HLS splitting — the episode is
immediately browsable in the dashboard. File type is auto-detected from the
extension. Large files are chunked (10 MB parts, 4 parallel workers) and
uploaded via S3 multipart, so an interrupted upload resumes where it left off.

| Extension | Type |
|-----------|------|
| `.mp4`, `.mov`, `.mkv`, `.webm` | video |
| `.wav`, `.mp3`, `.flac`, `.aac` | audio |
| `.vtt`, `.srt` | text-track |
| `.jsonl`, `.csv` | label-track |

### List and download

```bash file="terminal"
dreamlake list --episode alice@robotics:run-042
dreamlake download --episode alice@robotics:run-042 --from /camera/front -o ./video.mp4
```

### Organize with bindrs and datasets

A **bindr** is a curated collection of files matched by glob; a **dataset**
groups bindrs into a training-ready unit:

```bash file="terminal"
dreamlake create bindr "front-camera" --project robotics@alice --episode "2026/04/*"
dreamlake create dataset "training-v1" --project robotics@alice
dreamlake update dataset "training-v1" --project robotics@alice --add "front-*"
```

See the [CLI Reference](/cli.md#collections) for the full create / update /
delete / list surface.

### Episode syntax

The `--episode` flag everywhere uses `[namespace@]project[:episode]`:

| Example | Namespace | Project | Episode |
|---------|-----------|---------|---------|
| `robotics` | (current user) | `robotics` | — |
| `alice@robotics` | `alice` | `robotics` | — |
| `alice@robotics:run-042` | `alice` | `robotics` | `run-042` |

### Environment variables

| Variable | Description |
|----------|-------------|
| `DREAMLAKE_REMOTE` | Server URL (overrides the stored login) |
| `DREAMLAKE_BSS_URL` | BSS storage URL |
| `DREAMLAKE_API_KEY` | API token — skips interactive login, for CI |

## How it fits together

```
dreamlake CLI  /  Python SDK
    ├── Upload file ──→ BSS (S3 storage, HLS splitting)
    └── Register asset ──→ DreamLake Server (catalog, auth)
                              ├──→ Dashboard (browse, render, share)
                              └──→ Qdrant (semantic search)
```

| Component | Role |
|-----------|------|
| **dreamlake CLI** | Native binary — upload, download, collections, artifacts, workflows — [own docs](https://cli.dreamlake.ai) |
| **dreamlake-py** | Python SDK — video slicing, tracks, vector index |
| **dreamlake-server** | Fastify API — catalog, auth (JWT), visibility, search routing |
| **BSS** | S3-backed binary storage with HLS video splitting |
| **Dashboard** | Browse episodes, render artifacts, manage sharing at [dreamlake.ai](https://dreamlake.ai) |
| **Qdrant** | Vector index (CLIP embeddings) behind semantic search |
| **Lakeshore** | Queue-native remote compute — [own docs](https://lakeshore.dreamlake.ai) |

## Explore the docs

    Load, slice, and batch video in Python with lazy, NumPy-style indexing —
    frames to tensors in one line.

    Query hours of footage with natural language — CLIP embeddings over 2-second
    chunks, indexed in Qdrant.

    Push a renderable file, get a live page — versioned, shareable, and safe to
    delete.

    Every `dreamlake` command, versioned with each release — full reference at
    cli.dreamlake.ai.

    The REST surface behind the CLI and dashboard — auth, episodes, nodes,
    tracks, search, and artifacts.

    How the pieces fit: the data model, node tree, auth flow, and upload
    pipeline.

    DreamLake's elastic compute fabric — run Python functions on remote workers
    with a decorator.

    The dreamlake-ai org — SDKs, server, skills, and example pipelines.

Ready to go deeper? Jump straight to the [Architecture](/architecture.md) overview.

## Install reference

Everything below is the long tail of installing and maintaining the CLI. You do
not need any of it to get started.

### Supported platforms

| Platform | Architectures |
|---|---|
| macOS 13+ | Apple Silicon, Intel |
| Linux (glibc) | x86-64, arm64 |
| Linux (musl / Alpine) | x86-64, arm64 |
| Windows 10+ | x86-64, arm64 |

32-bit Windows is not supported. Inside WSL, use the Linux command rather
than the PowerShell one — you are installing into the Linux side.

### Staying up to date

At most once every four hours, a command may start a short detached
background process that checks for a new release and installs it; the new
version takes effect the next time you run a command. To update right now:

```bash file="terminal"
dreamlake self-update
```

> **Note:** Windows locks a running `.exe`, so there is no background updater there.
> Run `dreamlake self-update` when you want a new version. `dreamlake
> self-update --status` reports this under `auto:`.

> **Note:** `dreamlake update` edits bindrs, datasets, and projects. Updating the CLI
> itself is `dreamlake self-update`.

### Release channels

`latest` (the default) gets every release as it ships. `stable` trails by
about a week and skips releases with known regressions.

```bash file="terminal"
dreamlake self-update channel stable   # switch channel
dreamlake self-update                  # apply it
```

### Pin a version

Asking for an exact version pins it: auto-update stops until you choose a
channel again. This is what you want in a CI image or when a release
regresses.

**Windows (PowerShell) tab:** On Windows, pass the target through the script block:

**macOS, Linux, WSL**

```bash file="terminal"
curl -fsSL https://dl.dreamlake.ai/install.sh | bash -s 0.3.0
dreamlake self-update 0.3.0            # or, once installed
dreamlake self-update channel latest   # unpin and resume updates
```

**Windows (PowerShell)**

```powershell file="terminal"
& ([scriptblock]::Create((irm https://dl.dreamlake.ai/install.ps1))) 0.3.0
```

`dreamlake self-update --status` shows whether you're pinned.

### Turn updates off

| Variable | Effect |
|---|---|
| `DREAMLAKE_DISABLE_AUTOUPDATER=1` | No background checks; `self-update` and `install` still work |
| `DREAMLAKE_DISABLE_UPDATES=1` | Blocks every path that changes your version, including `self-update` and `install` |

### Troubleshooting

`dreamlake doctor` prints where the binary lives, which version the
launcher points at, your channel, and the last auto-update result — no
network calls, no session started.

**`command not found` after installing.** The installer appended to your
shell rc but the current shell predates it. Open a new terminal, or:

```bash file="terminal"
export PATH="$HOME/.local/bin:$PATH"
```

**`dreamlake` still runs an old version.** Something else on your `PATH`
answers to the same name — usually an npm install of the CLI, or the
retired Python console script. The installer warns about this, and `doctor`
names the file under `on PATH:`. Check with:

```bash file="terminal"
which -a dreamlake
```

Then remove the other one, or put `~/.local/bin` ahead of it:

```bash file="terminal"
npm uninstall -g @dreamlake/dreamlake-cli     # if it came from npm
```

This one is worth ruling out first, because it does not look like a
failure: the old binary keeps answering and every command appears to work.

### From source

For working on the CLI itself:

```bash file="terminal"
git clone https://github.com/dreamlake-ai/dreamlake-cli.git
cd dreamlake-cli && pnpm install
pnpm cli --help
```

### Uninstall

**Windows (PowerShell) tab:** On Windows:

**macOS, Linux, WSL**

```bash file="terminal"
rm -f  ~/.local/bin/dreamlake
rm -rf ~/.local/share/dreamlake ~/.local/state/dreamlake ~/.dreamlake
```

**Windows (PowerShell)**

```powershell file="terminal"
Remove-Item "$env:USERPROFILE\.local\bin\dreamlake.exe" -Force
Remove-Item "$env:USERPROFILE\.local\share\dreamlake" -Recurse -Force
```

Add `rm -rf ~/.config/dreamlake` to also drop your saved logins. On macOS
and Linux, remove the `# added by the dreamlake installer` block from your
shell rc; on Windows, drop `%USERPROFILE%\.local\bin` from your user `Path`
in **System Properties → Environment Variables**.

---

Source: https://docs.dreamlake.ai/ml-dash

# ML-Dash

  ML experiment tracking and data storage. Log parameters, metrics, logs,
  files, and time-series tracks from Python, keep them on disk or send them to
  a dash.ml server, and browse them in the dashboard.

This section documents ML-Dash SDK **0.7.0** and CLI **0.1.1**. The dash.ml
web dashboard is documented separately at
[docs.dash.ml](https://docs.dash.ml/dashboard/overview).

## Install

ML-Dash comes in two parts, installed separately:

| Part | What it does | Install |
|---|---|---|
| **Python SDK** — the `ml_dash` package | Logs from your training code | `pip install ml-dash` |
| **CLI** — the `ml-dash` command | Logs in, lists projects, uploads and downloads runs | standalone binary or npm |

You only need the SDK to track runs locally. Install the CLI as well to log in
to dash.ml.

### Python SDK

```bash
pip install ml-dash
```

Python 3.9 or newer. Two optional extras:

- `ml-dash[auth]` — reads the login token from the OS keychain. You need it on
  machines where `ml-dash login` stores the token there (see
  [Authentication](/ml-dash/get-started/authentication.md#where-the-token-lives)).
- `ml-dash[video]` — saves videos from frame arrays (`save_video`).

```bash
pip install "ml-dash[auth]"
```

### CLI

**macOS, Linux:** one self-contained binary. You don't need Node or Python.

```bash
curl -fsSL https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.sh | sh
```

**Windows (PowerShell):**

```powershell
irm https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.ps1 | iex
```

**If you already have Node.js 20.19 or newer:**

```bash
npm install -g @dreamlake/ml-dash
```

The npm package is scoped, but the command it installs is still `ml-dash`.
Check it worked:

```bash
ml-dash version
```

> **Warning:** From SDK **0.7.0**, `pip install ml-dash` installs only the Python SDK. The
> `ml-dash` command is now a separate program and is installed on its own, as
> shown above. See [Upgrading from 0.6](#upgrading-from-06).

## Your first experiment

### Track a run locally

You don't need an account or a server. By default an experiment writes to
`.dash/` in the current directory:

```python
from ml_dash import Experiment

with Experiment(prefix="alice/tutorial/first-run").run as exp:
    exp.params.set(learning_rate=0.001, batch_size=32, epochs=10)
    exp.log("Training started")

    for epoch in range(10):
        loss = 1.0 - epoch * 0.08  # your real loss here
        exp.metrics("train").log(loss=loss, epoch=epoch)

    exp.log("Training finished")
```

The prefix is `owner/project/experiment`. The run lands on disk as:

```
.dash/
└── alice/                    # owner
    └── tutorial/             # project
        └── first-run/        # experiment
            ├── logs/logs.jsonl
            ├── parameters.json
            └── metrics/train/data.jsonl
```

### Log in

```bash
ml-dash login
```

The CLI prints a short code and a QR code, and opens your browser to approve
it. The token is saved on your machine, and the SDK reads it from there. See
[Authentication](/ml-dash/get-started/authentication.md).

### Send runs to dash.ml

Pass `dash_url`, and the same code also writes to the server:

```python
with Experiment(
    prefix="alice/tutorial/first-run",
    dash_url="https://api.dash.ml",
).run as exp:
    ...
```

When the run starts, the SDK prints a link to it on
[dash.ml](https://dash.ml). Runs you already tracked locally can be uploaded
with the CLI:

```bash
ml-dash upload                  # everything under ./.dash
ml-dash list                    # confirm it arrived
```

## How it fits together

```
training script ── ml_dash SDK ──┬──→ .dash/ on disk         (local mode)
                                 └──→ ML-Dash server ──→ dash.ml dashboard
                                        ↑    (remote mode)
ml-dash CLI ── login, list, upload, download
```

| Component | Role |
|---|---|
| **`ml_dash` (PyPI)** | Python SDK. `Experiment` with `params`, `metrics`, `logs`, `files`, and `tracks` |
| **`ml-dash` CLI** | Login, projects, bulk upload and download, raw GraphQL. Ships from npm and as a standalone binary |
| **ML-Dash server** | REST and GraphQL API at `https://api.dash.ml` that stores runs, metrics, and files |
| **Dashboard** | Browse, chart, and compare runs at [dash.ml](https://dash.ml) |

## Explore the docs

    Prefixes, local, hybrid, and remote mode, and the run lifecycle.

    Step-indexed scalars: loss curves, accuracy, learning rate.

    Checkpoints, configs, figures, and videos, with metadata.

    Timestamped multi-modal streams for robotics and RL.

    Navigate, chart, and compare runs on dash.ml.

    Complete training scripts, from a minimal loop to PyTorch MNIST.

    Every public class and method in the SDK.

    Every `ml-dash` command and flag.

Working with an AI agent? Every page is also available as markdown and as an
importable skill. See [LLM-Readable Docs](/ml-dash/reference/llm-readable.md).

## Install reference

The rest of this page covers maintaining an install. You don't need it to get
started.

### Updating the CLI

```bash
ml-dash update           # install the latest release
ml-dash update --check   # only report whether one exists
```

`update` uses whichever channel you installed from. An npm install runs
`npm install -g @dreamlake/ml-dash@<version>`. A standalone binary downloads the
new build, checks it against the release's sha256, runs it once, and only then
replaces itself. If any step fails, your working binary stays as it was.
`update` never downgrades.

Update the SDK with pip:

```bash
pip install -U ml-dash
```

### Pin a CLI version

```bash
curl -fsSL https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.sh | sh -s -- --version 0.1.1
```

```powershell
& ([scriptblock]::Create((irm https://pub-42e1dcc7de574d4a92984865fdc95f10.r2.dev/install.ps1))) -Version 0.1.1
```

With npm: `npm install -g @dreamlake/ml-dash@0.1.1`. An installed CLI can move
to an exact newer release with `ml-dash update --version <x.y.z>`. `update`
refuses to downgrade, so use one of the commands above to go back to an older
release.

### Where the standalone CLI installs

The installer checks every download against the sha256 in that release's
manifest before writing anything. It installs into `~/.local/bin`
(`%LOCALAPPDATA%\ml-dash\bin` on Windows), which you can change with
`--install-dir` / `-InstallDir`. It never overwrites an `ml-dash` that npm or
pip installed. It reports the conflict on `PATH` and leaves it to you.

### Supported platforms

macOS (arm64, x64), Linux (x64, arm64; glibc and musl), and Windows (x64,
arm64). The binaries bundle their own runtime. On Alpine, the musl builds need
one system library first:

```bash
apk add --no-cache libstdc++
```

### Upgrading from 0.6

SDK 0.6.27 and earlier installed an `ml-dash` command as part of
`pip install ml-dash`. That Python CLI was removed in **0.7.0**:

- `pip install -U ml-dash` removes the old `ml-dash` command. Install the new CLI
  before or right after you upgrade if your scripts call `ml-dash`.
- The command names and arguments carry over. The new CLI reads and writes the
  same keychain entry and `~/.dash/` files, so an existing login normally keeps
  working. If it doesn't, run `ml-dash login` again.
- The `ml_dash.cli` and `ml_dash.cli_commands` modules are gone. Code that
  imported them should run the `ml-dash` binary instead.
- The SDK itself (`Experiment`, `params`, `metrics`, `logs`, `files`,
  `tracks`) is unchanged.

Docs for earlier releases are in the version menu at
[docs.dash.ml](https://docs.dash.ml).

---

Source: https://docs.dreamlake.ai/notes/linked-items

# Linked note items

Turn a list item into a note while keeping the parent list compact.

**Development preview:** available in the Notes extraction development UI. Production UI release is not yet verified.

1. Click **Turn list item into a note** at the right edge of any numbered, bullet or checkbox item.
2. The item text and nested content move into a new private note. Its first line becomes the title. The parent keeps its number or checkbox.
3. The reference displays a short hash and title, with an ellipsis when the title is too long.
4. Click the reference to open an editable tab in the panel on the right. Create that panel only when absent; subsequent references add tabs there. References opened from a side Note add tabs in that same side panel. An already-open Note is focused instead of duplicated. On a narrow screen, navigation fills the viewport. Closing a tab does not delete the Note.

## Plain Markdown

Only the full note ID is saved in the reference:

```markdown
1. :note[6aa9951250d9de84058e8ebb]
   - [ ] Discuss :note[6aa989ea6aff1e1960afc51f] before the demo.
```

You can edit text before and after the reference. The short hash and title are display values, not stored Markdown. Renaming the child does not change its ID; reopening the parent resolves its current title. References inside code remain literal text.

Linked notes retain their own permissions. Creating a reference does not grant access to the child or make it public. A missing or inaccessible note displays **Unavailable note**.

If an item changes during creation, the source stays intact and the new note opens separately. If a request fails, inspect Notes before trying again. Undoing the parent replacement does not delete the child.

## Rich-component notation

The Note picker, extraction and copy button prefer `:note[<full-note-id>]`.
The renderer preserves saved `#note:<full-note-id>` and `:note{id="<full-note-id>"}`.
Keep existing source unchanged; never bulk-migrate notation. Display titles and
short hashes are never reference IDs.

For an artifact, use `:artifact[geyang/pitch-deck]`; saved
`:artifact{namespace="geyang" id="pitch-deck"}` and `#artifact:geyang/pitch-deck`
remain supported. Brackets hold primary content; braces are only named attributes.
This is the remark-directive Markdown extension convention, not core CommonMark;
DreamLake defines resource semantics. Bare `:note{ID}` / `:artifact{namespace/id}`
are invalid. Other preferred forms are `:bindr[id]`,
`:asset-reference[id]{caption="plot"}`, `:placeholder[owner name]` and
`:chatgpt-content-reference[0]`. Imported ChatGPT forms remain unresolved;
never invent resources. Saved attribute forms and `[ owner name ]` remain supported.
The artifact extension is a development preview, not a verified production release.
Artifact IDs require their namespace; references grant no access. See
[Notes reference syntax](/notes/#artifact-references-development-preview).

## Sync recovery

Each open note has its own collaborative state. If sending pauses, preserve the
local draft before choosing **Out of sync ▾ → Use server version**. Downloading
the parent draft does not back up unsent text in the child editor. Follow the
[Notes recovery steps](/notes/#reconnect-and-recovery) for each affected note.
Do not retry extraction or rewrite a parent from stale text to bypass a sync hold.

## Agent skill

[Download the linked-note skill](/skills/dreamlake-note-references.zip). Extract `dreamlake-note-references` into your agent's skills directory. The skill covers raw token storage, nested item extraction, concurrency checks, and CLI readback.

---

Source: https://docs.dreamlake.ai/notes/markdown

# Markdown authoring

Write Markdown directly in a Note. Live preview renders formatting while retaining
the source for editing and collaboration. Use headings for structure, lists for
steps, and color sparingly to emphasize a status or phrase.

## Everyday formatting

```markdown
# Project update

**Decision:** proceed with the pilot.

- Owner: Ada
- [ ] Confirm the schedule
- [x] Review the proposal

Read the [project brief](https://example.com/brief).
Use `status` for inline code.
```

## Nested ordered lists

Write ordered lists with numeric Markdown markers (`1.` or `1)`) and indent
children beneath their parent:

```markdown
1. First step
   1. First substep
      1. First detail
      2. Second detail
   2. Second substep
2. Next step
```

Rendered Notes preserve each numeric marker as written, including its number
and `.` or `)` delimiter. Nesting does not change the marker style. Each nested
list is indented, with wrapped lines aligned beneath the item text. The editor
retains the source markers too.

Inside an ordered list, a child may start at `2.`, `10)`, or another number;
the editor and rendered Notes preserve the same nesting and marker. For example:

```markdown
1. Parent
    2) Child
        10. Grandchild
```

Press Tab on an item to nest it under the preceding sibling, or Shift+Tab to
move it back out. Tab leaves the first item at its current level when there is
no preceding sibling; repeated Tab presses do not turn it into a code block.
The shortcuts also work with the caret at the start of the item line.

Four spaces also work for a child beneath `1. Parent`; the indentation must
belong to a parent list item. At the top level, four leading spaces create an
indented code block. In the editor, continuation lines keep their structural
indentation when the cursor moves away; extra spaces within prose still collapse
in live preview without changing the saved source.

Typed `a.`, `a)`, `(a)`, `i.`, `ii.`, `一、`, and `（一）` are plain text,
not Markdown list markers. Chinese text is supported inside ordinary numeric
or bullet lists. A numeric `1)` marker displays as `1)` in rendered Notes.

## Color a phrase

Brackets hold the text; braces follow the brackets and hold named attributes:

```markdown
:color[Needs review]{color="#b45309"}
:color[Ready]{color="green"}
:color[Blocked]{color="#ef4444"}
```

These are DreamLake color directives using the Markdown directive convention
`:name[content]{attribute="value"}`. Standard Markdown has no text-color syntax.
The `:color` directive changes the foreground text color. Use `:highlight` for a
background tint; arbitrary CSS is not supported.

Use a visible word such as “Blocked” as well as color, and check readability in
both light and dark themes. A fixed color stays the same when the theme changes.

### Preview in light and dark themes

The same note renders an inline phrase and a colored table status in both themes:

![Light theme: red Important text above a table with a green Ready status.](/images/notes/inline-color-light.png)

![Dark theme: the same red phrase and green table status on a dark background.](/images/notes/inline-color-dark.png)

Captured from the deployed app using a sample read-only note. Fixed colors do not
adapt to the theme; choose a color with enough contrast in the theme you use.
The sample uses `:color[Important]{color="#ef4444"}` and
`:color[Ready]{color="green"}`.

### Supported values and text

Color values must be double-quoted. Use 3, 4, 6 or 8 hexadecimal digits after `#`
(the 4 and 8-digit forms include alpha), or one of these case-insensitive names:
`black`, `silver`, `gray`, `white`, `maroon`, `red`, `purple`, `fuchsia`, `green`,
`lime`, `olive`, `yellow`, `navy`, `blue`, `teal`, `aqua`, `orange`, `rebeccapurple`.

Content is plain text: nested Markdown, HTML and nested directives are not rendered.
Escape brackets and backslashes with a backslash. Attribute-only syntax is also accepted:

```markdown
:color[Review \[draft\]]{color="orange"}
:color{text="Ready" color="green"}
```

Place a directive at the beginning of a line or after whitespace or an opening
parenthesis. Select the directive in the editor to reveal and edit its source.
Invalid colors, missing text, duplicate attributes and unknown attributes remain
literal. A backslash before the colon or a code span keeps the syntax visible.
Directives inside Markdown links remain literal.

## Highlight a phrase

```markdown
:highlight[Review needed]
:highlight[Key finding]{color="#60a5fa"}
:highlight{text="Decision" color="orange"}
```

Highlights use a translucent background tint and inherit the surrounding text
color in light and dark themes. They accept the same quoted color values,
plain-text content and escaping rules as `:color`. Select the highlighted phrase
to edit its original source. Omit `color` for yellow; an explicitly empty or
invalid color remains literal.
`==text==` and raw HTML `<mark>` are not supported highlight syntax.

Add `user="geyang" comment="Check the source"` alongside `color` to attach plain-text
metadata: `:highlight[Key finding]{user="geyang" comment="Check the source"}`.
Use the inline/sidebar comments toggle: inline shows no annotation cards or hover
popups. Sidebar mode shows compact metadata cards in the table-of-contents column,
following passages visible in the current viewport. Click highlighted text in the
editor or use the sidebar edit action to reveal its original source.
Use canonical public handles, not display names or internal user IDs. Attribution
is self-declared; legacy names remain unresolved. See
[Highlight metadata](/notes/#highlight-metadata) for escaping and revision-safe agent edits.

### Highlight preview in both themes

![Light theme: yellow, blue and orange highlights in the live editor and rendered Markdown.](/images/notes/highlight-light.png)

![Dark theme: the same highlights inherit readable light text.](/images/notes/highlight-dark.png)

Captured from the app's actual editor and Markdown renderer using
`scripts/highlight-preview.html` (serve with
`pnpm exec vite --config scripts/highlight-preview.config.ts`; add `?dark` for dark mode).

## Use color in tables

```markdown
| Item | Status |
| --- | --- |
| Proposal | :color[Ready]{color="green"} |
| Schedule | :highlight[Needs review]{color="yellow"} |
```

Color and highlights render in Notes live preview, table cells and the app’s read-only Markdown
views. Saved text, revision handling and collaborative edits retain the exact source.
CLI/API HTML snapshots and external Markdown readers may show the directive literally;
they do not automatically gain the app’s color renderer.

## Link resources

Use resource directives to reference another Note or artifact:

```markdown
:note[note-id]
:artifact[namespace/artifact-id]
```

See [Notes](/notes/) for resource attributes and API editing, and
[Linked note items](/notes/linked-items/) for extracting a list item into a Note.

---

Source: https://docs.dreamlake.ai/architecture

# Architecture

  The mental model behind DreamLake: how episodes, files, and collections are
  organized, how auth works, and what happens to a file between `dreamlake
  upload` and playback in the dashboard.

## Data model

Everything hangs off a **namespace** (a user or an org). Projects group
episodes; an episode is one recording session and owns its files, tracks,
logs, and parameters.

```
Namespace (user or org)
└── Project
    ├── Episode (a recording session)
    │   ├── Files (video, audio, labels, text tracks)
    │   ├── Tracks (time-series scalars/tensors)
    │   ├── Logs
    │   └── Parameters
    ├── Bindrs (curated file collections)
    ├── Datasets (groups of bindrs)
    └── Node tree (folder hierarchy, materialized paths)
```

Namespaces also own **artifacts** — versioned renderable documents with
per-artifact visibility and share links, kept in their own catalog (see the
[CLI Reference](/cli.md#artifacts)).

## Node tree

All files and folders are nodes in one unified tree, stored in MongoDB using
materialized paths — lookups by path are a single indexed query, no recursion.

| Node kind | Description |
|-----------|-------------|
| `project` | Top-level project node |
| `episode` | Recording session |
| `folder` | Organizational directory |
| `file`, `video`, `audio`, `image`, `text`, `code` | Leaf nodes |

Path convention: root = `","`, depth 1 = `",camera,"`, depth 2 =
`",camera,front,"`.

## Auth

A two-token system separates identity from API access:

1. **Login** — OAuth device flow via vuer-auth → short-lived token
2. **Exchange** — `POST /auth/exchange` → long-lived DreamLake JWT (HS256)
3. **API calls** — `Authorization: Bearer <dreamlake-token>`

First login auto-creates the User and Namespace records — there is no separate
sign-up step.

## Upload pipeline

```
CLI → chunk file (10 MB) → S3 multipart upload via BSS
    → register asset in DreamLake Server (creates node hierarchy)
    → trigger Lambda for HLS splitting (video/audio)
```

Uploads are resumable — progress is persisted to `~/.dreamlake/uploads/`, so an
interrupted transfer picks up at the last completed part. The HLS split is what
powers both instant playback in the dashboard and the 2-second chunks that
[semantic search](/search.md) embeds.

## Planned DreamDB maintenance

During a coordinated storage-format upgrade, the operator can temporarily pause
the Artifacts, Annotations, Envs and Workflows APIs, plus managed DreamDB Source
creation and its DreamDB write/credential endpoints. These requests return HTTP
`503` with code `DREAMDB_MIGRATION_PAUSED`, `Retry-After: 60` and
`Cache-Control: no-store`. This is a maintenance failure, **not empty data**:
retain the existing dataset and retry after service resumes; do not delete or
recreate it to work around the pause. Search and non-DreamDB Source operations
are not paused by this switch.

The server switch is `DREAMDB_MIGRATION_PAUSED=true` (off by default). It does
not revoke credentials already issued to clients or stop direct storage writes.
Operators must coordinate a scoped storage-side freeze, compatible client
versions and rollback records separately before changing dataset refs.

## Tech stack

| Component | Technology |
|-----------|-----------|
| Server | Fastify, MongoDB (Prisma), JWT |
| Storage | S3 via BSS |
| Search | Qdrant (CLIP embeddings) |
| CLI | Python |

## Next steps

    The REST endpoints these pieces expose.

    The vectorize-and-query pipeline built on the HLS chunks.

---

Source: https://docs.dreamlake.ai/notes/embeds

# Embeds and query arguments

Artifacts and previews have three presentation states:

- **Inline:** a compact reference in the text flow, with no embedded content.
- **Embed:** a block of content inside the Note, enabled with `embed="4:3"` or another supported aspect.
- **Open:** the standalone artifact page or destination page, opened in the preview/browser.

These states apply to every supported artifact content type; the directive argument
is always `embed`, independent of the content language.

Use `embed="4:3"` or `embed="16:9"` to render an artifact or web page inside
the Note. The value both enables the embed and sets its aspect ratio.
`embed="true"` is shorthand for `embed="16:9"`. Omit `embed` (or set it to
`"false"`) to keep an inline reference.

## Sizing models

**Responsive ratio:** fill the available document width and derive height from
the ratio. This is the default model; it responds when the Note panel resizes.

```markdown
:artifact[geyang/dashboard]{embed="4:3"}
:artifact[geyang/pitch-deck#slide-3]{embed="16:9"}
```

**Fixed width with ratio:** request a pixel width and derive height from the
ratio. Width still shrinks to fit a narrower document.

```markdown
:artifact[geyang/dashboard]{embed="4:3" width="640"}
```

**Fixed height:** use an explicit height for a scrollable report or web page.
Height overrides the ratio; width remains responsive unless specified.

```markdown
:preview[https://example.com/report]{title="Report" embed="true" height="480"}
:artifact[geyang/dashboard]{embed="4:3" width="640" height="400"}
```

**Content zoom:** the default `zoom="fit"` gives responsive content the embed's
viewport dimensions. It does not inspect or automatically shrink a fixed-size
third-party page. Use a percentage to scale its content independently of the
outer dimensions; 75% provides a larger internal layout viewport.

```markdown
:preview[https://example.com/report]{embed="16:9" zoom="75%" border="false"}
```

| Argument | Values | Default |
| --- | --- | --- |
| `embed` | `"true"`, `"false"`, or a positive integer ratio such as `"4:3"` | `"false"` |
| `width` | Positive pixels (bare number or `px`, up to 4096), or 1–100% | `"100%"` |
| `height` | Positive pixels (bare number or `px`, up to 4096) | From ratio |
| `zoom` | `"fit"` or integer percentages from `"25%"` through `"200%"` | `"fit"` |
| `border` | `"true"` or `"false"` | `"false"` |

Ratio terms are integers from 1 through 999. Sizing, zoom and border arguments
require an enabled embed; invalid sizing values remain literal source. CSS and sandbox permissions cannot
be changed through these arguments. Use a standalone line for larger
embeds. Hover or focus a reference, then choose the pin + **Embed** bubble below it to embed it as a block. The bubble contains only the pin icon and **Embed**. In an embedded web preview, hovering or focusing its header shows the destination URL beside the preview tag. Drag the
bottom capsule to change height, or the left/right capsules to change width.
A curved bottom-right handle resizes width and height together.
All handles appear when the pointer reaches their edge or they receive keyboard focus.
Handles also accept arrow keys (16px steps; Shift for 64px). On the corner handle, left/right change width and up/down change height. A drag saves pixel
dimensions and preserves content query arguments. The preview header shows a pinned icon at rest; hovering or focusing it reveals a red unpin icon. Click it to collapse the embed back to a reference;
content query arguments are preserved and embed sizing is removed. Edit the
directive in source to return to percentage width or ratio sizing. Read-only views do
not expose editing controls.

Embedded artifacts use the isolated, content-only artifact renderer with the
current reader's existing access; embedding does not grant access or create a
share link. Web pages must allow iframe embedding. Static HTML snapshots retain
inert references and never load embedded content.

## Query pass-through API

Keep the artifact reference or page URL in brackets. Put embed options and
content-specific query arguments together in braces:

```markdown
:artifact[geyang/video-viewer]{embed="4:3" view="contact-sheet" columns="4" frames="12"}
:preview[https://example.com/video]{embed="16:9" view="storyboard" start="30"}
```

These resource names are examples, not preinstalled artifacts. The referenced
artifact or website must implement the requested views.

Notes consumes `embed`, `width`, `height`, `zoom`, and `border`. Earlier `inline` arguments remain readable for compatibility; new embeds use `embed`. Neither key is forwarded to the renderer. Resource identity
fields (`namespace`, `id`, `fragment` for artifacts; `url` and `title` for previews)
also belong to Notes. All other valid arguments become public query parameters;
they are never interpreted as HTML attributes, CSS, or sandbox flags.

For the first example, the artifact receives
`?view=contact-sheet&columns=4&frames=12`. Its ordinary viewer link uses
`?art.view=contact-sheet&art.columns=4&art.frames=12`. Only the viewer URL uses
`art.`; do not prefix directive arguments. A fragment stays in the reference:

```markdown
:artifact[geyang/video-viewer#scene-3]{embed="16:9" view="player" start="30"}
```

Preview arguments are merged into the URL query. Brace arguments replace an
existing value with the same key; unrelated URL parameters and the fragment stay
intact. Values use quoted strings and are URL-encoded automatically, including
nested URLs. Do not pre-encode them:

```markdown
:preview[https://example.com/viewer?theme=dark]{embed="16:9" src="https://example.com/clip.mp4?a=1&b=2" view="contact-sheet"}
```

The same arguments work on clickable tags without `embed`: opening the side
panel or the ordinary viewer link carries the query to the renderer.

### Read and update configuration inside an artifact

Use the existing artifact route API rather than `window.location`: HTML artifacts
run in a nested `about:srcdoc` frame.

```html
<div id="summary"></div>
<script>
  const route = window.dreamlake.route;
  function render() {
    const query = new URLSearchParams(route.search);
    const view = query.get('view') || 'player';
    const columns = Math.max(1, Math.min(8, Number(query.get('columns')) || 4));
    document.getElementById('summary').textContent = `${view}, ${columns} columns`;
  }
  const unsubscribe = route.subscribe(render);
  render();
  // For example, a view-selector control can call:
  async function showStoryboard() {
    const query = new URLSearchParams(route.search);
    query.set('view', 'storyboard');
    await route.navigate({ search: query.toString() }, { replace: true });
  }
</script>
```

Route changes stay inside the embed; they do not rewrite the Note or inherit its
page query. Dispose subscriptions when a renderer unmounts. See the full
[artifact routing contract](/artifacts/#artifact-paths-and-local-routing) for navigation,
fragments, lifecycle, and access boundaries.

### Argument validation

Names must match `[A-Za-z][A-Za-z0-9_.-]{0,63}`. Values are double-quoted strings;
the renderer validates their meaning and parses numbers or JSON. Duplicate
arguments are invalid. Reserved route names such as `share`, `token`, `auth`,
`authorization`, `cookie`, `project`, `namespace`, `instanceId`, `__proto__`,
`prototype`, `constructor`, and `dreamlake` (including their `.`, `_`, or `-`
suffix forms) cannot be forwarded. Encoded route state is limited to 8192
characters. Invalid directives remain literal text.

Query data is public configuration, not authorization. Notes never forwards its
own URL parameters or credentials. References and queries do not grant access.

## Video, storyboard, and contact-sheet contracts

A video artifact can define these query arguments without changing Notes:

| Argument | Suggested renderer meaning |
| --- | --- |
| `view` | `player`, `storyboard` (ordered scene cards), or `contact-sheet` (frame grid) |
| `src` | A video source supported by that renderer |
| `columns` | Number of grid columns |
| `frames` | Number of evenly sampled frames |
| `interval` | Sample spacing in seconds, instead of a fixed frame count |
| `start`, `end` | Sampling or playback range in seconds |

This is a renderer API convention, not a built-in Notes video feature. A renderer
should bound sampling work, show timestamps, and make a frame open playback at
that timestamp. It should reject conflicting `frames` and `interval` options.
A future `:contact-sheet[...]` directive could be shorthand for this renderer;
it is not currently implemented.

The artifact sandbox currently blocks arbitrary remote video-file loading.
A self-contained artifact can bundle video or precomputed frames. Passing a
`src` URL does not bypass that policy; general remote-video sampling needs an
authorized host media bridge. A separately hosted viewer used through `:preview`
can implement its own video access, subject to that site's embedding policy and
its media origin's CORS rules.

Parent-scoped user-data access is tracked in
[issue #837](https://github.com/dreamlake-ai/dreamlake-workspace/issues/837).
The embedding parent and current viewer must determine the authorized context;
the artifact owner's identity alone is insufficient.

---

Source: https://docs.dreamlake.ai/annotations

{/* The Fig tags come from the site-wide mdxComponents map in
    site.config.ts — no import needed. Beyond the install commands,
    this page carries no code: every SDK call it describes is written
    out in /annotations/reference. */}

# Annotations

  An annotation is where your **labeled data** lives — your workflow does the labeling, the
  annotation stores its output. One episode is one raw video plus any number of annotation layers:
  anything you can pin to that video's clock. Layers are independent and open-ended — send what you
  have, add the rest later.

## Public catalog reads

`GET /namespaces/:slug/annotations` accepts requests without an Authorization
header. Anonymous callers and authenticated nonmembers receive only live public
annotation rows; namespace members retain access to their private rows. A supplied
invalid or expired token returns 401.

Public annotation details (`GET /namespaces/:slug/annotations/:name`) and
content reads (`POST /namespaces/:slug/annotations/:name/presign-read`) also accept
anonymous requests. Both check the annotation's current visibility. Private,
missing and deleted annotations return 404 to callers without access; namespace
members can still read their private annotations. Presigned reads retain the
existing path validation and expiry limits. Upload credentials, creation,
editing and deletion still require authentication and membership.

## Browsing in the app

`/<namespace>/profile?tab=annotations` and `/<namespace>/annotations` share the
same catalog. Personal owners and organization members see the resources and
operations permitted to them; anonymous visitors and visitors to someone else's
namespace see public annotations only. Profile has an identity rail, while the
application has resource navigation for the URL's namespace.

Public details open without a sign-in redirect and retain the namespace sidebar.
The detail header returns anonymous readers to the Profile annotations tab and
signed-in readers to `/<namespace>/annotations`. Embedded viewers return to their
containing project. See [Profiles and workspaces](/workspaces.md).

## Prerequisites

```bash
curl -fsSL https://dl.dreamlake.ai/install.sh | bash   # the dreamlake CLI
pip install dreamlake dreamdb   # SDK + storage engine
brew install ffmpeg             # transcoding (any install method works)
dreamlake login                 # browser sign-in; CI uses DREAMLAKE_API_KEY
```

Windows, what the installer puts where, release channels, and auto-update:
[Install](/index.md#install).

## Upload it

One call. The video is transcoded for the browser, each layer is stored
against its clock, and adding a layer later just means passing one more
argument. Give the episode an id you'll recognise — that's the handle for
coming back.

## Keep adding

Open an annotation by name on any day and add to it. Revisions never overwrite —
newest wins, history stays.

| Later, you can                    | Effect                                         |
| --------------------------------- | ---------------------------------------------- |
| add another episode               | the annotation grows                           |
| revise a layer                    | newest wins, old versions kept                 |
| add a layer you skipped           | it shows up on an episode you already uploaded |
| add a layer type that ships later | same thing — just another revision             |
| add a camera angle                | views share one clock; video is add-only       |
| make it public                    | anyone can open it, no login                   |

Nothing you upload today has to be re-uploaded to benefit from what ships
tomorrow.

## Watch it

Open the web app → **Annotations** → your annotation → your episode.

How a layer is drawn follows from how it's pinned — which is why the list can
grow without the picture changing:

| A layer pinned to | Is drawn                                       | Shipping today                     |
| ----------------- | ---------------------------------------------- | ---------------------------------- |
| a frame           | on the picture, tracking playback              | joint skeletons, 3D reconstruction |
| an interval       | as labeled bars on the timeline; click to seek | action segments                    |
| the whole episode | as episode metadata                            | task labels                        |

Each is optional. The player shows what you have and skips what you don't —
a bare video simply streams.

## When there's no overlay yet

Every annotation page has two views, and the second one always works.

**Preset view** is what the last section showed: the annotation's type label
matches a preset, and you get the player with its overlays.

**Raw tracks view** ignores presets and lists every track straight off the
manifest — name, kind, values along the timeline. Label, JSON, embedding,
video; it doesn't matter.

| If your data        | You get                                           |
| ------------------- | ------------------------------------------------- |
| matches a preset    | the rendered view, overlays and all               |
| doesn't, or not yet | the raw track view — nothing hidden, nothing lost |
| gets a preset later | the rendered view, with no re-upload              |

So a new kind of data is **useful the day you upload it**.

## Bring your own schema

The same machinery with the lid off: declare any columns you like — sensor
readings, JSON, images, embeddings — anchored to timestamps, or to row
numbers when your data has no clock. It's also the escape hatch when the
layer you need doesn't exist yet.

| Rule                    | What it means for you                                 |
| ----------------------- | ----------------------------------------------------- |
| append-only, write-once | a value at a given time and column is never rewritten |
| one commit per write    | send batches, not one point at a time                 |
| one writer at a time    | parallel writers to the same annotation will clash    |

Custom annotations appear in the catalog under their own type label; today
you read them back through the SDK.

## Share it

Annotations are **private** by default.

|                        | Who can view                      |
| ---------------------- | --------------------------------- |
| 🔒 private _(default)_ | you and members of your namespace |
| 🌐 public              | anyone, no login                  |

Names can be scoped to a team, too: a bare name is yours, an organisation
prefix targets that org, and membership is checked per request.

## Let Claude do it

Add the [annotations skill](https://github.com/dreamlake-ai/dreamlake-skills) and
skip the SDK — describe what you want, it makes the calls:

| You say                                                          | It does                                     |
| ---------------------------------------------------------------- | ------------------------------------------- |
| _"upload this clip with its hand skeletons and action segments"_ | creates the annotation, uploads the episode |
| _"add the 3D reconstruction to ep-001"_                          | fills in the missing layer                  |
| _"add a wrist camera to ep-001"_                                 | attaches the second view                    |
| _"make this annotation public"_                                  | flips visibility                            |

## Next steps

    The manual — every method, argument and data shape, with the code this page leaves out.

    Every layer's exact fields, including 3D reconstruction.

---

Source: https://docs.dreamlake.ai/ml-dash/get-started/authentication

# Authentication

  You log in once with the `ml-dash` CLI. The CLI saves a token on your
  machine, and both the CLI and the Python SDK read it from there. Local mode
  needs no login at all.

## Log in

Install the CLI first (see [Install](/ml-dash.md#cli)), then:

```bash
ml-dash login
```

The CLI prints a short code and a QR code, and opens your browser at the
approval page. Approve the request there. You never type a password into the
terminal. Once you approve, the CLI saves the token and tells you where it
put it, for example `Your authentication token has been stored (keychain).`

| Flag | Use |
|---|---|
| `--no-browser` | Print the code and URL, but don't open a browser. Use this on a remote machine and approve from any other device. |
| `--dash-url URL` | Log in to a server other than `https://api.dash.ml` |
| `--auth-url URL` | Use a different authorization server (default `https://auth.vuer.ai`) |

The code expires after 10 minutes. Check who you are logged in as, or log out:

```bash
ml-dash profile          # fetches your profile from the server
ml-dash profile --cached # reads the stored token only, no network
ml-dash logout           # clears the token from every place it could be stored
```

## Where the token lives

The CLI stores the token in the most secure place the machine offers:

| Machine | Where `ml-dash login` stores the token |
|---|---|
| macOS | The login keychain (service `ml-dash`) |
| Linux with `secret-tool` (a desktop session) | The Secret Service keyring (service `ml-dash`) |
| Windows, or Linux without `secret-tool` (servers, clusters, containers) | `~/.dash/tokens.encrypted`, with its key in `~/.dash/encryption.key` |

Set `ML_DASH_NO_KEYCHAIN=1` before `ml-dash login` to skip the keychain and
always use the encrypted file.

## Using the token from Python

The SDK loads the stored token when an experiment has a `dash_url`. You don't
pass any credentials in code:

```python
from ml_dash import Experiment

with Experiment(prefix="alice/project/run-1", dash_url="https://api.dash.ml").run as exp:
    exp.log("Authenticated automatically")
```

The SDK reads the same places the CLI writes. If `keyring` is installed, it
uses the OS keychain. Otherwise it uses `~/.dash/tokens.encrypted`. So match
the SDK install to where your login went:

- **Token in the keychain** (macOS, desktop Linux): install `pip install
  "ml-dash[auth]"`, which adds `keyring`. Without it, the SDK can't see the
  token.
- **Token in `~/.dash/tokens.encrypted`**: a plain `pip install ml-dash`
  reads it.

> **Warning:** Run `ml-dash profile` to confirm the CLI is logged in, then check that the SDK
> install matches the list above. A common mismatch: the token is in
> `~/.dash/tokens.encrypted`, but another package pulled `keyring` into the
> Python environment, so the SDK looks only in the keychain. Uninstall
> `keyring` from that environment, or log in again on a machine whose keychain
> the SDK can read.

## Servers and configuration

Both the CLI and the SDK default to `https://api.dash.ml`.

- **CLI:** `--dash-url` (alias `--api-url`) on any command, or `remote_url` in
  `~/.dash/config.json`.
- **SDK:** the `dash_url` argument. `dash_url=True` uses the `ML_DASH_API_URL`
  environment variable, or `https://api.dash.ml` if it isn't set.

For scripts and CI, the CLI also accepts a token written directly into
`~/.dash/config.json`. It takes precedence over the stored login:

```json
{
  "remote_url": "https://api.dash.ml",
  "api_key": "<token>"
}
```

The SDK does not read `api_key` from this file. It reads only the stored login
described above.

## How login works

`ml-dash login` uses the OAuth 2.0 Device Authorization Grant
([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)) against
`auth.vuer.ai`, then exchanges the result for an ML-Dash token:

```
ml-dash CLI                  auth.vuer.ai                   Browser
     |-- POST /api/device/start -->|                               |
     |   { device_secret_hash }    |                               |
     |<-- { user_code, verification_uri, expires_in: 600 }         |
     |  [prints code + QR, opens browser]                          |
     |                             |<-- user enters code, approves |
     |-- POST /api/device/poll --->|                               |
     |<-- 202 authorization_pending   (every 5 s)                  |
     |<-- 200 { access_token }     |                               |
     |                                                             |
     |-- POST /api/auth/exchange ──→ ML-Dash server                |
     |<-- { ML-Dash token }                                        |
  [stores the token]
```

- The poll is tied to a random per-machine secret, stored in
  `~/.dash/config.json`. Only its SHA-256 hash is sent to the server, so there
  is no `device_code` that could be intercepted.
- The token from `auth.vuer.ai` is exchanged at the ML-Dash server's
  `/api/auth/exchange` for the token the CLI stores and the SDK sends.

---

Source: https://docs.dreamlake.ai/sim-rollouts

{/* Figures come from the site-wide mdxComponents map (SimRolloutFigures) — no
    import needed. The page is figure-led: each section opens with a diagram,
    prose stays to captions, and every deep detail links out to Sources and
    the Dataset Viz docs. */}

# Sim rollouts

  A trained policy is a neural network — nothing to watch. What's worth seeing is the policy
  **acting**: the agent walking, reaching, flying. This guide turns one rollout into a single
  **MCAP** DreamLake plays natively — the mesh moving through the scene, every reward and joint a
  cursor-synced chart. No screen recording, no bespoke viewer.

Anything with a **body and a 3D pose** fits — robot, character, drone, hand.
DreamLake already ships the last two moves; this guide is mostly the first.

## Prerequisites

```bash
pip install foxglove-sdk trimesh          # write MCAP; export meshes to OBJ
curl -fsSL https://dl.dreamlake.ai/install.sh | bash   # the dreamlake CLI
dreamlake login                           # browser sign-in
```

## Generate the MCAP

Roll the policy out and log **three channels**, each a Foxglove well-known
schema DreamLake decodes with zero config.

```python
import foxglove
from foxglove.messages import FrameTransforms, SceneUpdate

w = foxglove.open_mcap("rollout.mcap")
obs, _ = env.reset()
for t in range(STEPS):
    obs, reward, done, _ = env.step(policy(obs))
    ns = int(t * step_dt * 1e9)
    foxglove.log("/tf", FrameTransforms(transforms=body_transforms(env)), log_time=ns)
    if t == 0:
        foxglove.log("/robot", SceneUpdate(entities=robot_meshes(env)), log_time=ns)  # once
    foxglove.log("/metrics", {"reward": float(reward), **joint_angles(env)}, log_time=ns)
w.close()
```

The [skill](#let-claude-do-it) ships a runnable template that fills the two
helpers above and gets the easy-to-miss details right — quaternion order
(`wxyz` → `xyzw`) and exporting meshes in a format the viewer reads today
(OBJ or GLB).

## Connect a source

The `.mcap` is data like any other — DreamLake reads it in place, never
imports. Put it in storage you already reach, then link it on the namespace's
**Sources** page ([full rules](/sources.md)):

```bash
hf upload your-name/your-repo ./rollout.mcap --repo-type dataset   # or S3 / Dropbox
```

## Watch it

A `.dreamrc` beside the file names which channel feeds which view — embedded
mesh, a motion trail, the metric charts:

```yaml
version: 1
dataset:
  format: mcap
  episodes: auto
views:
  - view: recon3d
    up: z
    tracks: [{ field: "/tf::*", as: transform3d }]
    geometry: ["/robot::*"]              # the embedded OBJ meshes
    trail: { ahead: 1, behind: 0.5 }
  - view: timeline
  - view: lineChart
    title: "/metrics"
    series: ["/metrics"]
```

Name it `.dreamrc` for a folder, or `<file>.mcap.dreamrc` for one mcap when the
folder holds several. Keys, options, and the validate loop: the
[Dataset Viz docs](https://viz.dreamlake.ai/dataset-viz).

## Bring your own robot

Two ways to put a body on the skeleton — pick one.

Embed the mesh for a self-contained file, or — if DreamLake's robot registry
(`live9080/dreamlake-robots`) has your robot and its link names match your
`/tf` frames — emit a `/tf`-only MCAP and let the `.dreamrc` load the URDF.

## Let Claude do it

The [sim-to-mcap skill](https://github.com/dreamlake-ai/dreamlake-skills)
runs this end to end and hands off to the source and dataset-viz skills:

| You say | It does |
| --- | --- |
| _"visualize my mjlab G1 walking policy"_ | rolls out the checkpoint, writes the MCAP |
| _"the robot shows as bare axes"_ | re-exports the mesh in a format the viewer reads, binds `/robot::*` |
| _"use the preset G1 model instead"_ | switches to a `/tf`-only file + URDF |

## Next steps

    Link a bucket or HF repo as a source — providers, layout, verification.

    Every `.dreamrc` key and view option, next to a live playground.

    The runnable template and the write → upload → render hand-off.

---

Source: https://docs.dreamlake.ai/video

# Video SDK

  Load, slice, and batch video data in Python with NumPy-style indexing. Every
  operation is lazy — nothing is decoded until you actually access pixels, so
  slicing an hour of footage costs nothing.

> **Note:** **Before you begin** — `pip install dreamlake` for this Python SDK. The
>   `dreamlake` CLI is a separate native binary
>   ([install it here](/index.md#install)); use it to authenticate with
>   `dreamlake login`, which the SDK then reuses. Video ids come from
>   `dreamlake list` or the dashboard.

## Load

```python
import dreamlake as dl

video = dl.load_video("v-BV1bW411n7fY9x01")
print(video.fps, video.duration, video.width, video.height)
```

## Slice

`float` = time (seconds), `int` = frame number. Returns a lazy `Video`.

```python
clip = video[10.0:20.0]       # 10s clip
frame = video[42]              # frame 42
sub = clip[2.0:5.0]           # sub-slice → Video(st=12.0, et=15.0)
```

## Access Frames

```python
video[0].image                 # PIL Image
video[0].numpy()               # (H, W, 3)
clip.numpy()                   # (N, H, W, 3)
clip.tensor()                  # (N, C, H, W) torch tensor
video.thumbnail                # middle frame
```

## Chunk & Batch

```python
chunks = video[0.0:2.0].chunk(0.200)   # VideoArray of 10 × 200ms
chunks[:, 0].numpy()                     # first frame of each → (10, H, W, 3)
chunks[:, 0].tensor()                    # feed to model
```

## TextTrack

Buffer time-aligned text entries, flush to server:

```python
track = dl.text_track(prefix="/run-042/captions", project="robotics@alice")
track.add("Robot picks up cup", source=clip)
track.flush()
```

## VectorIndex

Store and search embeddings:

```python
index = dl.vec_index("my-experiment")
index.add(vector=enc(clip[0]), caption="robot arm", source=clip)
results = index.search("robot picking up cup", limit=10)
```

## Prefix Context

```python
with dl.Prefix(project="robotics@alice", prefix="/2026/04/run-042"):
    dl.upload("./video.mp4", path="camera/front")
    track = dl.text_track(path="captions/llava")
```

## Next steps

    Vectorize the clips you just sliced and query them with natural language.

    Upload and organize the episodes the SDK loads from.

---

Source: https://docs.dreamlake.ai/search

# Semantic Search

  Search video content with natural language — "robot picking up cup" returns
  the exact 2-second clips, with playback URLs and scores. Videos are split
  into HLS chunks, embedded with CLIP, and indexed in Qdrant.

## Pipeline

```
Upload video → Lambda splits into 2s HLS chunks
    → dreamlake vectorize (CLIP + LLaVA per chunk)
    → Qdrant index
    → Query: text → CLIP embed → nearest neighbor
```

## Vectorize

```bash
dreamlake vectorize --episode robotics@alice:run-042
dreamlake vectorize --bindr "front-camera" --project robotics@alice
dreamlake vectorize --dataset "training-v1" --project robotics@alice
```

Add `--zaku-url http://host:9000` for distributed processing via Zaku task queue.

Per chunk: CLIP ViT-L/14 (768d image embedding) + LLaVA 13B (caption → CLIP text embedding).

## Search

```
GET /namespaces/:ns/projects/:project/semantic-search?q=robot+picking+up+cup
```

| Param | Description |
|-------|-------------|
| `q` | Natural language query |
| `episode` | Scope to episode |
| `bindr` | Scope to bindr |
| `limit` | Max results (default 10) |
| `using` | `image` (default) or `caption` |

Returns matched 2s clips with playback URLs and scores.

## Performance

| Step | Time |
|------|------|
| Vectorize per chunk | ~14.5s (CLIP + LLaVA) |
| Search query | ~50ms |
| Storage per chunk | ~6KB |
| 1 hour video | 1,800 points, ~11MB in Qdrant |

## Next steps

    Load the matched clips in Python and turn them into tensors.

    The search endpoints, plus everything else the server exposes.

---

Source: https://docs.dreamlake.ai/workspaces

# Profiles and workspaces

## One namespace, two layouts

`/<namespace>/profile?tab=<resource-type>` and
`/<namespace>/<resource-type>` show the same resource catalog with the same
permissions. Profile has an identity and avatar rail; the workspace has a resource
sidebar. Projects is the first resource after Overview and the default workspace
destination. Existing namespace-root links continue to open Profile.

Your own profile and profiles of organizations you belong to expose the resources
and actions available to you. Creation, editing, deletion and organization
administration remain subject to the existing resource and role permissions;
being able to browse a catalog does not grant permission to modify every item.

Signed-out visitors and signed-in visitors browsing someone else's namespace see
public catalogs only. Projects, Notes, Annotations, Envs and Artifacts support
public browsing in either layout. Private catalogs such as Sources, Connections
and Vault are not advertised to visitors. A directly shared resource can still be
opened according to its existing server permissions; a share does not turn its
owner's private catalog into a public list.

Public views omit private counts, trash, Shared with me, organization updates and
creation/editing controls. All/Public filters are omitted when every result is
public; meaningful filters such as artifact kind remain. The member views retain
useful catalog filters and permitted management actions. List/grid, search,
sorting and resource cards are shared across the two layouts.

Overview keeps recent projects and annotations and its list/grid preference.
It does not fetch every resource catalog merely to display counts. The global
**Cmd+Shift+D** (or **Ctrl+Shift+D**) developer switch controls discovery of
experimental features, not access rights. Turning it on never grants access to
private resources.

## Resource owner and signed-in account

The sidebar separates your signed-in account, global navigation and the namespace
you are browsing. Above the DreamLake brand, a plain username and chevron open your
account menu; the sidebar collapse control shares that row. Dashboard opens your
own recent work from any namespace. Gallery opens the same public gallery for
everyone in a new browser tab.

In your own personal namespace, a plain **Workspace** heading folds and unfolds
the resource navigation, just like Bindrs. It scrolls with the list. Other
namespaces instead show an avatar, display name and **Workspace @namespace**
heading. This heading stays at the top of the scrolling sidebar; clicking the
avatar/name area folds its resource links. The plus/minus indicator appears on
hover. The separate **@namespace** link opens that owner's Profile in the current
tab. A collapsed sidebar shows only the owner avatar and resource icons, and
restores the previous resource-fold state when expanded. Folding Workspace does
not hide Pinned or Bindrs. When available, **+New** sits above the Workspace group.

Resource links and permitted Settings, Members and Teams entries belong to the
URL's namespace. Your signed-in identity above the brand does not turn into an
organization when you browse one.

The account menu lists your personal namespace and organizations, then **My
Profile**, **My Dashboard**, **New organization** and **Sign out**. Both personal
destinations remain available on every signed-in surface: My Profile opens your
own profile, and My Dashboard opens `/dashboard`, in the current browser tab.
Profile has no separate Enter workspace button or Dashboard shortcut beside the
account menu.

Choosing a namespace normally opens its corresponding resource list. From a
detail it returns to the list without carrying the previous resource ID;
unavailable destinations fall back to Projects. From Profile it retains that
layout and an available tab. From the personal Dashboard, choosing an organization
opens its Projects list.

Browser history and refresh follow the URL's namespace. There is no remembered
workspace overriding the owner shown in navigation. Membership loss removes
member-only navigation and content without changing the owner of the page.

Signed-out visitors see a brief sign-in invitation between the brand and Gallery,
with a primary **Sign in** button and a **New to DreamLake? Sign up** link. Gallery
and public workspace navigation remain available, while Dashboard is hidden.
A collapsed sidebar keeps a sign-in icon accessible. While authentication is
being checked, a neutral placeholder reserves the account area instead of
flashing sign-in buttons. Profile retains its landing-style authentication
buttons. Explicit sign-in return addresses preserve the pathname, query and fragment.

The footer pairs a small **Theme** label with the light/system/dark segmented
control. The label is hidden and the control turns vertical when the sidebar is
collapsed. Profile keeps its existing horizontal theme control.

Profile owners can edit their identity through the existing pencil/avatar dialogs;
organization identity editing remains restricted to its owners. Organization
profiles retain member avatars and directory views. Public directories exclude
secret teams and private member fields; governance remains permission-controlled.

## Your Dashboard

`/dashboard` is the signed-in user's personal home, with the application sidebar.
It combines recent projects and annotations in your own namespace with your
recently visited projects across namespaces. Visit history stays private to your
account and each project links to its real owner. Other people and organizations
are browsed through Profile and their resource lists, not public Dashboards.

The global Dashboard entry stays reachable while browsing someone else's
namespace. On Dashboard, the Workspace section offers your own namespace's
resource shortcuts. Profile exposes My Dashboard in the account menu; Gallery retains its signed-in
Dashboard shortcut.

Signing in without an explicit return destination opens `/dashboard`; a preserved
resource destination still takes priority. Legacy `/<namespace>/dashboard` links
redirect to `/dashboard`, which requires authentication and always resolves the
signed-in user's own data rather than the namespace in the old address.

## Resource lists and shared links

Public resource lists and public Projects, Annotations, Envs, Artifacts and Notes
details can be opened without signing in. Private-only pages require the
appropriate identity and permissions. The sidebar remains available while moving
between application lists and details, with the current owner's permitted links.
Loading or an error in the resource does not replace the navigation.

Project files inherit their containing project's visibility; separately filed
Notes, Artifacts and Annotations retain their own permissions. A public project
does not publish private resources filed inside it or their private counts.
An Env or Artifact share token can authorize an anonymous read. A private Note
share link requires sign-in because it creates a grant for that person. Invalid
or revoked links retain the server's not-found or access-denied behavior.

The detail header returns signed-out readers to
`/<namespace>/profile?tab=<resource-type>` and signed-in readers to
`/<namespace>/<resource-type>`. Embedded resources return to their containing
project first. Browser Back continues to follow actual history. There is no
extra sign-in strip above the detail.

The namespace list APIs for Notes, Projects and Annotations accept requests
without an Authorization header. Anonymous users and nonmembers receive only
live public rows; authenticated namespace members retain their existing access.
Pagination totals use the same visibility filter. Supplied invalid or expired
credentials return 401. Anonymous project summaries omit internal bindr/dataset
counts. Anonymous Notes searches do not activate or flush collaborative rooms.
Creating, modifying, sharing and deleting remain authenticated operations.

## Organization updates

Your own Envs and Notes catalogs include a separate **Recent in your
organizations** section. Each organization shows up to six recent resources and
a **View all** link. Personal results and Shared with me remain separate.
Visitors and organization catalogs do not show this personal aggregation.

Organizations load in batches of six, with at most three simultaneous catalog
requests. A failed organization can be retried without reloading your personal
resources. Notes requests are bounded by the existing API; Envs currently reads
the organization's full catalog and displays the six most recent entries.

---

Source: https://docs.dreamlake.ai/artifacts

{/* FigWhat/FigPush/FigVersions/FigTrash come from the site-wide
    mdxComponents map in site.config.ts — no import needed. */}

# Artifacts

  An artifact is one renderable file — an HTML page, a React component, a
  Markdown doc, an SVG, a Mermaid diagram, or a code snippet — that you push
  from the terminal and view as a live page in the dashboard.

## Preview spacing

Artifact previews start with zero page margin and padding. This applies to the
shared renderer and the default HTML document inside its isolated iframe.
HTML and React authors can add spacing explicitly within their content; the
preview does not add an outer gutter. To show an image edge to edge, remove
padding from its authored container and use `display: block` on the image.
Fit preserves the image's aspect ratio, so a differently shaped viewport can
still leave unused space; zero padding does not crop or stretch the image.

## Reference an artifact from a Note (development preview)

```markdown
:artifact[geyang/pitch-deck]
```

In the development UI, click the `#…` ID badge in the artifact header to copy
the complete `:artifact[namespace/id]` reference. The badge displays only the last
six ID characters; the copied reference includes the owner namespace and full ID.
This copy action does not create a share link or change permissions.

Use the owner namespace and stable artifact ID returned by the artifact CLI.
Brackets hold primary content; optional named attributes belong in braces, following
the [remark-directive extension](https://github.com/remarkjs/remark-directive), not core CommonMark.
DreamLake defines the resource semantics. Saved `:artifact{namespace="geyang" id="pitch-deck"}`
and `#artifact:geyang/pitch-deck` also work in the local development
UI. The tag resolves the title and opens the artifact panel to the right of the Note without changing
permissions or visibility. Static API HTML preserves the reference as an unresolved,
atomic source span; it does not embed artifact content or share-token URLs.
Production deployment is not yet verified. See [Notes reference syntax](/notes/#artifact-references-development-preview).

### Slide and section reference syntax

`:artifact[geyang/pitch-deck#slide-3]` retains an existing target ID; `#/3` is
valid only if the artifact defines that route. Clicking sends the fragment to
the reusable panel through `dreamlake.route.hash`, retaining its running iframe. See [fragment syntax](/notes/#fragment-reference-syntax-development-preview).

## Browsing in the app

`/<namespace>/profile?tab=artifacts` and `/<namespace>/artifacts` reuse the same
Artifacts catalog. Your own namespace and organizations you belong to show
resources and actions allowed by your permissions. Signed-out visitors and
signed-in visitors to other namespaces see public resources only, without
creation or modification controls. Profile uses an avatar rail; the application
uses resource navigation for the namespace in the URL.

Shared with me, trash and modification controls remain restricted to permitted member views. Public artifacts can be read without sign-in. Private share links require the recipient to sign in.

The application sidebar shows the resource owner's avatar and links, including
for anonymous public readers. Your signed-in identity and personal/organization
switcher are separate from that owner. See [Profiles and workspaces](/workspaces.md).

The detail header returns anonymous readers to `/<namespace>/profile?tab=artifacts`
and signed-in readers to `/<namespace>/artifacts`. Details opened inside a project
retain their return-to-project action. There is no extra sign-in navigation bar.

## Push one

```bash
dreamlake artifact push ./report.html
```

That's it. The CLI prints an **open link** — click it to see your artifact
rendered at `dreamlake.ai/<you>/artifacts`.

| Kind | File |
|------|------|
| `html` | Any self-contained page |
| `react` | A component file that defines `App` |
| `markdown` | `.md` docs |
| `svg` / `mermaid` | Diagrams |
| `code` | Anything else — rendered with syntax highlighting |

## Version it

Push the same `--id` again and you get a new version — nothing is overwritten,
and the viewer has a version picker.

## Share it

Artifacts are **private** by default. Two ways to open them up:

| | Command | Who can view |
|---|---------|--------------|
| 🔒 private | *(default)* | Only you and namespace members |
| 🔗 share link | `push --share` | Signed-in recipients with a valid share token |
| 🌐 public | `push --visibility public` | Anyone, no login |

You can also toggle visibility and copy links from the artifact's page — the
Share button does the same thing.

## Delete it (safely)

`delete` is a soft delete: the artifact moves to your gallery's **trash** tab
and any share link stops working. Restore it any time — or erase it forever.

```bash
dreamlake artifact delete report              # → Trash (restorable)
dreamlake artifact restore report             # bring it back
dreamlake artifact delete report --permanent  # erase forever — no undo
```

## Let Claude do it

Add the [artifacts skills](https://github.com/dreamlake-ai/dreamlake-skills) and
ask Claude to *"push this dashboard as a dreamlake artifact and share it"*:

```bash
git clone https://github.com/dreamlake-ai/dreamlake-skills.git ~/dreamlake-skills
mkdir -p ~/.claude/skills
ln -s ~/dreamlake-skills/dreamlake-artifacts ~/.claude/skills/
ln -s ~/dreamlake-skills/dreamlake-artifact-authoring ~/.claude/skills/
```

Install both skills: one publishes, the other prepares content for the offline
rendering frame. To update both, run `git -C ~/dreamlake-skills pull --ff-only`.
Use a project's `.claude/skills/` directory for project scope. If a skill already
exists, inspect and preserve local edits before replacing it with a symlink.

## Next steps

    Every flag — ids, kinds, namespaces, visibility.

    The REST endpoints behind push, share, and trash.

## Artifact paths and local routing

The artifact render iframe uses a meaningful resource path and ordinary local
query/fragment state:

```text
https://artifacts.dreamlake.ai/geyang/pitch-deck?slide=3&view=chart#overview
```

There is no internal instance ID in its URL. The path identifies the resource;
it is **not authorization**. The DreamLake viewer performs the authorized content
read, then sends the content to this isolated frame through a validated handshake.
The frame never receives the viewer's authentication or share token.

The corresponding shareable **viewer** link is:

```text
https://dreamlake.ai/geyang/artifacts/pitch-deck?art.slide=3&art.view=chart#overview
```

Only this outer viewer query uses `art.` to distinguish artifact state from
host parameters such as `share`. The fragment is ordinary `#overview` on both
URLs. Earlier development links using `#art=overview` are still read, but new
links use the plain fragment. The `art.` prefix never reaches the frame query.

Opening the frame address directly shows an explicit embed-only page with a
link to the authorized DreamLake viewer. It does not fetch private content,
invent a public read endpoint, or copy capability query fields into that link.
Public/private/share-link rules continue to be enforced by the viewer and API.
Ad-hoc Note/file previews have no catalog identity and use `/_preview`; catalog
thumbnails and artifact detail viewers use the actual namespace/artifact path.

Inside HTML and React artifacts this becomes `dreamlake.route.search ===
'?slide=3&view=chart'` and `dreamlake.route.hash === '#overview'`. Read strings
with `new URLSearchParams(dreamlake.route.search)`. Values can contain Unicode,
spaces, JSON text, or other strings; use `URLSearchParams` to encode queries
and `encodeURIComponent` for a fragment when building a URL. Repeated keys and
empty values are supported. Parse numbers/JSON and validate their meaning in
your artifact. Route data is public, user-controlled state, never a secret.

```html
<div id="slide"></div>
<button id="next">Next slide</button>
<script>
  const route = window.dreamlake.route;
  function render() {
    const params = new URLSearchParams(route.search);
    document.getElementById('slide').textContent = params.get('slide') || '1';
  }
  const unsubscribe = route.subscribe(render);
  render();
  document.getElementById('next').onclick = async () => {
    const params = new URLSearchParams(route.search);
    params.set('slide', String((Number(params.get('slide')) || 1) + 1));
    await route.navigate({ search: params.toString(), hash: '#overview' });
  };
</script>
```

`navigate({search?, hash?}, {replace?: boolean})` merges omitted fields with
the current route and returns a Promise. Set a field to `''` to clear it.
It pushes browser history by default; `{replace: true}` replaces the current
entry. `subscribe(callback)` returns an unsubscribe function; callbacks read
the new snapshot using `getSnapshot()` or the `search`/`hash` getters. React
artifacts can use `React.useSyncExternalStore(route.subscribe, route.getSnapshot)`.
Use an effect cleanup for other subscriptions.

Back/forward and incoming route changes update the running artifact without
reloading its iframe or resetting forms, React state, or WebGL scenes. The
outer render frame's `location.pathname`, `location.search`, and `location.hash`
reflect the clean artifact address. Use `dreamlake.route` for navigation without
reloads and for a common API across HTML and React. HTML still runs inside an
opaque, sandboxed `about:srcdoc` child; its own `location` is not the outer frame
URL. The route API supplies the same values without weakening that sandbox.

The host owns browser history; the frame mirrors route changes with
`replaceState`, preventing duplicate history entries. Reloading the iframe
performs a fresh handshake and reloads authorized content for the same path.
Directly assigning `location.search` in React reloads the frame; prefer
`route.navigate` to preserve component state. Native React fragment changes
mirror to the host using replace semantics; native HTML anchors stay in the
opaque child. Use the route API when an HTML route should survive sharing.

Only the standalone artifact detail page binds this API to browser history.
Gallery thumbnails, file/Note previews, and project-embedded viewers do not
inherit the surrounding page's query/fragment. Interactive previews can use
the route API locally. The detail Share/Copy link includes the current route.
Public links contain no share token; private sharing adds only the intended
read-capability token. Updating a route preserves host authorization in the
address bar but never exposes it to artifact code.

Parameter names (after removing `art.`) must match
`[A-Za-z][A-Za-z0-9_.-]{0,63}`. Reserved names, case-insensitively, are `share`,
`token`, `auth`, `authorization`, `cookie`, `project`, `namespace`, `instanceId`,
`__proto__`, `prototype`, `constructor`, and `dreamlake`, including names
followed by `.`, `_`, or `-`. Search plus hash is limited to 8192 characters.
Invalid API navigation rejects; invalid link parameters are ignored and an
oversized link route becomes empty. Host parameters such as `share`, auth,
and project fields are never blanket-forwarded. A parameter is ordinary data,
not permission to query private resources or escape the sandbox. The existing
query/download bridge and its authorization/confirmation rules still apply.

For a deep link from a Note, use an ordinary Markdown link with this URL, or
`:artifact[namespace/id#slide-3]` to open its hash route in a right-hand panel.
Do not put a share token inside rich-reference attributes.

This contract requires the companion frame and app changes. Release the frame
first, including its SPA fallback (`/* /index.html 200`), then the app. The new
frame accepts old root `/#af...` handshakes for existing hosts; only legacy root
URLs interpret the fragment as protocol state. Modern paths use a per-document
boot challenge and host instance identity exchanged exclusively in messages,
checked together with the source window and allowed/pinned parent origin.
Repeated readiness for the same document does not reinitialize the artifact.
After reload, messages from the previous document cannot complete new requests.

The new host can answer an old frame's ready message if that renderer loads,
but older frame deployments may lack the clean-path fallback and route API.
Do not deploy the host before the new frame is verified. Source validation
does not mean this feature is deployed. No server API or CLI change is required.

## Artifact panels in Notes (development preview)

Use `:artifact[namespace/id]` to open the shared artifact viewer beside a Note,
including Notes within a project. Append the artifact's own hash route to select
a slide: `:artifact[geyang/landing-pages#slide-3]`. Clicking a second reference to
the same artifact selects its existing panel and applies the new fragment. The
artifact receives it through `dreamlake.route.hash`; its own code defines what
that fragment means. The surrounding Note/project URL stays unchanged.

This is the same viewer used by standalone artifact pages and project items,
including version selection, preview zoom, and permission-checked management
controls. Closing the panel leaves the Note open. Tags grant no access, and
never contain a share capability. Full artifact links remain available with
Control/Command-click. These panel changes require the companion UI release;
publishing these docs or uploading an artifact alone does not deploy them.

## Manage an existing link

CLI 0.32.4 adds `artifact share get/create/revoke` and `artifact visibility`
without another upload. Inspect with `get` before changing access and after the
requested change. Follow the [complete CLI sharing recipe](https://cli.dreamlake.ai/artifacts#manage-existing-share-links).

Omitting `--share` on a later push preserves the existing token; it does not
stop sharing. Use `dreamlake artifact share revoke <id>` to clear the token.
Revocation blocks link-derived access while sharing is disabled; recorded
recipients may regain access if sharing is enabled again. Public visibility
and namespace membership are independent of the link.

---

Source: https://docs.dreamlake.ai/hosted-pages

# Generate & Hosted Pages

  A hosted page is a React app written by an AI agent and kept alive in its own
  container. There is no build and no deploy: the page runs a dev server, so an
  edit made from chat appears in the open browser within seconds — at the same
  URL, forever.

## Quick experience

The whole loop from the command line — no build, no deploy, one URL throughout.

```bash
# 1. Install and sign in
curl -fsSL https://dl.dreamlake.ai/install.sh | sh
dreamlake login --env prod

# 2. Generate — the URL is printed within seconds
dreamlake page generate \
  --description "Three stat cards: Total, Reviewed, Pending."
#   https://host.dreamlake.ai/page/eba91469e21e/

# 3. Edit — applied over HMR, same URL
dreamlake page edit --workspace-id eba91469e21e \
  --description "Switch to a dark theme with a blue accent."

# 4. Inspect and remove
dreamlake page status --workspace-id eba91469e21e
dreamlake page delete --workspace-id eba91469e21e
```

> **Note:** Run step 3 with the page open in another window: nothing reloads, nothing
>   rebuilds, and the URL never changes.

## Generating a page

The agent writes an ordinary Vite React project. A container starts, runs `pnpm dev`, and the page is reachable. Nothing is compiled, uploaded, or published.

## Serving

Each page has its own container and its own dev server. The router maps the URL path to the right one.

## Editing a live page

This is the part that replaces "rebuild and redeploy".

The agent edits the source code **inside** the container. Vite notices, and pushes just the changed module to every browser that has the page open. A page being watched on a wall display updates without anyone reloading it.

### When an edit breaks the page

The agent can read the dev server's compile output and the browser's runtime errors, so it sees its own mistakes and fixes them before reporting success.

## Idle pages

A page nobody is looking at costs nothing. It stops after 30 minutes and comes back on the next visit.

## Security model

### Isolation

Edit instructions come from end users, in plain language. So the agent never touches the host.

A malicious or simply confused instruction can corrupt one page's source code — which the same mechanism can then repair. It cannot reach the machine, the other pages, or anything sensitive.

### Kernel isolation

Containers run under **gVisor** (`runsc`) rather than the normal runtime.

gVisor implements Linux itself, in user space. The container's syscalls are answered by that kernel — the host kernel sits behind it and is never called directly. The container even reports its own kernel version, `4.19.0-gvisor`.

The usual way out of a container is a host-kernel bug. Here the host kernel is not the thing on the other side of the syscall boundary, so that class of escape has nothing to aim at.

### Shell / data separation

Two modes. A page built from a plain description has no business data to
protect. A page wired to real records does — and even then, its source code contains
**no business data and no credentials**.

Only two things are written into the page — the API base URL and the annotation result ID. Everything else is fetched at runtime. Access control lives in the API layer, not in the page, so a leaked URL exposes an empty shell.

### Not embeddable by third parties

When the page loads, it asks its parent window for the current user's token, then calls the DreamLake API with it. The token never appears in the page's source code.

**If no parent responds** — the URL is opened directly, or embedded in someone else's site — the page shows a blank auth-required screen. There is nothing to extract without a live token from a trusted parent.

| Layer | Mechanism | Description |
|---|---|---|
| Outer | frame-ancestors CSP | A response header restricts embedding to `*.dreamlake.ai` — the browser rejects third-party embeds before any JavaScript runs |
| Middle | Origin allowlist | The console's token responder only replies to requests from trusted origins, so a page embedded elsewhere never receives a token |
| Inner | API JWT auth | Every API call carries the user's JWT; the server verifies it and enforces namespace access control — the same rules as everywhere else in DreamLake |

---

Source: https://docs.dreamlake.ai/notes

# Notes

Read [Markdown authoring](/notes/markdown/), [Embeds and query arguments](/notes/embeds/),
[Panels](/notes/panels/), and [Linked note items](/notes/linked-items/) for focused guides.
This page retains the complete CLI/API reference and existing section links.

  A note is a collaborative Markdown document. This is how a script — or a
  coding agent working through bash — edits one while people have it open.

See [Panels and agent control](/notes/panels.md) for artifact previews, pinned tabs,
and programmable native layouts.

In live preview, an opening H1 with content below it is positioned
above the viewport once, before interaction. Scrolling back to the title keeps it
visible; typing, blur, and idle time do not automatically hide it again. Raw
Markdown, title-only notes, and explicit search or section navigation retain
their existing behavior. Formatting remains enabled while editing. Vim visual
selections remain visible in both rich and raw views. Each connected browser session shares its cursor and selection, including other sessions of the same account. Clearing a selection updates it immediately; leaving editor focus removes its shared cursor and selection. Hidden tabs leave visible presence. Visible sessions renew presence every 30 seconds; peers expire after 90 seconds without renewal. Cursor labels size to their names, capped at 20 characters of display width with ellipsis. Remote text updates preserve the
visible text position in the note pane; a new scroll gesture, keystroke, or
selection takes precedence over a pending viewport correction.

Use a collaborator avatar to navigate to its current cursor when the location is
available. A cursor at the beginning of the note shows a popup saying
**Cursor is at the start of the note** and leaves your view in place. An avatar
without a current cursor shows a popup saying **No location available**. Other
available cursor locations support the existing jump action.

History timeline previews return to the current working draft when the pointer
leaves the timeline. An explicitly placed edit marker or selected change range
keeps its historical view open; clicking a version label alone does not pin it.

## Experimental native rich Markdown editor

In **Settings → editor experiments**, enable **Native Markdown editor
(experimental)** to switch the main Notes editor to the native rich Markdown
editor. The setting is off by default, applies only in this browser, and takes
effect immediately. Other browsers and teammates keep their own choice; disable
it to return to the CodeMirror editor.

The native editor keeps canonical Markdown in the same collaborative RTC
document. It supports rich Markdown presentation, formatting and insertion
commands, comments and suggestions, references, folding and section navigation,
Vim mode, audio controls, and collaborator cursors and selections. Notes keep
their existing save, sync, version history, and recovery controls. Switching
between rich presentation and raw Markdown does not change the note source.

In rich presentation, native headings align with the surrounding prose: the
heading marker and its separator whitespace do not add a visual indent. Paragraphs
and lists use consistent spacing, and blank lines retain a visible editing position.
These presentation rules preserve the original Markdown, including heading spaces
and line breaks; raw Markdown keeps the source visible.

### Stable prefixes and structural Backspace

The native rich editor keeps heading (`#`), list (`-`, `1.`),
and quote (`>`) prefixes in a fixed left gutter. Activating a line keeps its body
text in the same position and preserves its wrapping. Nested lists keep a stable
indent at each level, and task items keep a stable checkbox slot.

With a collapsed caret at the start of visible text, **Backspace** converts an
`#`-style (ATX) heading to a paragraph; outdents a nested list or task item one level together
with its subtree; converts a root list or task item to a paragraph; or removes
one quote level. Within text or at a soft wrap, Backspace performs ordinary
character deletion. **Undo** restores the structural edit as one action. Raw
Markdown mode keeps literal deletion behavior. These changes apply only to the
native experiment. Underlined (Setext) headings have no leading marker and
retain ordinary deletion behavior.

This editor remains experimental, and CodeMirror remains the default. The
browser preference does not change the CLI, API, note format, or permissions.

Use the DreamLake CLI for supported operations. Use Python or TypeScript APIs only when a required operation is unavailable through the CLI or the task explicitly requires SDK integration.

{/* <!-- skill-entrypoint:start --> */}

## Read Notes directly

**For normal reads, run the bare command and inspect its output directly:**

```bash
# Set NOTE_ID to the note ID, slug, or exact title you want to read.
dreamlake notes read "$NOTE_ID"
```

Do not add `--json` or `--view` for ordinary human or agent reads. The default
output includes canonical source, a revision, and a content hash. Retain the
revision and hash with the source when preparing safe edits; agent convenience
is not a reason to switch to JSON.

Use JSON only for an explicitly requested structured integration. The scripted
concurrency examples below demonstrate that compatibility path; they are not
the default reading procedure. Read normal collaboration and selection receipts
directly too.

{/* <!-- skill-entrypoint:end --> */}

## Public catalog reads

`GET /namespaces/:slug/notes` accepts requests without an Authorization header.
Anonymous callers and authenticated nonmembers receive only live public notes;
namespace members retain their existing catalog access. Pagination totals use
the same visibility filter as the rows. A supplied invalid or expired token
returns 401 rather than silently falling back to anonymous access. Anonymous
searches do not activate or flush collaborative rooms. Creating, editing and
sharing notes still require authentication and their existing permissions.

## Browsing in the app

`/<namespace>/profile?tab=notes` and `/<namespace>/notes` reuse the same
Notes catalog. Your own namespace and organizations you belong to show
resources and actions allowed by your permissions. Signed-out visitors and
signed-in visitors to other namespaces see public resources only, without
creation or modification controls. Profile uses an avatar rail; the application
uses resource navigation for the namespace in the URL.

Your own Notes catalog retains Shared with me and recent organization notes. Private Note share links require sign-in under the server's per-person grant rules.

The application sidebar shows the resource owner's avatar and links, including
for anonymous public readers. Your signed-in identity and personal/organization
switcher are separate from that owner. See [Profiles and workspaces](/workspaces.md).

The detail header returns anonymous readers to `/<namespace>/profile?tab=notes`
and signed-in readers to `/<namespace>/notes`. Details opened inside a project
retain their return-to-project action. There is no extra sign-in navigation bar.

### Project and bindr associations

Adding a project or bindr from a note changes membership while keeping the
current note, URL, search and panes open. Choose a destination project inside
the association picker. Bindrs belong to that project; identical bindr names in
different projects are separate destinations. A bindr association uses the
existing mounted note node, not a new copy or arbitrary filesystem placement.

Pending operations disable duplicate submissions. A failed bindr addition may
leave a successfully added project association; retry the bindr addition after
reviewing the inline status. Removing an association uses the same context
preservation behavior and retains the last-project guard. Use the separate
**Open project** or **Open bindr** links when you want to navigate.

### Matching passages

Searching the Notes catalog shows up to two distinct matching passages beneath
each result title, with matching words highlighted. Hover or focus a passage to
open a line-based popover, or use **Preview matches** from the keyboard. The
popover shows multiple matching paragraphs with their line breaks and all query
highlights. Repeated excerpts appear once with an occurrence count; expand them
to choose the exact section and occurrence. Selecting a
passage opens the note in the existing pane and selects the matching occurrence
when its current source still agrees with the result. Identical wording at
different source positions remains distinct. A changed source reports **Match
changed** and asks you to choose a current occurrence instead of using stale
offsets. Title-only matches open the note normally.

The current catalog query and list scroll survive opening a passage. Source-only
matches that cannot be mapped safely to rendered Markdown remain visible in the
explicit source excerpt; the interface does not guess a rendered position.

### Resource subviews

Project file and folder details use native draggable sibling view tabs. Files
offer **Preview** and **Details**; folders offer their available **Files**,
**README**, **Visualize** and **Episodes** views. Each tab identifies its resource
and subview. In the project view, selecting another resource reuses the existing
resource tab slots instead of accumulating README/Files pairs for visited folders.
Open note tabs remain in place. Drag a tab to an edge to compare views side by side, or into a panel's
center to group it. Closing a subview leaves its siblings open; **Views** reopens
closed views. Tab switches retain mounted view state. Existing source-browser
URL-owned view controls keep their navigation behavior. ML-Dash run inspectors
use the same native tabs for **Params** and **Log**, while detail pages keep
their existing separate log panel.

## Install

**CLI**

```bash
curl -fsSL https://dl.dreamlake.ai/install.sh | bash
dreamlake login
```

**Python**

```bash
pip install dreamlake
dreamlake login
```

Both read the same saved login. `pip install dreamlake` installs the Python
SDK; install the standalone CLI using the CLI tab before running
`dreamlake login`. The Python package is not the supported CLI installer.

## Collaboration and sync

People can edit the same note simultaneously. Edits merge through the existing
CRDT; checking sync does not lock the note or wait for other editors to stop.
The status beside the note title describes this tab:

| Status | Meaning |
|---|---|
| **Synced** | This tab matched the server revision and text checksum. |
| **Syncing** | Changes or verification are still in progress. |
| **Out of sync** | Sending is paused; inspect the recovery dropdown. |

A connected socket alone does not prove that text matches. The browser requests
a checksum calculated by the RTC server and compares it only when both hold the
same revision and no local changes are pending. Different revisions, slow
acknowledgements and delayed checks remain **Syncing**; they are not proof of
corruption. New edits invalidate the previous verification.

Typing and selection replacement stay local while the edit is applied, so
intermediate delete/insert events do not reset the cursor. Composition finishes
before an incoming update changes the editor. Updates from other people continue
to merge normally.

### Reconnect and recovery

During a temporary disconnect, the tab keeps pending operations and retries on
reconnect. It replays their original identities only against a compatible server
checkpoint. A proven text mismatch, an update that cannot be applied, or a changed
checkpoint that prevents safe replay pauses sending and retains a local draft.
It does not automatically send that held draft after a refresh.

Open **Out of sync ▾** beside the note title:

1. Choose **Download local draft** to save your text before discarding anything.
2. Choose **Use server version** to discard the held local draft and fetch current
   server content. This does not overwrite the server note.
3. Compare your downloaded draft with the note, then reapply any missing changes
   in the editor.

**Download edit data** saves `note-edit-data.json` with the local editing and sync
state for inspection. It does not send edits, discard the draft or load a server
version. This is diagnostic data, not an automatic restore/import action.

A retained draft normally survives refresh in the same browser tab. Browser
storage can be unavailable; follow the warning to copy or download it before
closing or refreshing. Do not clear browser storage as a recovery shortcut.

Legacy CLI/Python edit helpers retain their conditional revision checks below.
The v2 patch interface uses merge mode by default and opt-in exact mode.
They cannot read or recover an unsent draft held in another browser tab. A fresh
CLI read describes server content, not proof that every open editor matches it.

## Time travel

Click the **Time travel** history icon beside the title to open a near-full-screen,
resizable viewer. Use **Play/Pause**, previous/next step, or the ticked slider to
browse retained versions. Each tick selects one recorded edit; the slider snaps
to those ticks.

The viewer is **view only**. It captures the checkpoint and retained edits when
opened, renders them separately, and does not replace the live editor or publish
changes. Close and reopen it to include newer edits. There is no restore action.

When you step or play through versions, added rendered text briefly glows green.
Removed text appears in red with a strikethrough, fades, then disappears. Colors
compare the view you left with the view you entered: stepping backward reverses
which text appears and disappears. A jump compares the two selected views rather
than replaying every intermediate edit. Formatting-only changes update normally.

Pausing playback freezes an active highlight; resuming continues it. Stepping or
scrubbing cancels the old transition so ghosts never pile up. Faster playback
uses shorter fades. Reduced-motion preferences use static highlights that clear
without fading. Very large comparisons display the version without highlights
to keep navigation responsive. Deleted ghosts are presentation-only, excluded
from accessibility output, selection, and the code-copy action. They never alter
saved text or the live editor. Scroll position stays under your control.

History starts at the retained checkpoint: compaction can remove older versions.
This is not a complete archive, and playback is not a recovery tool for an unsent
local draft. Download a held draft through the sync dropdown instead.

## For coding agents

```bash
git clone https://github.com/dreamlake-ai/dreamlake-skills.git ~/dreamlake-skills
mkdir -p ~/.claude/skills
ln -s ~/dreamlake-skills/dreamlake-notes ~/.claude/skills/
```

`git pull` then updates it. Use `.claude/skills/` for one project.
`dreamlake-cli` in the same repo is the full CLI reference.

The Notes skill's procedure is generated from this guide. Correct examples
here first, then regenerate the docs reference and synchronize the public
skills repository using the [docs-to-skills procedure](/dev/skills.md).

## Placeholders

Use square brackets with whitespace immediately inside both brackets for text
that still needs to be filled in: `[ xxxxx ]`,
`[ owner name ]`, or `[ launch date ]`. Notes show these as blue highlighted inline
boxes with visible brackets and inner spacing: `[ owner name ]`. Hover over
a box to see **placeholder**. This works in the editor, table cells and
read-only view. Keep the brackets until you replace
the placeholder with its final value; the saved Markdown remains plain text. `[text]`, `[ text]`, and `[text ]`
are plain text, not placeholders. Empty brackets and whitespace-only content
are not placeholders.

```markdown
Owner: [ owner name ]
Launch: [ launch date ]
Review #note:6aa9951250d9de84058e8ebb before publishing.
```

References take precedence: Markdown links such as `[guide](https://docs.dreamlake.ai/notes/)`,
reference links with a definition (`[guide][docs]` or `[docs]`), images, and
`#note:<full-note-id>` keep their reference behavior. Do not turn a reference
into a placeholder. Task markers (`[ ]` and `[x]`) and brackets inside code
are not placeholders. Escape the opening bracket (`\[literal]`) when you want
ordinary bracketed prose without a highlight.

## Create and list

**CLI**

```bash
dreamlake notes create "Design Doc"
dreamlake notes create "Design Doc" --file draft.md
dreamlake notes create "Design Doc" --text "# Design Doc"
dreamlake notes create "Design Doc" --public        # default is private

dreamlake notes list
dreamlake notes list --limit 20
dreamlake notes list --shared                       # what others sent you
dreamlake notes list --json
```

**Python**

```python
import dreamlake as dl

note = dl.create_note("<namespace>", "Design Doc", text="# Design Doc\n")
note.id, note.namespace, note.etag

dl.list_notes("<namespace>")
dl.list_notes("<namespace>", limit=20, offset=20)
dl.shared_with_me()
```

Titles may repeat — the slug takes a suffix — so keep `note.id` rather than
the name you passed.

## Link to a note in the browser

Use the note's full `id` in browser links:

```text
https://dreamlake.ai/<namespaceSlug>/notes?note=<noteId>
```

Read `namespaceSlug` and `id` from `dreamlake notes create --json` or
`dreamlake notes list --json`. Do not substitute the title or human-readable
slug in this URL: the browser detail route expects the ID, even though the
CLI accepts slugs and titles. Use the returned owner namespace rather than
assuming your personal namespace. The ID is sometimes called the note hash;
it is the `note` query parameter, not a `#` URL fragment.

In the development preview, the path controls the list pane independently of the
active note:

- `/<namespace>/notes` lists notes.
- `/<namespace>/projects` lists projects; `/projects/<project>` opens a project.
- `/<namespace>/bindrs` lists Bindrs; `/bindrs/<bindrId>` opens a Bindr.

Append `?note=<full-note-id>` to any of these paths to open a note. Switching
list context keeps that note open. The note header's contextual list button
hides or restores the list pane. Older note and project links redirect to these
routes. List search includes ordering; default status/category chips are omitted
from the compact panes. Project and Bindr member ordering is applied before
pagination so it covers the entire result set.

Inside another DreamLake note, prefer `:note[<full-note-id>]` (development preview) for a native note
reference. A browser link does not change visibility or grant access to a
private note.

## Inline text color and highlights

Use a color directive to style an inline span in Notes previews, table cells,
and the app’s rendered Markdown:

```markdown
:color[Important]{color="#ef4444"}
:color[Ready]{color="green"}
:highlight[Review needed]
:highlight[Key finding]{color="#60a5fa"}
:color{text="Review needed" color="#f90"}
```

The content is plain text, including any Markdown markers. Escape brackets and
backslashes with a backslash in bracket content. Color values must be quoted:
3, 4, 6 or 8-digit hex colors, or `black`, `silver`, `gray`, `white`, `maroon`,
`red`, `purple`, `fuchsia`, `green`, `lime`, `olive`, `yellow`, `navy`, `blue`,
`teal`, `aqua`, `orange` or `rebeccapurple`. Unknown attributes and invalid colors
remain literal. Code, escaped directives and Markdown links remain literal too.
Selecting a directive in the editor reveals its original editable source;
saved Markdown is unchanged. `:color` changes the foreground; `:highlight` adds
a translucent background tint and keeps the surrounding text color. Omit the
`color` attribute to use yellow: `:highlight[Important]` or
`:highlight{text="Important"}`. Highlights
accept the same colors and plain-text content as color directives, including the
attribute-only form `:highlight{text="Review needed" color="yellow"}`.
Raw HTML and arbitrary CSS styles are not enabled.

See the [Markdown authoring guide](/notes/markdown/) for formatting examples,
color choices, tables and portability. CLI/API HTML snapshots currently keep
color directives as source text.

### Highlight metadata

Attach optional `user` and `comment` strings to a highlight:

```markdown
:highlight[Review needed]{user="geyang" comment="Confirm the delivery date"}
:highlight[Key finding]{color="#60a5fa" user="geyang" comment="Check the source"}
:highlight[重点 🤖]{comment="First line\nSecond line"}
```

Highlight annotations reuse the Notes inline/sidebar comments toggle. Inline
mode shows no annotation cards or hover popups. Click highlighted text in the
editor to reveal its editable source. Sidebar mode shows the handle and comment
in compact cards in the table-of-contents column, with an edit action for writers.
Cards follow the passages visible in the current viewport; a dense group scrolls
inside the column. Narrow panes fall back to inline mode. Read-only sidebar
cards show metadata without edit controls.

`user` is the canonical public user handle, such as `geyang`, not an internal
user ID or a display name. A single leading `@` is accepted; the saved source is
not rewritten. Autocomplete inserts the canonical handle. Compact sidebar cards
show the handle. Legacy display-name values remain literal; the app never guesses
an account from a name. Attribution is self-declared and does not verify authorship
or grant access.

These are plain-text annotations on a highlight, not saved comment threads.
Either field may be omitted; empty strings add no label. Existing plain highlights
and colors keep their behavior. Select the directive in the editor to edit its
source, including metadata. Metadata does not change the highlighted text or
its source offsets, including in table cells and read-only app views.

Attribute values use JSON string escaping: `\"` for a quote, `\\` for a
backslash and `\n` for a newline. HTML in metadata stays text. Unknown or duplicate
attributes and malformed quoting leave the whole directive literal. Use `user`,
not `author`; only `color`, `user` and `comment` are accepted secondary attributes.

Agents should first read the note and retain its revision, then replace the exact
existing directive using `--if-match` and read it back.
For example, set `NOTE_ID` to the target note ID and read its legacy ETag
(the replacement helper uses an ETag, not a v2 `rtc:` revision):

```bash
# NOTE_ID is the ID returned by create/list; this edits an existing highlight.
SNAPSHOT=$(mktemp)
dreamlake notes read --legacy --note "$NOTE_ID" --json > "$SNAPSHOT"
REV=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["etag"])' "$SNAPSHOT")
dreamlake notes replace ':highlight[Review needed]' \
  --text ':highlight[Review needed]{user="geyang" comment="Check the source"}' \
  --note "$NOTE_ID" --if-match "$REV"
dreamlake notes read "$NOTE_ID" --json
rm "$SNAPSHOT"
```

The existing `notes create --text` / `--file` commands also accept this syntax.
There is no dedicated highlight command: these are ordinary Markdown directives,
so matching text with `notes replace` is enough; no line numbers are needed.

Do not overwrite the whole note to update one annotation. CLI/SDK storage already
accepts this Markdown; no new client method or package version is required.
CLI/API HTML snapshots retain rich directives as source text; the app renders them.

### Web preview tags

Open a web page beside a Note with a preview tag:

```markdown
:preview[https://example.com/deck/#slide-3]{title="Slide 3"}
```

The URL is required; the title is optional. Tags work in the editor, tables and
rendered Markdown. A normal click opens the built-in web preview panel beside
the Note. New targets open as tabs in the existing panel on the right; a right
panel is created only when one is absent. Reopening the exact URL reuses its tab;
different URL fragments retain separate preview tabs. Note references follow the
same rule. References opened from a side Note add tabs in that same side panel,
preserving the current Note and its edits. Modified clicks keep ordinary browser link behavior.
Only absolute HTTP(S) URLs without embedded credentials are accepted. Invalid
syntax, duplicate or unknown attributes, unsafe schemes, code and escaped tags
remain literal text. The saved source is unchanged by rendering.

A target must allow iframe embedding. Its own authentication and framing policy
still apply. A temporary tunnel URL works only while its tunnel and server run.
Browser static rendering retains an inert label before hydration; server CLI
HTML snapshots currently leave preview directives as literal source with the
existing source mapping. They do not load the target or create a panel.

### Embeds

See [Embeds and query arguments](/notes/embeds/) for responsive ratios, fixed
sizes, zoom, and the artifact/preview query API. Inline references stay in the text
flow; `embed` shows a content block; opening a reference shows its standalone
page in the preview/browser.

### Artifact references (development preview)

Use Markdown directive notation for new references:

```markdown
:note[6ab5aaeed3b4339ea2f4c162]
:artifact[geyang/pitch-deck]
:bindr[bindr-id]
:asset-reference[asset-id]{caption="plot"}
:placeholder[owner name]
:chatgpt-content-reference[0]
```

This follows the [remark-directive convention](https://github.com/remarkjs/remark-directive),
a Markdown extension, not core CommonMark. Brackets hold primary content; braces
hold optional named attributes. Resource semantics are DreamLake-specific.
The namespace and artifact ID are both required because artifact IDs are scoped
to their owner; note IDs resolve globally. The Note picker, extraction and copy
reference button now prefer `:note[<full-note-id>]` in the development UI.
Both Note and artifact headers show a clickable `#…` badge with the last six ID
characters. Clicking copies the complete bracket reference, including the owner
namespace for artifacts; it does not create a share link or change access.

Saved `#note:<full-note-id>`, `#artifact:geyang/pitch-deck`,
`:note{id="note-id"}`, `:artifact{namespace="geyang" id="pitch-deck"}` and all
existing attribute-only rich components remain accepted. Do not bulk-rewrite
stored notes. Bare `:note{ID}` and `:artifact{namespace/id}` are invalid.
Secondary attributes currently include asset `caption`; values are double-quoted
JSON strings. Unknown/duplicate attributes, conflicting primary values, missing
fields and invalid IDs remain literal. Preserve exact source on reads and patches.
Placeholder content can escape brackets and backslashes with a backslash.

References grant no access and never change sharing. Missing/inaccessible resources
remain unavailable. Code, escapes and Markdown links stay literal. Imported ChatGPT
citation forms stay unresolved and retain their original source; never invent a
Note or artifact to replace them. Existing `[ owner name ]` placeholders remain supported.

Click an artifact tag in a Note or a project's Note pane to open the reusable
artifact panel to the right of that note. The note stays open. Clicking another
reference to the same artifact reuses its panel, including references to a different
slide. Panels retain the artifact viewer's preview, version, zoom and authorized
sharing controls, and use the common draggable tabs and close controls.
Control/Command-click keeps the ordinary artifact link behavior. The current
implementation is a development preview until the companion UI is deployed.

The browser resolves titles through authorized artifact metadata. API HTML
previews map each full token atomically and leave it unresolved, without fetching
private metadata or embedding capability URLs. Artifact tags are implemented in
the local development UI/API; production deployment is not yet verified. There
is no artifact insertion picker yet: type/paste the complete token.

### Fragment reference syntax (development preview)

A reference can retain a slide or section target as a URL fragment:

```markdown
:note[6ab5aaeed3b4339ea2f4c162#overview]
:artifact[geyang/pitch-deck#slide-3]
:artifact[geyang/pitch-deck#/3]
```

The optional named form `:note[id]{fragment="overview"}` is also accepted.
Specify the fragment only once. The parser separates it from the resource ID and
preserves the exact raw token, including percent encoding. Malformed fragments
remain literal. Static API HTML maps the complete reference atomically without
fetching metadata or creating capabilities.

Artifact references pass their fragment to the panel's local `dreamlake.route`.
For example, `:artifact[geyang/landing-pages#slide-3]` opens the landing-page copy
at stage 3. Selecting another slide updates the existing iframe without reloading
it or changing the surrounding Note/project URL. Note-section scrolling remains
separate from this artifact behavior. An existing artifact ID or an author-defined hash route must supply
the target; do not infer slide numbering or invent a section.

## Suggested edits

Use three tags for reviewable edits stored directly in the note:

```markdown
:insert[new text]{user="geyang"}
:delete[existing text]{user="geyang"}
:replace[existing text]{with="replacement text" user="geyang"}
```

`user` is optional display attribution. `replace` requires `with`; an empty
replacement is allowed. Add optional `reason="Why this change helps"` to explain
a suggestion. Attribute values are JSON strings. Escape literal brackets and
backslashes in the bracket body with a backslash. Insertion-menu choices fill
the signed-in user's name; scripts can supply attribution explicitly.

The bracket form is canonical. The browser also accepts a curly-body alias for
all three kinds; optional named attributes follow in a separate pair of braces:

```markdown
and I:insert[ think this works]
and I:insert{ think this works}
:delete{old text}{reason="No longer needed"}
:replace{old text}{with="new text" user="geyang"}
```

A suggestion can directly follow ordinary text without an intervening space.
Leading and trailing spaces inside its body are preserved when accepted.
Curly bodies support balanced nested braces; escape a literal brace or backslash
with a backslash. Canonical bracket bodies retain their existing bracket escaping.
These aliases apply to suggested edits, not other directive types.

Insertions are underlined and deletions struck through in the note. A replacement
shows both. Inline mode shows these text changes without cards or hover popups.
Switch to Sidebar in a wide pane for **accept · reject** actions. Compact cards
replace the table of contents in its existing column and follow passages visible
in the current viewport. Dense groups scroll inside that column. Hovering or
focusing a card or text anchor highlights the corresponding annotation. Narrow
panes fall back to Inline while retaining the Sidebar preference.

Accept applies the proposed text: insert keeps new text, delete removes old
text, and replace substitutes its `with` value. Reject removes an insertion or
restores the original text of a deletion/replacement. Each decision replaces
only that exact tag in one undoable editor operation and uses the note's normal
collaborative save. If the source changed before the action, it refuses the stale
operation. Note writers can accept/reject; read-only views show the proposal
without write controls. No separate suggestion collection or replies are added.

Incomplete or malformed tags remain literal. Tags inside code, Markdown links,
or comments do not become suggested edits. Supported kinds are intentionally
limited to insert, delete, and replace; use comments for questions or discussion.

## Comments (development preview)

Comments use `:comment[text]` for text stored in the note and
`:comment[cmt_<24 hex digits>]` for a saved comment reference. Both accept optional
`{user="geyang"}` attribution and `mode="inline"` to keep an occurrence inline. Braces after a bracket contain metadata only;
there is no `type`, `text`, `ref`, or `userId` field. Attribution is a display
label; the server records the authenticated creator separately. Escape brackets
and backslashes with a backslash. Use `\cmt_...` inside brackets when an ID-shaped
string should be literal text. Code spans and fenced code remain literal.

In the rich editor, typing `:comment{` starts a saved-comment draft. Keep typing
in the note: its side box mirrors the body. The editor supplies a hidden draft
key for retry safety; this key does not create a saved comment object. Closed
drafts first save after 800 ms of inactivity once their body contains at least
two non-whitespace characters, or with any nonempty body when the caret or focus
leaves the comment. Empty and whitespace-only drafts never create objects.
IME composition defers writes. Saving never moves the
caret or replaces active text. Once the caret leaves and the latest body is
acknowledged, source becomes `:comment[cmt_...]{user="..."}` (the optional user
attribute is retained when supplied). Newly typed comment brackets and brace
drafts automatically include the signed-in user's namespace as `user`. Opening
a saved comment edits its object while the reference stays fixed. In Sidebar
view the borderless editor and its Save action share the comment container;
Save waits for the latest save before closing. Comments have no replies; conversations belong in chats.

The sidebar starts with Comments when review annotations are present. In
**Settings → Sidebar suggestions**, Automatic learns a small preference model
from comment use and corrections; fixed Comments and Contents modes disable
that automatic choice. The model makes at most one decision per note visit,
when preview is enabled and the pane has room. Choosing a tab or collapsing the
sidebar takes priority for the rest of that visit. Narrow panes keep annotations
inline. An empty Comments view falls back to Contents without erasing the choice.

New choices do not create per-note preference records. Existing saved note
choices remain readable for compatibility. Learning is saved per account in
this browser, with eight numeric context features, at most 32 recent feedback
records, and an 8 KiB total storage cap. Records exclude note identifiers,
titles, authors and bodies. Settings shows observation counts, storage use,
recent outcomes and selection probabilities. You can choose how often the
other view is tried, stop keeping recent records, clear records, or reset
learning. Disabling or clearing the record history does not erase the aggregate
model; Reset learning clears both while preserving your settings.

The initial exploration rate is 5%. Comment use is a small positive signal;
dismissing Comments or manually opening it after Contents corrects the model.
Inactivity is never positive feedback. A decision without an explicit correction
is evaluated after 60 visible, focused seconds; incomplete visits are discarded.
These signals estimate interface usefulness, not user satisfaction.

**Comments → Inline / Sidebar** changes the current view, independently of
storage. Inline comments show the author label and italic text in the author's
collaboration color, with faint brackets around the body. Sidebar comments use
`[…]` anchors and compact bracketed cards. Short comments wrap in full; longer
comments show four lines with **Read more** to expand a scrollable reading view.
**Edit** opens the saved-comment editor separately. The editor grows with its
text up to a bounded height, then scrolls. Cards replace
the table of contents in the same column, follow visible passages, and scroll
within the column when densely packed. Hovering or focusing the anchor or card
highlights its matching annotation. Inline mode has no annotation cards or hover
previews; explicitly opening a saved comment opens its editor beside the clicked
comment, within the visible window, without scrolling the note to the top.
The editor's **Resolve** action saves pending changes before removing that comment
occurrence from the note; **Save** closes the editor without removing it.
The **Inline this** button sits after the resolve checkmark. At rest it is a
Lucide chevron; hover or keyboard focus animates it into a left arrow pointing
at a vertical line. Reduced-motion preferences show the same states without
animation. The action saves pending edits and adds `mode="inline"` to that
occurrence, keeping it in the paragraph with the Comments sidebar open.
Use the right chevron in its editor to return it to the sidebar. Both actions
use editor history, and Undo restores the previous occurrence.
Readers without note-edit permission do not see these actions. Narrow panes
fall back to Inline while retaining the Sidebar preference. Read-only readers can open accessible saved comments but
cannot change them. Rendering, loading, and remote text replay never create
comment objects. A brace draft pasted by a script without an editor creation
key remains source text; use the API to create a saved object deliberately.

The same completion menu handles supported tag names after `:`, accessible
resource targets within `[`, and supported attributes within `{`. The `user`
attribute offers people lookup. Free text stays valid; searching does not save
or convert it. Comment bodies are free text: typing inside `:comment[` does not
search saved comments. Existing saved-comment references still render normally.

### Collection API

These endpoints require the matching server version. They are not a CLI release
claim. Paths are relative to the DreamLake API base.

| Method and path | Contract |
|---|---|
| `POST /namespaces/:slug/notes/:noteId/comments` | Body `{body, creationKey, user?}`; authenticated origin-note writer only. Key is 16–128 ASCII letters, digits, `_`, or `-`. |
| `GET /namespaces/:slug/notes/:noteId/comments?q=...` | Up to 30 accessible origin-note comments, newest first; optional body substring search. |
| `GET /namespaces/:slug/comments/:commentId` | Read the object under its original note's permissions. |
| `PATCH /namespaces/:slug/comments/:commentId` | Body `{body, revision}`; compare-and-swap update; stale revision returns 409. |

Returned objects include `id`, `noteId`, `body`, optional `user`, `createdBy`,
`revision`, timestamps and `canEdit`. Bodies are nonempty and at most 20,000
characters. Retrying creation with the same note/key returns the existing object
without overwriting it. A different key deliberately creates a different object.
Reads of public origin notes allow anonymous callers; private origins and deleted
origins do not become visible through a copied reference. Invalid credentials
are rejected, and mutations still require authentication and write permission.

Retain local text on a failed save or revision conflict. Retry uncertain creation
with the same key, and never overwrite a newer object from an older draft.
The editor retains recovery state for the current browser session; the keyed
body remains in the note until acknowledged and collapsed. A changed object
requires reconciliation, with the local draft available to copy. A lost response
can safely be retried. Deleting an anchor does not delete its saved object.

## Name a note

**CLI**

```bash
dreamlake notes read --legacy design-doc                     # slug
dreamlake notes read --legacy 6aa948b3fea6e541282b747e       # id
dreamlake notes read --legacy "Design Doc"                   # exact title

# Every example below uses $NOTE_ID. Set it once — any of the three forms:
NOTE_ID=design-doc
```

**Python**

```python
dl.note("<namespace>/design-doc")
dl.note("6aa948b3fea6e541282b747e")                  # id alone, no namespace
```

A note you may not read answers exactly as one that does not exist.

## Read

### Prefer the smallest relevant read

For a targeted question or edit, read the relevant section or passage instead
of the entire note. Use `toc` or `find` to locate it when needed, then request
that section or line range. Read the whole document when reviewing the whole
document, establishing a required v2 baseline, or recovering a missing or expired
baseline — not on every small edit or verification.

Keep the baseline and its tokens across calls. Once a v2 baseline is available,
use [incremental reads](#keep-incremental-reads-compact) to refresh the cached
source and check edits; inspect only the relevant changed passages. A section
read is not a complete v2 baseline. Do not replace the whole body with a partial
read, or substitute a legacy ETag for an opaque v2 revision.

With the current CLI, `--section`, `--start-line`, `--end-line` and `--numbered`
require `--legacy`. V2 supports complete source and `--since` deltas, not section
snapshots. Prefer the scoped compatibility read for inspection; obtain one full
v2 baseline only when the planned patch workflow needs it and none is cached.

Attributed reads also affect what collaborators see. A full-body read selects
the full source; a scoped read selects its returned passage, and a delta read
does not claim a whole-document selection. Match the requested range to the
work you are doing. Do not issue repeated full reads just to refresh presence;
use a heartbeat for an active session or let recent presence expire.

### Read commands

The existing examples below use the explicit `--legacy` CLI contract (source
`text` and content-hash `etag`). The v2 interface later in this guide uses
`content`, `hash` and an opaque RTC `revision`. Do not mix their tokens.

**CLI**

```bash
dreamlake notes read --legacy "$NOTE_ID"                                    # whole body
dreamlake notes read --legacy "$NOTE_ID" --section install                  # one section
dreamlake notes read --legacy "$NOTE_ID" --start-line 40 --end-line 80
dreamlake notes read --legacy "$NOTE_ID" --start-line 40 --end-line 80 --numbered
dreamlake notes read --legacy --note "$NOTE_ID" --json                      # body + revision
dreamlake notes toc --note "$NOTE_ID"                              # the outline
dreamlake notes toc --note "$NOTE_ID" --json
```

**Python**

```python
note = dl.note("<namespace>/design-doc")
note.text                        # whole body
note.read_section("install")     # one section
part = note.read_lines(1, 40)
part.truncated                   # there is more below
part.total_lines
doc = note.read()
doc.toc()                        # anchor, title, level, line range, ind range
```

A **section** is a heading plus everything under it. Anchors are title slugs
(`setup`, `setup-2` when repeated); text above the first heading is
`preamble`.

`toc` gives each heading an anchor, a **line range** and a **character range** —
enough to edit a part without reading the whole note.

A ranged read reports the **whole** note's revision. Writing a range back as
the body deletes everything outside it — use `replace` instead.

## Edit by what it says

Line numbers move when anyone edits above them; text does not. A query matching
**twice is refused**, not applied to the first match.

The examples below are independent recipes, not a script to run in sequence.
Before each revision-checked edit, read the note and capture its revision
(the CLI recipe uses `jq`):

```bash
REV=$(dreamlake notes read --legacy "$NOTE_ID" --json | jq -er .etag)
```

Inspect the returned body before choosing the edit. After a successful write,
read again before the next edit; do not reuse the old revision or bypass a
conflict with `--force`.

**CLI**

```bash
dreamlake notes find "Draft" --note "$NOTE_ID"
dreamlake notes find --regex '\bTODO\b.*' --flags im --note "$NOTE_ID"

dreamlake notes replace "Draft" --text "Published" --all --note "$NOTE_ID" --if-match "$REV"
dreamlake notes insert --text "New line" --line 10 --note "$NOTE_ID" --if-match "$REV"
dreamlake notes delete "obsolete paragraph" --note "$NOTE_ID"
```

**Python**

```python
doc = dl.note("<uuid>").read()      # local snapshot
doc.find("Draft")
doc.find(regex=r"\bTODO\b.*", flags="im")

updated = doc.replace("Published", query="Draft", all=True)
print(updated)                       # the full new source, not just the part changed
doc.insert("New line", line=10)
doc.delete(query="obsolete paragraph")
print(doc.diff())                    # what would change
doc.save()                           # one conditional write
```

Replacement text is the **first** argument; `query` or `regex` names what to
change. Each edit returns the whole updated source, not just the part it
touched.

Exactly one match is expected. `--all` / `all=True` takes every match;
`--count N` / `count=N` requires exactly N. A failed edit changes nothing.

Python edits are local until `save()`, which writes one patch against the
revision `read()` returned. If the note moved, the save is refused.
`doc.revert()` throws the local edits away.

### Patterns

Regex is explicit — never inferred from the query. JavaScript syntax in both
clients: `(?<name>…)`, `$1`, `$<name>`, `$&`, `$$` for a literal `$`. Capture
expansion is automatic; there is no flag for it.

**CLI**

```bash
dreamlake notes replace --regex '(\w+)=(\d+)' --text '$1: $2' --all --note "$NOTE_ID"
dreamlake notes replace --regex '(?<key>timeout|retries)=(?<value>\d+)' \
  --text '$<key>: $<value>' --all --note "$NOTE_ID" --if-match "$REV" --dry-run
```

**Python**

```python
doc.replace("$1: $2", regex=r"(\w+)=(\d+)", all=True)
doc.replace("$<key>: $<value>", regex=r"(?<key>timeout|retries)=(?<value>\d+)", all=True)
```

`--dry-run` prints the result without writing. Every mutation takes
`--if-match`.

### By line or character range

When the text is awkward to name, address it by position instead. Positions
come from a read or from `toc`.

**CLI**

```bash
dreamlake notes replace --text "Updated line" --line 10 --note "$NOTE_ID" --if-match "$REV"
dreamlake notes replace --text "New block" --line 10:15 --note "$NOTE_ID"
dreamlake notes replace --text "replacement" --ind 120:145 --note "$NOTE_ID"
dreamlake notes insert --text "inserted text" --ind 120 --note "$NOTE_ID"
```

**Python**

```python
doc.replace("Updated line", line=10)
doc.replace("New block", line=(10, 15))
doc.replace("replacement", ind=(120, 145))
doc.insert("inserted text", ind=120)
```

Lines are **1-based and inclusive**. `ind` is **0-based and end-exclusive**,
counted in Unicode code points — so an emoji or a CJK character is one unit,
not two. `toc` returns both.

A line edit keeps the line ending; a character edit adds nothing.

### HTML

Markdown may contain HTML, and a note's body can be an HTML document outright.
When it does, address an **element** rather than raw text — the same sentence
often appears in several places, and a plain query would refuse the edit as
ambiguous.

**CLI**

```bash
dreamlake notes select "#contact" --note "$NOTE_ID"          # where it is, and its text
dreamlake notes replace "Contact us" --text "Talk to sales" --selector "#contact" --note "$NOTE_ID"
dreamlake notes insert --text "<li>New</li>" --selector "#list" --position append --note "$NOTE_ID"
```

**Python**

```python
doc.select("#contact")
doc.select("#contact").replace("Talk to sales", query="Contact us")
doc.select("#contact").update(attrs={"href": "/sales"})
doc.select("#list").insert("<li>New</li>", position="append")
```

A selector must match **exactly one** element; zero or several is an error.
`select` on its own only reports — the element's source range and its decoded
text — and changes nothing.

Only the addressed characters change; entity spelling, attribute quoting and
whitespace elsewhere survive.

## Write whole parts

For replacing a section or the whole body outright, rather than editing text
in place.

**CLI**

```bash
dreamlake notes write "$NOTE_ID" --file whole.md
dreamlake notes write "$NOTE_ID" --section install --file install.md
dreamlake notes append "$NOTE_ID" --text "one more line"
dreamlake notes append "$NOTE_ID" --file more.md
dreamlake notes add-section "$NOTE_ID" --file trouble.md --after install
dreamlake notes rm-section "$NOTE_ID" troubleshooting
```

**Python**

```python
note.write(whole_body)
note.write_section("install", "## Install\n\npip install dreamlake\n")
note.append("\n## Changelog\n\n- shipped\n")
note.insert_section("## Troubleshooting\n\nCheck the logs.\n", after="install")
note.delete_section("troubleshooting")
note.refresh()                   # re-read after someone else wrote
```

Anyone with the note open **sees the change appear** — your edit merges with
what they are typing. Nothing is locked.

### Changes since a read or edit

**Legacy ETag interface:** available alongside v2 in CLI 0.26.2 and Python SDK 0.20.0. Select `--legacy` for these CLI recipes and `legacy=True` for remote Python patches.

The CLI returns the same ref in `read --json` and accepts it via `--since`:

```bash
# Requires jq. Keep the snapshot and ref for a later shell session.
NOTE_ID=design-doc
dreamlake notes read --legacy "$NOTE_ID" --json > note-snapshot.json
REV=$(jq -er .etag note-snapshot.json)
dreamlake notes diff --legacy "$NOTE_ID" --since "$REV"
dreamlake notes diff --legacy "$NOTE_ID" --since "$REV" --json
# Apply a diff prepared against that saved body:
dreamlake notes patch --legacy "$NOTE_ID" --file change.patch --if-match "$REV" --json
```

`notes diff` requires `--since`; it does not keep a hidden local baseline.
Plain output is the diff on stdout and current ETag on stderr. `--json` also
returns `from` and `to`. The CLI help includes this workflow:
`dreamlake notes diff --legacy --help`, `notes read --help`, and `notes patch --help`.

Reads return `doc.etag`, a quoted SHA-256 hash of the complete note text. Keep
that ref to see changes since your own read or successful edit across sessions:

```python
note = dl.note("<note-id>")
doc = note.read()
ref = doc.etag

print(note.diff(since=ref))          # current text versus that snapshot
print(note.diff())                   # defaults to this handle's last ETag
result = note.patch(my_diff, if_match=ref, legacy=True)
ref = result.etag                   # reference for the successful edit
```

Fetching a diff does not advance the cached revision or write precondition.
Call `read()` or `refresh()` to adopt the latest state. Identical text has the
same hash; the ref identifies content, not an RTC operation index. Unknown refs
return an error, including older refs whose snapshots were never retained.

The HTTP endpoint is `GET /namespaces/:slug/notes/:noteId/diff?since=<etag>`.
It returns `diff`, `from`, `to`, and `etag` (the current ref). Snapshots are
scoped to the note and require current read access. Optional `context` accepts
0–100 lines, default 3. Partial reads return a ref for the complete body.

For local draft changes, use `doc.diff()` for all unsaved changes,
`doc.diff(since="last_edit")` for the latest local operation, and
`doc.patch(unified_diff)` to apply a patch before `doc.save()`.

### Patch

This legacy patch helper validates unified-diff context against current text
and rejects mismatched context. Its optional ETag rejects any intervening
revision. The v2 merge workflow below instead addresses the saved original
native identities and preserves compatible concurrent edits.

**CLI**

```bash
diff -u before.md after.md | dreamlake notes patch --legacy "$NOTE_ID" --file -
dreamlake notes patch --legacy "$NOTE_ID" --file change.patch --dry-run
```

**Python**

```python
note.patch(unified_diff, legacy=True)
note.patch(unified_diff, if_match=doc.etag, legacy=True)
```

## Search

**CLI**

```bash
dreamlake notes grep "TODO" -C 2
dreamlake notes grep --regex '\bFIXME\b' --case-sensitive --glob 'spec-*'
dreamlake notes grep "Draft" --json        # revision + character range per hit
```

**Python**

```python
for hit in dl.grep_notes("TODO", namespace="<namespace>", context=1):
    print(f"{hit.note_slug}:{hit.line}:{hit.column}  {hit.text}")
```

Output is `slug:line:column`, like `rg` — which note, and where inside it.
Literal and case-insensitive by default, so `v1.2` does not match `v1x2`.

Each hit carries its revision and `ind`, the character range — enough to edit
without re-reading:

```python
hit = dl.grep_notes("Draft", namespace="<namespace>").hits[0]
doc = hit.open().read()
doc.replace("Published", ind=hit.ind)
doc.save()
```

## Files

Files inherit the note's permissions.

**CLI**

```bash
dreamlake notes files upload ./report.html --note "$NOTE_ID"
dreamlake notes files list --note "$NOTE_ID"
dreamlake notes files list 'assets/*.png' --note "$NOTE_ID"
dreamlake notes files cat config.json --note "$NOTE_ID"
dreamlake notes files write config.json --text '{}' --note "$NOTE_ID"
dreamlake notes files download report.html --note "$NOTE_ID" -o ./report.html
dreamlake notes files mv old.txt new.txt --note "$NOTE_ID"
dreamlake notes files cp a.txt b.txt --note "$NOTE_ID"
dreamlake notes files rm old.txt --note "$NOTE_ID"       # trash
dreamlake notes files list --trashed --note "$NOTE_ID"   # ids of trashed files
dreamlake notes files restore <file-id> --note "$NOTE_ID"
```

**Python**

```python
note.files.upload("diagram.png", path="assets/diagram.png")
note.files.create("config.json", text='{"enabled": true}\n')
note.files.list("assets/*.png")
f = note.files.find("assets/diagram.png")
f.download("./local.png")
f.move("assets/new.png")
f.copy("assets/copy.png")
f = f.trash()                    # each returns the updated file
f = f.restore()
```

Bytes are **streamed** both ways and never decoded, so a file larger than
memory still round-trips intact. `cat` refuses a binary rather than printing
mojibake.

`rm` moves a file to the trash. Restoring takes the file **id**, not its path —
two trashed files can share a path, so the path alone would be ambiguous.
`files list --trashed` prints the ids.

### Attach an image and get its path

With the CLI installed and signed in, set `NOTE_ID` to your note's full ID and
upload a local PNG. No JSON flag or parsing is needed for interactive use:

```bash
dreamlake notes files upload ./diagram.png --note "$NOTE_ID" --path assets/diagram.png
```

The output shows `assets/diagram.png`, the size, content type and file ID.
You chose that logical path with `--path`; without it, the path defaults to
`diagram.png`. To get just the authenticated **preview page URL** on stdout:

```bash
dreamlake notes files preview assets/diagram.png --note "$NOTE_ID"
```

For scripts that need to capture the returned attachment path, use the
structured response below (`jq` required):

```bash
set -e
NOTE_ID="<full-note-id>"
dreamlake notes files upload ./diagram.png --note "$NOTE_ID" \
  --path assets/diagram.png --json > attachment.json
IMAGE_PATH=$(jq -er '.path' attachment.json)
printf '%s\n' "$IMAGE_PATH"  # assets/diagram.png
```

The Python equivalent returns a file object with the same logical path:

```python
import dreamlake as dl

note = dl.note("<full-note-id>")
image = note.files.upload("./diagram.png", path="assets/diagram.png")
print(image.path)  # assets/diagram.png
```

`path` is relative to the note's attachment collection, not a browser image
URL. Uploading an attachment does not insert it into the note body. The file
preview link is a viewer page, not a URL to use in an image's `src`.

### Get an image URL for Markdown or HTML

For an inline image, upload the bytes to the media endpoint and keep the
returned `url`. This is a separate upload from the permission-inheriting
attachment above; you can skip the attachment step if you only need an inline
image. Media is not listed by `notes files list`.

CLI 0.37.0 and later return that URL directly using your saved login:

```bash
dreamlake notes media upload ./diagram.png
```

Or capture it for insertion into a document:

```bash
IMAGE_URL=$(dreamlake notes media upload ./diagram.png)
printf '\n![Architecture diagram](%s)\n' "${IMAGE_URL:?Upload the image first}" > image.md
printf '<img src="%s" alt="Architecture diagram">\n' "${IMAGE_URL:?Upload the image first}" > image.html
```

Choose either the direct upload or the capture command; each call uploads a
new media object. No note ID or namespace is needed, and upload alone does not
edit a note. Optional `--json` returns the full receipt. This command requires
CLI 0.37.0 or later; check `dreamlake notes media upload --help` for availability.
For installed versions without it, use the HTTP example below.

Set `DREAMLAKE_TOKEN` to a valid bearer token for the API environment you are
using. The following uses `curl`, `jq` and an existing `./diagram.png`; set
`API_URL` for another environment before running it:

```bash
set -e
: "${DREAMLAKE_TOKEN:?Set a valid DreamLake API bearer token}"
API_URL="${API_URL:-https://api.dreamlake.ai}"
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $DREAMLAKE_TOKEN" \
  -F 'file=@./diagram.png;type=image/png' \
  "${API_URL%/}/notes/media" > media.json
IMAGE_URL=$(jq -er '.url' media.json)
printf '%s\n' "$IMAGE_URL"

# Save snippets to local files, ready to paste or insert.
printf '\n![Architecture diagram](%s)\n' "$IMAGE_URL" > image.md
printf '<img src="%s" alt="Architecture diagram">\n' "$IMAGE_URL" > image.html
```

For one-liners without `--json` or an intermediate JSON file, use the same
token and local image setup above. The upload response is still JSON;
`jq` extracts its URL. This is the fallback for CLI versions without
`notes media upload`.

```bash
IMAGE_URL=$(set -o pipefail; curl --fail-with-body --silent --show-error -H "Authorization: Bearer ${DREAMLAKE_TOKEN:?Set a valid DreamLake API bearer token}" -F 'file=@./diagram.png;type=image/png' "${API_URL:-https://api.dreamlake.ai}/notes/media" | jq -er '.url')
```

After that upload succeeds, choose either one-liner to write the image markup:

```bash
printf '\n![Architecture diagram](%s)\n' "${IMAGE_URL:?Upload the image first}" > image.md
printf '<img src="%s" alt="Architecture diagram">\n' "${IMAGE_URL:?Upload the image first}" > image.html
```

The response contains `url`, `contentType` and `sizeBytes`. The URL has the form
`https://api.dreamlake.ai/notes/media/<media-id>`. Keep that returned URL rather
than the temporary storage URL it redirects to. Do not construct it from the
attachment path or ID.

Insert the Markdown snippet into your existing note with the append helper:

```bash
dreamlake notes append "$NOTE_ID" --file image.md
```

Use `image.html` in an HTML document; for the Notes Markdown body, use
`image.md`. Raw HTML is not enabled in the Notes Markdown renderer. Attaching
an HTML file with `notes files upload` is also separate from editing the note
body. The static `notes read --view html` preview excludes network-loaded
media, so verify the image in the interactive app.

Anyone holding a media URL can load it without signing in. Making a note
private does not revoke that URL. For an image that must inherit the note's
permissions, keep it as a file attachment and use the authenticated file
preview instead of publishing an inline media URL.

### Look at one

**CLI**

```bash
dreamlake notes files preview report.html --note "$NOTE_ID" --open
dreamlake notes files preview report.html --note "$NOTE_ID" --share
dreamlake notes files preview report.html --note "$NOTE_ID" --revoke
```

**Python**

```python
print(note.files.find("report.html").preview_url())
print(note.files.find("report.html").preview_url(share=True))
note.files.find("report.html").unshare()
```

The default link needs a signed-in reader. `--share` opens without signing in
and does not expire; `--revoke` kills every copy at once.

Uploaded HTML renders in a separate origin, never the dashboard's. Markdown,
SVG, code and images render too; anything else offers a download. A file with
no rendered form is refused rather than linked.

## Legacy revision-checked edit helpers

The legacy whole-body/local-document helpers below carry the revision they were based on. A note that changed in
between is **refused** rather than overwritten:

**CLI**

```bash
REV=$(dreamlake notes read --legacy "$NOTE_ID" --json | jq -r .etag)
dreamlake notes write "$NOTE_ID" --file new.md --if-match "$REV"
```

**Python**

```python
doc = dl.note("<uuid>").read()
doc.replace("Published", query="Draft", all=True)
doc.save()                       # refused if the note moved since read()
```

| Python | CLI exit | Means | Do |
|---|:---:|---|---|
| `NoteChanged` | `3` | It changed since you read it | Re-read, redo. Retrying fails again. |
| `NoteBusy` | `4` | The realtime outcome is unavailable | Preserve the draft and baseline; read and reconcile before resubmitting. |
| `PatchFailed` | `5` | Your diff no longer applies | Re-read, regenerate it. |
| `NoMatch` | `6` | Nothing matched | Widen the query. |
| — | `7` | Refused to overwrite a local file | Pass `--overwrite`. |

`--force` / `force=True` skips the check — deliberately, so overwriting a
colleague is something you typed rather than something that happened.

Verify a write landed by reading it back against the revision it produced:

```python
rev = note.patch(diff, if_match=doc.etag, legacy=True)
check = note.read(if_match=rev.etag)      # refused if anything changed since
```

## Which addressing to reach for

1. **Exact text** (`query=`) — what you can state reliably; ambiguous matches fail.
2. **A section anchor** from `toc` for a heading and its contents.
3. **A line or character range** from a current read, TOC or grep hit.
4. **A unified patch** for coordinated changes in several places at once.

## Next steps

    Every `dreamlake notes` command and flag.

    The endpoints underneath, if you need them directly.

## Notes v2: merge and exact patches

Released September 24, 2026 with CLI 0.26.2, Python SDK 0.20.0 and the Notes API
backed by RTC server 0.5.1. The API retains native baselines and the authority
supplies unlocked baseline observations. Upgrade older clients before using
these examples. Deployment evidence and manual acceptance are tracked in
[the Notes master plan](https://github.com/dreamlake-ai/dreamlake-workspace/issues/706).

A v2 source read returns `note`, `hash`, `revision` and `content`. `hash` is
`sha256:` plus the exact UTF-8 source digest. `revision` is an opaque RTC write
baseline; equal text does not imply an equal revision. Keep the original source
and token together until the edit is verified. Never fetch a fresh token merely
to make an old patch pass.

```bash
set -euo pipefail
NOTE_ID=design-doc
dreamlake notes read "$NOTE_ID" --json > baseline.json
BASE_HASH=$(jq -er '.hash' baseline.json)
BASE=$(jq -er '.revision' baseline.json)
jq -jr '.content' baseline.json > base.md

dreamlake notes read "$NOTE_ID" --since "$BASE_HASH" --format inline-dff
dreamlake notes read "$NOTE_ID" --since "$BASE_HASH" --format diff

# Example requires saved source exactly Hello world. without a final newline.
dreamlake notes patch "$NOTE_ID" --format inline-dff --base-revision "$BASE" --json > committed.json <<'PATCH'
@@ chars 0:12 @@
~ Hello [-world-]{+team+}.
PATCH

REVISION=$(jq -er '.revision' committed.json)
dreamlake notes read "$NOTE_ID" --if-match "$REVISION" --json > verified.json
```

Use a quoted heredoc delimiter absent from the patch body. Multiline stdin is
the default; `--file` is optional. Both reads and uploads select `inline-dff` or
`diff` independently. Full reads and incremental reads have self-contained text
metadata by default; JSON is opt-in. `--legacy` selects the previous text/ETag
contract. `notes diff` is the incremental-read alias in the matching CLI.

Inline ranges count Unicode code points, zero-based and end-exclusive. Literal
marker punctuation uses backslash escaping, with `\n`, `\r`, `\t` and `\\`
for controls/backslashes. Unified line patches preserve exact line endings and
`\ No newline at end of file` markers. Invalid patches apply nothing. The default patch sends `{format, patch, baseRevision, mode: "merge"}`
without `If-Match`: the server retrieves the original identity-bearing snapshot
and journal, validates the original source, and compiles the sparse edits into
ordinary native RTC operations. Concurrent changes merge by native character
identity; the server never re-diffs an old target against freshly read text.
The source hash alone cannot identify this baseline. Missing or expired native
baselines fail explicitly and require a new read and a reviewed patch. A room
reset invalidates prior generations even in merge mode.

The default mode is `merge`. Add `--exact --base-revision "$BASE"` to require
the original authoritative revision at commit (`mode: "exact"` in the API). For compatibility, `--if-match`
alone supplies both the original baseline and exact mode; if both flags are
provided they must agree. An explicit API `mode: "merge"` conflicts with
`If-Match` and is rejected. Python uses `base_revision=BASE` with optional
`exact=True`. Patch receipts include `mode` (`merge` or `exact`), the original
`baseRevision`, and the observed resulting `hash` and `revision`. That observation
may already include later concurrent edits. Only exact mode uses the conditional commit
protocol and may return 412 when another writer changed the room. Merge-mode
patches use the existing `crdt`/`ack` protocol. RTC outages produce errors,
never an archive-only replacement.

`--since` accepts a retained hash, ISO timestamp/date, or positive integer
`second(s)`, `minute(s)`, `hour(s)` or `day(s) ago`. Unzoned timestamps and dates
use UTC; relative times resolve once at server request time. Time lookups select
the latest **retained source observation** at or before that instant, not every
browser keystroke or an audit history of all commits. Retention starts when this
interface records snapshots; no earlier history is invented. Unknown or expired
bases return an explicit error. Apply a returned patch only to its exact `base`
source, and verify the resulting hash. A no-op source diff may carry a newer RTC
token; it never advances an existing draft automatically.

The default `diff` read aligns source lines directly, so substantial rewrites do
not consume the character-alignment budget used for merge-safe write patches.
`inline-dff` still requires bounded character alignment. Invalid references
return `400 bad_reference`, missing retained snapshots return `404 revision_not_found`,
diff-generation limits return `422 diff_failed`, and retained-storage or observation
failures return `503 diff_unavailable`. Preserve the original baseline on failure.
A display diff does not guarantee that a later merge patch fits the write limits;
merge remains the default and exact mode remains opt-in.

Native CLI 0.33.0 has a redirected-file input defect: `--file - < edit.dff`
can send an empty patch and receive a successful no-op receipt. Until a release
containing the stdin fix is installed, use `--file edit.dff` and inspect
`--dry-run --json` to verify `payload.patch`. The corrected reader preserves
redirected input and rejects empty patches before sending. This does not change
merge semantics; always verify the requested text in the acknowledged snapshot.

Stop on failure and preserve the patch, working copy and original baseline.
A missing acknowledgement can mean a commit occurred. The backend reconnects
at most once within the same request and resends the identical native message
and operation IDs. The CLI does not automatically retry the HTTP patch. A new
HTTP invocation is an independent operation, with no cross-request idempotency
receipt: read and reconcile the result before resubmitting. Exact readback can itself return a conflict if another writer
has already changed the acknowledged revision.

### Agent presence and activity (opt-in)

#### Agreed lifecycle and identity

**Presence is opt-in.** Agents can read and edit using normal authentication and
revision checks without any agent ID, join, heartbeat, or leave. A runner opts in
by supplying a stable session ID. The client generates it (a UUID once per task),
not the server. Names and IDs are self-reported, grant no permissions, and are not
verified audit identity. Two clients under the same authenticated owner can reuse
an ID; random UUIDs prevent accidental collisions, not deliberate impersonation.

Presence means **active in this note recently**, for both humans and agents. It is
not proof that an agent is continuously watching, reading, or typing. Reuse the
existing RTC awareness channel and header badge; do not add a status row below
the bindr row.

Keep three identities separate:

| Identity | Purpose |
|---|---|
| Agent identity / display name | Identifies the agent; its name is a supplied label, not verified model identity. |
| Task/session ID | Stable across all CLI calls in one task; distinct for concurrent sessions, even for the same agent. |
| Human owner | Derived from authentication, not an agent-supplied owner field; attribution does not imply the owner is present. |

The runner creates the task/session ID once, retains it across tool invocations,
and passes it to every Notes command. Do not generate an ID on every command or
use a shared display name as the session key. Resume the same ID for the same
task; use a new ID for a new or concurrent task. Socket reconnections have their
own transport IDs and must not create a new logical participant.

The current `DREAMLAKE_AGENT_ID` / `X-DreamLake-Agent-Id` field carries this
**task/session ID**, despite its name. It does not yet represent a separate,
persistent agent-account ID. The roster key is scoped by note, authenticated
owner, and session ID; the display name is never the key.

| Event | Intended behavior |
|---|---|
| First attributed read/edit | Implicitly join and start the recent-presence timeout. |
| Later read/edit with the same session ID | Refresh the existing badge, without adding another participant. |
| Inactivity | Remove the badge after expiry; no cleanup command is required. |
| Explicit leave/unjoin | Remove that session from that note immediately; do not erase its identity. |
| Interaction after leave or expiry | Implicitly rejoin using the same session ID. |
| Optional explicit join or maintained session | Support clients that need sustained presence; ordinary CLI use does not require it. |

Human clients can send leave on navigation away or note closure. Abrupt tab close,
crash, or network loss may prevent delivery, so expiry is still required. Agents
have the same optional leave and expiry fallback. A session ID is identity, not a
live lease: storing the ID does not keep a badge alive. Neither a TUI nor a
continuous edit stream is required for recent presence.

Read activity uses the **existing human selection and cursor display**, with the
agent label and participant color. It selects the returned source range; a
full-body read selects the full source, and incremental changes do not claim a
whole-source selection. New read/focus activity replaces the previous selection.
Search does not add a separate seek event. Do not render a second agent-specific
selection style or a tool-call log.

Insertion/replacement text uses a fading highlight only after acknowledgement.
Deletion has no special marker in this iteration. Failed writes and dry runs never
produce success highlights. Selections expire after 8 seconds; completed edit
highlights fade over 5 seconds. Neither heartbeat nor badge renewal extends those
lifetimes. A completed edit may finish fading after its author leaves. Human
cursors retain relative CRDT anchoring; CLI selections are exact-source-hash bound
and disappear on source changes, rather than guessing a new position.

People and agents share participant-color rules, not action-specific colors.
Use an agent icon and agent/owner labels to distinguish them; do not rely on color
alone. Concurrent sessions must remain distinguishable even when names match.

The defaults are a 60-second recent-presence timeout and a 5-second
completed-edit fade. Optional passage activity has an independent 8-second
expiry. These are DreamLake choices, not asserted Google Docs, iMessage, or
Claude Tag timing constants.

#### Availability and optional controls

An attributed operation uses the lifecycle above and
implicitly joins or renews the same 60-second presence entry. Anonymous agent
identity is not inferred from ordinary API calls. A separate persistent
agent-account identity is not yet part of the wire contract. Deployment and
client release status must be checked independently of this source documentation.

CLI 0.27.0+ and Python SDK 0.21.0+ support attributed reads and edits.
CLI 0.29.0+ adds `visit` and `read --linger`; CLI 0.31.0+ adds the read-only
`presence` command and event-driven selections. These require matching server
capabilities; a successful read does not prove presence or event support.
The CLI uses the active login's API; running a locally installed binary does not
select a local server. Use `--remote <url>` to test a specific API or `--debug`
for the local development server.

To check a matching API, use an accessible test note and the stable task identity
below. Run a read, inspect `notes presence`, then start `read --linger` and stop
it with Ctrl-C to verify automatic session cleanup. Verify patch support
separately on a disposable note with a merge patch, an exact readback, and a stale
exact request that must fail without changing the source. Do not use an existing
user document as a write-test fixture.

#### Read and linger in the foreground

CLI 0.29.0+ adds `notes read --linger` and `notes visit`. They use the deployed Notes v2, presence-roster and
agent-activity endpoints. Python has no corresponding convenience method yet.

Set `DREAMLAKE_AGENT_ID` once to a unique, stable task-session identity (and
optionally `DREAMLAKE_AGENT_NAME`) as described below. `NOTE_ID` must identify a
note you can access as a member or explicitly shared reader.

```bash
# NOTE_ID and the stable task identity must already be set.
dreamlake notes read "$NOTE_ID" --linger
```

**Use the default text output for people and coding agents.** It shows readable
diffs, participants, and quoted selections. JSON is optional and intended only
for a program that explicitly needs to parse structured events.

The command registers presence automatically, prints the complete source with
its hash/revision and the other current participants, and stays in the foreground.
A separate `visit` is optional. Interrupt with Ctrl-C or SIGTERM to stop and send
leave. No background daemon is spawned. Presence expires after its server lease
if the process is killed or cannot send leave. Use one linger process per
note/task identity; multiple keepers using the same identity share one lease.

Edit delivery is **debounced**: wait until the observed source has been quiet
for `--debounce` (default `2s`), then deliver **one unified diff** from the last
emitted content baseline through the end of the burst. Each newly observed edit
restarts that quiet timer. Continuous editing keeps the diff pending; there is
no forced maximum-wait flush. Stopping before the quiet period ends discards the
pending notification, not any document edits.

All output batches are **throttled** by `--throttle` (default `2s`): no two update
batches are emitted closer together than that interval. Presence and activity
can still be delivered while edits continue; they do not reset the edit quiet
timer. Once a diff is ready it joins the next eligible output batch, so a recent
presence batch can delay it until the throttle expires. The first source snapshot
is immediate. No new batch is emitted merely because a timer elapsed.

Both flags require `--linger` and accept explicit `ms`, `s` or `m` units, including
fractions, from `250ms` through `5m`. Bare numbers, zero, negatives and out-of-range
values are rejected before presence registration. For example:

```bash
# One second of edit quiet; no more than one output batch every two seconds.
dreamlake notes read "$NOTE_ID" --linger --debounce 1s --throttle 2s
# Slower text output for a coding agent or a quieter session.
dreamlake notes read "$NOTE_ID" --linger --debounce 2s --throttle 5s
```

**CLI 0.42.0+:** `--intent "…"` publishes a self-reported purpose with the
session — one short, specific sentence in the agent's own voice, shown to
collaborators in the agent's presence card. It is sent once at join;
heartbeats preserve it, and leave or lease expiry removes it. The flag requires
`--linger` (`notes visit` also accepts it for one-shot presence). The server
trims the text and rejects empty values and more than 280 Unicode code points.

```bash
dreamlake notes read "$NOTE_ID" --linger \
  --intent "I'm reviewing this sequence to make the pacing clearer."
```

**CLI 0.31.0+:** linger subscribes to authenticated
`GET /namespaces/:slug/notes/:noteId/events` (SSE). CLI 0.29.0–0.30.0 used
polling. The event stream requires a matching server; there is no silent
polling fallback.

The server observes the existing RTC connection events and coalesces them to
at most one batch per 250ms. The CLI keeps only the latest selection per browser
connection, emits at most one update per `--throttle`, and delivers the final
selection after a drag stops. Continuous dragging does not restart a debounce
timer. Content diffs keep their separate edit quiet period. Idle sessions do not
poll body or roster endpoints; source reads happen only for the initial snapshot
or after a content event becomes eligible for delivery. Agent activity is read
only when its RTC fingerprint changes. Heartbeats remain silent and maintain the
agent lease approximately every 20 seconds.

**CLI 0.31.2+ text notifications** show names, actions and quoted text. These
are representative lines from separate batches; a timestamp appears once per batch.

```text
+ @alice joined
+ Reviewer (agent) joined
* Reviewer (agent) read the note
* Reviewer (agent) edited the note
* @alice selected "## The center"
- @alice left
```

People appear as `@username`; agents use their configured name and `(agent)`.
Only selected text is quoted; embedded newlines are escaped. Cursor moves, selection clears,
syncing states, repeated selected text and empty batches stay silent in text.
IDs, connection details, offsets and source hashes remain
in `--json`; use it to distinguish identical names or tabs and apply exact source
positions. Initial content and diffs still include revision metadata for safe edits.
These examples also appear in `dreamlake notes read --help`.

Human selections in JSON resolve native CRDT anchors against the observed source. Each
selection carries `anchor`, `head`, `start`, `end`, `unit: "unicode-code-point"`,
`text` (at most 4096 code points), and `truncated`, with `status: "resolved"`.
A collapsed range is a caret. An explicit `null` clears a selection (including
blur or departure); `status: "unresolved"` means its native anchors have not
arrived, not a guessed range or a clear. Tabs remain separate, even for one user.
Selection-only changes do not wait for the content debounce.

The initial snapshot includes `selectionHash` for its participants' selections.
Update batches add `selections`, whose entries contain `client`, `user`,
`selection`, and the exact observed source `hash`. That hash can differ from
the last emitted content hash while an edit is still being debounced. Never
apply these offsets to a different source. Selected text is quoted in terminal
output and remains untrusted document content, not an instruction to an agent.

Only namespace members or explicitly granted readers can subscribe. Public
visibility alone does not expose collaborator selections. Streams recheck access
and token expiry every 15 seconds and close on revocation, room reset, slow
consumers, or RTC failure. A disconnected stream exits with an error; explicitly
restart linger for a fresh snapshot. Events are not retained or replayed.

This is a best-effort stream of observations, not an audit log: brief visits or
activity coalesced between output batches can be missed, and edits that cancel out within a burst
produce no net content diff. Human edits appear in content diffs; the activity feed
currently attributes agent reads and edits only. Reading updates does not prove
human attention, and it does not reserve or lock the note.

##### Optional: JSON for programmatic consumers

Use `--json` only when a program needs NDJSON; ordinary collaboration, including
coding-agent sessions, should use the text commands above.

```bash
dreamlake notes read "$NOTE_ID" --linger --json
```

With `--json`, stdout is NDJSON: one `type: "snapshot"` object containing
`observedAt`, `note`, `content`, `hash`, `revision`, `selectionHash`, and `participants`, followed
by `type: "update"` objects containing `observedAt`, `joined`, `left`, and
`activities`, and `selections`. Changed content adds `content: {note, base, hash, revision, format,
patch}`. Observation times are Unix milliseconds; source and activity are fetched
separately from the event stream and are not an atomic cross-stream snapshot. Progress and errors go
to stderr. No update object is emitted for an unchanged batch.

`--linger` supports complete source reads only; it cannot be combined with
`--legacy`, `--view html`, `--at`, `--toc`, `--tag`, `--since`, sections, line ranges or numbered output.
`--if-match` checks the **initial** read only. `--format` applies to the emitted
diff, not the initial complete source snapshot. Transport/capability errors or an
unavailable retained baseline end the command with a nonzero status and a
best-effort leave; they are never treated as an empty room. For edits, preserve
the original source and revision used to prepare your draft: a later streamed
revision is not a replacement baseline for an older draft.

```bash cli-help="notes visit"
# Optional one-shot registration: does not fetch the note body or keep a daemon.
# NOTE_ID and the stable task identity must already be set.
dreamlake notes visit "$NOTE_ID"
```

`visit` uses the existing join lease (60 seconds unless renewed by an attributed
operation), returns immediately and does not read content. Use
`read --linger` when you want ongoing updates. CLI 0.31.0 removes the old
manual `notes presence <note> <action>` and `join --watch` controls.

`read --linger` manages joining, heartbeats, and leaving automatically. Stop it
with Ctrl-C when finished; one-shot reads and `visit` expire naturally. There is
no manual lifecycle sequence to run alongside it. Never start an untracked
helper that outlives the task.

##### Read who is present

In CLI 0.31.0+, `presence` reads the current roster without joining or refreshing
your session. It does not require an agent ID. Text is the default:

```bash cli-help="notes presence"
dreamlake notes presence "$NOTE_ID"
```

Add `--json` only for a program consuming the roster. There are no direct
`notes join`, `notes heartbeat`, or `notes leave` commands. Use `visit`,
`read --linger`, and Ctrl-C for participation.

##### Low-level HTTP lease protocol

SDK integrations and linger use the HTTP protocol below internally. It is not
a manual CLI workflow.

API: `POST /namespaces/:slug/notes/:noteId/presence` accepts
`{action, hash?, ranges?: [{start,end}], intent?}`, bearer authentication,
`X-DreamLake-Agent-Id`, and optional `X-DreamLake-Agent-Name`.
Actions are `join`, `heartbeat`, `read`, `edit`, `seek`, `clear`, `leave`.
Response is `{state}` or `{state:null}` after leave. Only authenticated members or
explicitly shared readers may publish; `edit` also requires write permission.
Public visibility alone does not grant presence access. Controls do not mutate
document content or revision. Owner metadata comes from authenticated lookup.

`intent` is the agent's self-reported purpose — one short plain-text sentence in
the agent's own voice, such as "I'm reviewing this sequence to make the pacing
clearer." Omitting the field preserves the current purpose, `{"summary": "…"}`
replaces it, and an explicit `null` clears it, on any action. Summaries are
trimmed; empty strings and more than 280 Unicode code points are rejected with
400 `invalid_presence`. The server stamps `updatedAt`; clients cannot supply
owner attribution or timestamps. Intent lives with the presence lease: leave or
lease expiry removes it, and a later join never resurrects an expired purpose.
`clear` keeps its existing meaning — it clears passage activity, not intent.
Intent is a self-reported claim, not observed activity, progress, or a
permission grant; the roster's authorized readers can see it.

#### Read who is present (HTTP API)

`GET /namespaces/:slug/notes/:noteId/presence` returns the current RTC awareness
roster, including humans and agents. Use bearer authentication as a namespace
member or explicitly shared reader. Public visibility alone is insufficient.
Agent identity headers are not required, and the observer does not publish
presence, renew an agent lease, or edit the note.

Successful reads default to `text/plain; charset=utf-8` (also available with
`?format=text`):

```text
Observed at: 2026-09-26T08:00:00.000Z
- human: "Ge" (id: "ge"; client: "browser-session-123")
- agent: "Codex" (id: "agent:owner-id:agent-id"; client: "note-agent-session-456"); owner: "Ge" (id: "owner-id"); intent: "I'm reviewing this sequence to make the pacing clearer."; expiresAt: 1790409660000
```

An empty text roster says `No participants present.` after the observation time.
Client-declared strings are quoted and escaped to keep each connection on one
line. Use `?format=json` for structured output; other format values return
400 `invalid_format`. Error responses remain JSON for either format.

The opt-in JSON response is `{participants, observedAt}`. `observedAt` is Unix time in
milliseconds. Each participant has `client` (connection ID) and `user` with
`id`, `name`, and `kind` (`human` or `agent`), plus optional `color` and `avatar`.
Agents can include `user.owner`, their lease's `expiresAt`, and `intent`
(`{summary, updatedAt}` — the self-reported purpose last published with
presence). Expired agent leases and internal observer connections are excluded. Multiple browser tabs
remain separate entries. To identify other agents, compare `user.id` against
`agent:<authenticated-owner-id>:<agent-id>`; the caller is not automatically
excluded. Human identities without a kind field are normalized to `human`.
These are client-declared display identities, not verified authorization claims.

An inactive note returns an empty roster. An active room whose connection fails
or times out returns 503 `presence_unavailable`, not an empty roster. Responses
are not cached. This requires a server with the GET endpoint and an RTC server
supporting awareness rosters; a 404 can also mean the caller lacks access.
There is no CLI or Python convenience method for roster reads yet. Using any
HTTP client, send an authenticated GET to the path above. The roster is an
observation of presence, not a lock or a guarantee that another editor is idle;
continue to use the normal conditional-write contract.

Explicit ranges require the exact source SHA-256 and zero-based, end-exclusive
Unicode code point offsets. Stale or out-of-bounds locations are refused. A
collapsed seek is a caret, not a claim that text was read. Source changes invalidate
hash-bound markers. Deletion-only edits do not invent insertion ranges.
Errors include missing identity/invalid input (400), denied access (404), stale
range (409), expired heartbeat (410), and unavailable relay (503).

Identity values accept 1–128 ASCII letters, digits, dots, colons, underscores and
hyphens; names accept at most 64 printable ASCII characters. CLI 0.27.0+ and
Python SDK 0.21.0+ attach identity headers to Notes body/section/diff operations
when the environment variables below are set. `visit` and `read --linger` require
CLI 0.29.0+ and an active collaborative room; read-only `presence` requires
CLI 0.31.0+. The old manual action commands were removed in 0.31.0.
Updating a skill does not update a binary or deploy a server. Python has no
presence convenience method yet; use the HTTP contract when available.
The authorized agent-activity feed retains operation observations, not an online
roster. Observation failures must not turn an acknowledged edit into an apparent
failed edit. Live source-range decorations currently require the collaborative
editor; read-only views do not run an RTC client.

#### Identity, names and photos

Use a readable agent prefix plus a UUID as the task ID, for example
`codex:7b52e4d1-3ac9-4d88-b2a6-61f03c927ea5`. Generate it once per task and reuse
it across reads, edits and linger sessions. Concurrent tasks need different IDs;
a display name such as `Codex` does not distinguish their sessions. The CLI sends
`DREAMLAKE_AGENT_ID` as `X-DreamLake-Agent-Id` and `DREAMLAKE_AGENT_NAME` as
`X-DreamLake-Agent-Name`. No separate identity-registration request is required.

| Display field | Humans | Agents |
| --- | --- | --- |
| Presence identity | User namespace slug | `agent:<authenticated-owner-id>:<task-id>` |
| Display name | Profile name from `/auth/me`, falling back to namespace slug | `DREAMLAKE_AGENT_NAME`, falling back to `AI agent` |
| Header avatar | Profile photo, or initials when absent | Bot icon |
| Tooltip | Name and presence | Agent name, owner name, stated purpose (intent), activity and task/session ID |

The server derives an agent's owner from authentication and looks up the owner's
profile name/photo; an agent cannot assign an owner through these headers. The
owner's photo is carried in metadata but is not currently rendered as the agent's
header avatar. Owner attribution does not mean that the owner is present.

The header deduplicates connections by identity: multiple browser tabs show one
human avatar, while unique agent task IDs show separate agent avatars. It shows
up to four avatars plus an overflow chip. Colors are derived from identity.
The HTTP roster still returns one entry per connection. Browser awareness names
and photos are display metadata, not an authorization source.

#### Agentic usage pattern: one identity, normal commands

For agent-driven Notes work, set both identity variables before the first live
read or edit, unless the user explicitly requests unattributed work. This is a
workflow prerequisite for attribution, not a requirement for saving content.
Without `DREAMLAKE_AGENT_ID`, an edit can save successfully while producing no
agent presence or attributed fading edit highlight. `DREAMLAKE_AGENT_NAME`
provides the readable label.

Initialize once in the runner's task environment. For separate shell tool calls,
the runner must inject the same saved values each time; an export in one shell
does not propagate into later independent shells. No explicit join is required.

```bash
export DREAMLAKE_AGENT_ID="${DREAMLAKE_AGENT_ID:-codex:$(python3 -c 'import uuid; print(uuid.uuid4())')}"
export DREAMLAKE_AGENT_NAME="${DREAMLAKE_AGENT_NAME:-Codex}"
NOTE_ID="<full-note-id>"
```

Run ordinary commands with that identity. An attributed `read` automatically
registers or refreshes presence; a preceding `visit` is never required. Reading
without agent identity does not invent or register an agent session. Retain the generated ID in the task context and inject that same literal value into each later shell; rerunning the UUID fallback in a new shell would create a different session.

After the first intended live read, verify attribution with
`dreamlake notes presence "$NOTE_ID"` (CLI 0.31.0+). This only inspects the roster;
it does not register an agent. Check the task ID and display name, not merely
another session named Codex. If absent, check the environment passed to the
actual read/edit process before diagnosing a UI regression. Do not repeat a
successful edit to trigger its highlight. Presence expires about 60 seconds
after the last activity; completed edit highlights fade over 5 seconds and
require an exact matching live document revision. A roster entry verifies
presence only: report a highlight as visually verified only after observing it
in the collaborative editor.

| Command | Reads content | Presence lifetime |
| --- | --- | --- |
| `notes read "$NOTE_ID"` | Once | Registers/refreshes presence, then the lease expires naturally |
| `notes read "$NOTE_ID" --linger` | Initial source and ongoing updates | Registers automatically and maintains presence until stopped |
| `notes visit "$NOTE_ID"` | No | Registers once, returns immediately, then the lease expires naturally |

The last two commands require CLI 0.29.0+. A normal
read does not mean the agent remains actively reading between commands.

```bash
dreamlake notes read "$NOTE_ID" --json > baseline.json
dreamlake notes find lighthouse --note "$NOTE_ID" --json
# Draft a reviewed patch against baseline.json, using the patch workflow below.
# Retain its revision, apply the patch, and read back the acknowledged revision.
```

The conditional patch and exact-readback examples elsewhere in this guide remain
required; presence does not relax concurrency checks. Do not retry an old patch
with a newly fetched revision merely to force it through.

When finished, stop `read --linger` with Ctrl-C; it sends leave automatically.
One-shot operations expire naturally. Keep the same session ID between commands,
and remove the task identity from the runner's environment when the task ends.
Lease expiry handles abrupt exits without requiring remembered cleanup.

### Keep incremental reads compact

For an agent following a note, reuse the saved full `read --json` baseline;
obtain one only if none is available. Then use `read --since "$BASE_HASH"` for
subsequent checks instead of repeatedly downloading the full document. For
one-off passage inspection, use the scoped reads above without fetching a full
baseline. Differential reads default to unified line diffs.
Use `--format inline-dff` explicitly when character edits are useful.
On servers with localized unified-diff generation, this returns changed
lines with up to three unchanged context lines on each side; nearby changes
share a hunk and distant changes use separate hunks. Older servers may still
return a whole-document replacement; a docs or skill update alone does not
change server output.

Both formats preserve exact source, including CRLF and a missing final newline.
An unchanged source returns an empty `patch`, possibly with a newer RTC
`revision`. Keep `base`, `hash`, and `revision` with the response. Apply the patch
only to the saved source matching `base`, verify its resulting hash, and never
replace an existing draft's original revision just to make it pass. Unknown or
expired bases remain errors. Use `--json` and extract `.patch` when a consumer
needs patch text alone; normal text output includes metadata.

#### Verify edits without rereading the whole note

After a successful v2 patch, verify the acknowledged revision with a delta from
your saved baseline. This uses the existing `baseline.json` from the pre-edit
read and `receipt.json` from the successful patch; `NOTE_ID` is the same note
used for both operations, as set in [Name a note](#name-a-note).

```bash
BASE_HASH=$(jq -er .hash baseline.json)
ACK_REVISION=$(jq -er .revision receipt.json)
dreamlake notes read "$NOTE_ID" --since "$BASE_HASH" \
  --if-match "$ACK_REVISION" --json > verified-delta.json
```

Check that the returned `base` matches the cached source hash and its `hash`
matches the receipt. Apply the returned patch to that cached source, verify the
resulting hash, and inspect the intended changes. Preserve unrelated changes
when the write used merge mode. Save the reconstructed source and returned
revision as the next baseline only after verification succeeds.

An empty delta from the receipt's hash checks for changes after the write; it
does not by itself verify the edited text. A stale `--if-match` fails rather than
silently accepting a newer revision: retain the receipt and original baseline,
then inspect an incremental read without that condition to reconcile later
edits. Do not retry the write using a newly fetched revision merely to force it
through. If the cached source or retained base is unavailable, take a new full
snapshot explicitly; do not claim exact verification of an expired revision.

The full-read examples below remain useful as standalone demonstrations and
recovery checks. They are not a requirement to reread the entire note after
every targeted edit.

### Reproduce a concurrent merge and an exact conflict

Use a new private fixture with the compatible releases, an authenticated CLI,
`jq`, and Python `dreamlake` configured for the same account/namespace. These
examples deliberately issue an exact request first, inspect its rejection, and
then make a separate, explicit merge request. There is no automatic downgrade.

**CLI**

```bash
set -euo pipefail
dreamlake notes create "Merge/exact example" --text 'Hello world.' --json > fixture.json
NOTE_ID=$(jq -er '.id' fixture.json)
dreamlake notes read "$NOTE_ID" --json > baseline.json
BASE=$(jq -er '.revision' baseline.json)
jq -jr '.content' baseline.json > original.md
cat > agent.patch <<'PATCH'
@@ chars 0:12 @@
~ Hello [-world-]{+team+}.
PATCH

# Simulate a second participant inserting a prefix after the agent's read.
dreamlake notes patch "$NOTE_ID" --base-revision "$BASE" --json > human.json <<'PATCH'
@@ chars 0:0 @@
~ {+Human: +}
PATCH

# Expected conflict: stdout stays empty; stderr explains the failure; exit is 3.
set +e
dreamlake notes patch "$NOTE_ID" --base-revision "$BASE" --exact \
  --file agent.patch --json > exact.stdout 2> exact.stderr
STATUS=$?
set -e
test "$STATUS" -eq 3
test ! -s exact.stdout
cat exact.stderr

# A separate explicit choice to merge the ORIGINAL patch and identities.
dreamlake notes patch "$NOTE_ID" --base-revision "$BASE" \
  --file agent.patch --json > merged.json
jq '{note, mode, baseRevision, hash, revision}' merged.json
dreamlake notes read "$NOTE_ID" --json > observed.json
jq -er '.content == "Human: Hello team."' observed.json
```

**Python**

```python
import json
import os
from pathlib import Path
import dreamlake as dl
from dreamlake import NoteChanged

note = dl.create_note(os.environ["NAMESPACE"], "Merge/exact example",
                      text="Hello world.")
baseline = note.read_snapshot()
patch = "@@ chars 0:12 @@\n~ Hello [-world-]{+team+}.\n"
Path("baseline.json").write_text(json.dumps(baseline.to_dict(), indent=2), encoding="utf-8")
Path("original.md").write_text(baseline.content, encoding="utf-8")
Path("agent.patch").write_text(patch, encoding="utf-8")

# A separate native edit arrives after this baseline.
note.patch("@@ chars 0:0 @@\n~ {+Human: +}\n",
           base_revision=baseline.revision)
try:
    note.patch(patch, base_revision=baseline.revision, exact=True)
except NoteChanged:
    print("Exact request rejected; original files retained.")
else:
    raise AssertionError("Expected a stale exact request")

# Explicitly choose merge; never do this automatically inside the except block.
receipt = note.patch(patch, base_revision=baseline.revision)
print(receipt.mode)           # merge
print(receipt.base_revision)  # the ORIGINAL opaque token
print(receipt.hash)           # observed resulting source hash
print(receipt.revision)       # observed resulting RTC revision
print(json.dumps(receipt.to_dict(), indent=2))
assert note.read_snapshot().content == "Human: Hello team."
```

### Complete an exact edit and return to merge mode

Continue with the fixture above, now containing `Human: Hello team.`. Read a
fresh baseline before making this new edit. Exact mode applies only to its
individual request; the following empty patch uses the default merge mode.

**CLI**

```bash
dreamlake notes read "$NOTE_ID" --json > exact-baseline.json
EXACT_BASE=$(jq -er '.revision' exact-baseline.json)
cat > exact.patch <<'PATCH'
@@ chars 18:18 @@
~ {+!+}
PATCH
dreamlake notes patch "$NOTE_ID" --base-revision "$EXACT_BASE" --exact \
  --file exact.patch --json > exact-success.json
jq '{note, mode, baseRevision, hash, revision}' exact-success.json

dreamlake notes read "$NOTE_ID" --json > after-exact.json
NEXT_BASE=$(jq -er '.revision' after-exact.json)
printf '' | dreamlake notes patch "$NOTE_ID" --base-revision "$NEXT_BASE" \
  --json > merge-after-exact.json
jq -er '.mode == "merge"' merge-after-exact.json
```

**Python**

```python
exact_baseline = note.read_snapshot()
exact_patch = "@@ chars 18:18 @@\n~ {+!+}\n"
Path("exact-baseline.json").write_text(
    json.dumps(exact_baseline.to_dict(), indent=2), encoding="utf-8")
Path("exact.patch").write_text(exact_patch, encoding="utf-8")
exact_receipt = note.patch(exact_patch, base_revision=exact_baseline.revision,
                           exact=True)
print(exact_receipt.mode)  # exact
print(json.dumps(exact_receipt.to_dict(), indent=2))
after_exact = note.read_snapshot()
assert after_exact.content == "Human: Hello team.!"
merge_receipt = note.patch("", base_revision=after_exact.revision)
assert merge_receipt.mode == "merge"
assert merge_receipt.hash == after_exact.hash
assert merge_receipt.revision == after_exact.revision
```

If another writer changes the exact baseline first, stop on the conflict and
retain these files. The examples do not retry the HTTP request or switch modes
after a failure. The successful follow-up merge above is a separate no-op
request with its own saved baseline.

Successful exact output captured from the matching isolated API fixture with
the candidate CLI (exit 0, empty stderr; these are fixture tokens):

```text
note: 507f1f77bcf86cd799439099
hash: sha256:2b8c0f5475f23494272f3800abb11a7680b3360bc2e927763c10aec9cf4398f5
revision: rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484
mode: exact
baseRevision: rtc:71371be6e3227abca241161ebb7d8d65e2d851b8872b5a5d51ce7ec80369d95e
```

With `--json`, the same exact receipt is:

```json
{
  "note": "507f1f77bcf86cd799439099",
  "hash": "sha256:2b8c0f5475f23494272f3800abb11a7680b3360bc2e927763c10aec9cf4398f5",
  "revision": "rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484",
  "baseRevision": "rtc:71371be6e3227abca241161ebb7d8d65e2d851b8872b5a5d51ce7ec80369d95e",
  "mode": "exact"
}
```

Python's captured `PatchReceipt` attributes match that JSON:

```text
mode: exact
base_revision: rtc:71371be6e3227abca241161ebb7d8d65e2d851b8872b5a5d51ce7ec80369d95e
hash: sha256:2b8c0f5475f23494272f3800abb11a7680b3360bc2e927763c10aec9cf4398f5
revision: rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484
```

The following empty patch defaults back to merge and returns this actual CLI
text receipt (exit 0, empty stderr). Python reports `.mode == "merge"`, and
`.to_dict()` returns the same fields with `baseRevision` in JSON:

```text
note: 507f1f77bcf86cd799439099
hash: sha256:2b8c0f5475f23494272f3800abb11a7680b3360bc2e927763c10aec9cf4398f5
revision: rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484
mode: merge
baseRevision: rtc:63834c3821f7b76779815f3a670449268711811e69f86f6b208fb52236713484
```

The local API/RTC/Mongo fixture verifies `Hello world.` → `Human: Hello team.`:
the unrelated prefix survives, original native identities address the replaced
word, and the exact rejection appends zero operation batches. The matching
source hashes observed in that fixture are:

```json
{
  "originalHash": "sha256:aa3ec16e6acc809d8b2818662276256abfd2f1b441cb51574933f3d4bd115d11",
  "mergedHash": "sha256:163af32ec4bc25f27e3b9ae68fe85c75e5b4436a769cc82a4050692643ce92cf"
}
```

Candidate CLI output captured by replaying that isolated API fixture (exit 0,
empty stderr; these IDs are fixture values, not production):

```text
note: 507f1f77bcf86cd799439099
hash: sha256:163af32ec4bc25f27e3b9ae68fe85c75e5b4436a769cc82a4050692643ce92cf
revision: rtc:71371be6e3227abca241161ebb7d8d65e2d851b8872b5a5d51ce7ec80369d95e
mode: merge
baseRevision: rtc:870fa6d8ca75e1ae8c89b0e4abf08fd8a2c222c99ac698227f25c94b8f5b41e7
```

With `--json`, the corresponding stdout is:

```json
{
  "note": "507f1f77bcf86cd799439099",
  "hash": "sha256:163af32ec4bc25f27e3b9ae68fe85c75e5b4436a769cc82a4050692643ce92cf",
  "revision": "rtc:71371be6e3227abca241161ebb7d8d65e2d851b8872b5a5d51ce7ec80369d95e",
  "baseRevision": "rtc:870fa6d8ca75e1ae8c89b0e4abf08fd8a2c222c99ac698227f25c94b8f5b41e7",
  "mode": "merge"
}
```

The exact conflict replay exits 3 with empty stdout and this stderr:

```text
✗ the original revision or RTC identities are no longer valid for this request; keep the original baseline and draft, inspect the note before resubmitting ((412) stale)
```

Opaque note/revision values vary. A successful JSON receipt contains exactly
`note`, `mode`, `baseRevision`, `hash`, and `revision`; normal CLI text prints
those metadata fields. Python exposes the corresponding attributes, with
`base_revision` in Python and `baseRevision` in `to_dict()`.
These describe a coherent authoritative observation after persistence was
acknowledged. They do not mean every peer has synchronized or that the document
will remain unchanged. Another edit can arrive before the verification read;
`read --if-match "$REVISION"` / `read_snapshot(if_match=receipt.revision)` makes
that verification exact rather than silently accepting a newer state.

The fixture observed these HTTP errors (no success receipt on failure):

```json
{"error":"stale","message":"The RTC baseline changed"}
{"error":"revision_not_found","message":"Original RTC baseline is not retained"}
{"error":"patch_failed","message":"Expected inline header and one record"}
```

They correspond to exact conflict **412** (CLI exit **3**, Python `NoteChanged`),
missing original identity baseline **404** (CLI exit **1**, Python `NoteNotFound`),
and malformed patch **422** (CLI exit **5**, Python `PatchFailed`). CLI failures
leave stdout empty and explain the failure on stderr, without replacing local files.
A destructive room reset or history rewrite can expire native identities even
when the retained baseline envelope still exists; merge then returns **412**
(`stale`, CLI exit **3**, Python `NoteChanged`) without applying the patch.
Ordinary concurrent editing alone does not cause that merge rejection. A missing
retained envelope instead returns **404**; malformed patches return **422**.
The baseline, draft and patch remain the caller's files on all failures. Neither
client retries a failed HTTP patch or silently changes exact mode to merge.
A transport/acknowledgement failure can be ambiguous even when a write persisted:
read, reconcile, and deliberately decide what remains to be submitted.

### HTML snapshot preview

With the compatible v2 server and CLI, `dreamlake notes read "$NOTE_ID" --view html`
returns a complete inert HTML document. Root `data-note`, `data-hash`,
`data-revision`, `data-source-type`, `data-offset-unit` and `data-source`
attributes contain the exact canonical source and its baseline. Element
`data-char="start:end"` ranges address that source in Unicode code points;
`data-map` marks linear text, atomic syntax or generated presentation.

Decode the source attribute once to recover canonical source, including original
entity spelling and line endings. Patch that source using the embedded revision;
never upload generated wrappers or mapping attributes. HTML reads are snapshot
views; `--view html --since` is rejected. HTML-looking source is rendered as
HTML, other source as Markdown. Rich or restricted structures may map atomically;
no editable range is guessed from generated text. Scripts, active attributes and
network-loaded media are excluded from this static preview.

### Literal Markdown for agents

With CLI 0.34.4 and a compatible server, `--view html` on a Markdown note is
an **agent format**: HTML-like tags supply structure and addresses; their
contents are the exact original Markdown. There is one `data-char` source
range, including the construct's syntax. There is no inner/outer split.

```text
<li id="s0.ul1.li2" data-char="0:11">- [ ] Ship
</li>
```

Keep Markdown literal: `- [ ]`, `**bold**`, `:comment[...]`, backslashes,
`<`, `&`, and Unicode remain exactly as saved. Do not add HTML escapes,
Markdown escapes, or Unicode escape sequences to element contents. Do not
strip escapes that are already present in canonical source. No display-text
index conversion is needed: ranges address the source text inside the wrappers.
A parent item's range includes its nested source.

This is not browser HTML. Do not render it or use a DOM parser to recover its
body. CLI 0.34.4 requests `contentFormat=literal-markdown` automatically; direct API clients add that parameter to a v2 HTML read. Existing clients keep the prior rendered contract. The API serves Markdown agent markup as `text/plain` and marks the root
`data-content-format="literal-markdown"`. Generated heading numbers and other
preview decoration are absent. The separate visual preview is unchanged.

Metadata attributes still use transport encoding: decode the root `data-source`
attribute once for an exact machine-readable source slice, and use the trusted
root `data-addresses` index rather than finding tags inside arbitrary Markdown.
CLI `--view markdown` handles this and prints literal source with address hints.
Keep the original revision with the source and verify the acknowledged edit.
Older servers may return rendered HTML; do not assume literal bodies without the
format marker. Canonical HTML notes retain their existing HTML source mapping.

### Focused and historical reads

`read` returns the current snapshot. Use `--at REVISION` for a retained snapshot;
`--since HASH` remains a unified line-diff read. Snapshot selectors are mutually
exclusive, and cannot combine with `--since` or `--linger`:

```bash
# NOTE_ID identifies an accessible note; copy REVISION from its read receipt.
dreamlake notes read "$NOTE_ID"
dreamlake notes read "$NOTE_ID" --at "$REVISION" --toc
dreamlake notes read "$NOTE_ID" --at "$REVISION" --section s1.1
dreamlake notes read "$NOTE_ID" --at "$REVISION" --tag s1.1.p1
```

Selectors return mapped HTML. Nested `section` tags have content-derived IDs and
`data-index="s1.1"`; headings use `s1.1.h`. Paragraphs (`p`), unordered lists
(`ul`), ordered lists (`ol`) and all list items (`li`) share one counter per
section, in document reading order. List and item IDs include their containing
list/item path: `s1.p1 → s1.ul2 → s1.ul2.li3 → s1.ul2.li4 → s1.p5`.
A nested ordered list under the fourth element is `s1.ul2.li4.ol5`, and its
next item is `s1.ul2.li4.ol5.li6`. The suffix is the shared section counter,
not an item-local position.

Checklist items use the same `li` prefix and expose `data-checked="false"` or
`data-checked="true"`; ordinary items omit that attribute. Adding, checking or
removing a checkbox does not change the item's prefix or its container's type.
There is no `tl`, `tli` or `cli` type. HTML tags remain `ul`, `ol` and `li`.

A list consumes a number before its items; nested lists and items continue
that same counter depth-first. Paragraph wrappers inside list items do not
consume another number. Numbering restarts in each section; content before
the first heading uses `s0`. A list target includes its entire subtree, and an
item target includes its continuation lines and nested lists. Markdown task
markers (`[ ]`, `[x]`, `[X]`) and leading HTML checkbox inputs identify checklist
items. Read IDs from the returned snapshot rather than calculating them. `--tag` is an exact element ID; a section ID selects its
entire subtree. IDs are local to one revision. Unknown IDs and missing snapshots
return 404; every read checks current permissions.

`data-char="start:end"` are absolute, zero-based, end-exclusive Unicode code-point
ranges in original source. `data-lines` is one-based and inclusive. A scoped root
contains only the selected `data-source`, with its global `data-source-start` and
`data-source-end` and its own `data-source-hash`. The root's `data-hash` and
`data-revision` still identify the complete document. Subtract `data-source-start`
when slicing local source; keep absolute offsets in the patch. TOCs carry exact
heading source on each heading and empty root source. Never upload a slice or
rendered HTML as the complete note.

```bash
# edit.dff is prepared from the exact source at REVISION.
dreamlake notes patch "$NOTE_ID" --file edit.dff --base-revision "$REVISION" --exact
# NEXT_REVISION comes from that write receipt.
dreamlake notes read "$NOTE_ID" --at "$NEXT_REVISION" --tag s1.1.p1
```

Exact mode refuses concurrent edits with 412; native merge mode remains available
by omitting `--exact`. `--if-match` checks the current revision, while `--at`
retrieves history: do not combine them. Preserve an existing draft's original
baseline even after another read or linger update. Linger continues to emit source
snapshots and line diffs; inspect a streamed revision using a separate pinned read.
Pinned reads do not overwrite live presence with historical offsets.

See the [addressed-read specification](https://docs.dreamlake.ai/dev/notes/addressed-reads/)
for ID generation, ranges, examples, efficiency limits, and the executable
acceptance harness. Use a CLI/server build supporting the addressed-read options.

### Comment targets in HTML reads

Closed comment directives render as individually addressable elements with
`data-rich-kind="comment"`. Their `id` uses `sN.cK` (for example, `s1.c2`),
sharing the section's reading-order counter with paragraphs, lists and items.
Use the returned ID with `--view html --at "$REVISION" --tag s1.c2` to read one
comment's exact canonical directive. The atomic `data-char` and `data-lines`
cover the complete directive, including attribution attributes. These HTML
addresses are revision-local; read them from the snapshot, rather than guessing.

Saved references such as `:comment[cmt_0123456789abcdef01234567]` additionally
carry `data-comment-id="cmt_0123456789abcdef01234567"`. That persistent resource
ID survives moves and edits and can be used with the comment API. Repeated
references to the same saved comment get distinct HTML target IDs but retain
the same `data-comment-id`. Keyed drafts expose `data-comment-key`; inline text
comments have a target address but no invented persistent resource ID.

Static HTML shows source text or the saved reference ID; it does not fetch a
comment's private body. Code examples, escaped directives, malformed comments
and Markdown links remain literal. When normalization prevents an exact range,
the surrounding block remains the edit target instead of a guessed comment range.

### Rich tokens in HTML reads

The v2 HTML renderer recognizes strict Markdown source tokens for
`:placeholder[owner]`, `:asset-reference[asset-id]{caption="plot"}`,
`:note[note-id]`, `:artifact[geyang/pitch-deck]`, `:bindr[bindr-id]` and
`:chatgpt-content-reference[0]` in the development preview, plus every saved legacy form. Attribute values use double quotes;
unknown/duplicate attributes and malformed tokens remain literal source.
Code, escaped punctuation, Markdown links and URL paths keep their ordinary
interpretation. Existing `[ owner ]` placeholders retain blue boxes, visible
brackets, inner spacing and the **placeholder** hover label.

Recognized components carry atomic `data-char` and `data-map`
attributes addressing the complete token in canonical Unicode-code-point
source. The root `data-source` remains exact. When Markdown normalizes a region
so an exact token range cannot be proven, its enclosing block remains atomic;
the renderer never guesses an editable token range.

Static previews show assets, Notes and bindrs as unresolved labels. They perform
no metadata lookup and include no download URL or authorization capability.
Labels come only from source the reader can already read. The interactive
application separately resolves resources through authorized APIs. Imported
ChatGPT citation tags render as unresolved broken-link icons with their original
source in the hover label. Neither form implies that the reference is valid or
accessible. Placeholder CSS is static and hash-authorized by the preview's CSP;
source-provided styles and active HTML remain inert.

This capability is included in the September 24 release. Browser rich
components were delivered separately in
[UI PR #415](https://github.com/dreamlake-ai/dreamlake-ai/pull/415).

### Heading numbering in HTML reads

Markdown Notes can place the following options in an initial YAML front-matter
block. The same policy is used by the editor/outline and the server HTML preview:

```markdown
---
render:
  headings:
    numbering: hierarchical
    startLevel: 2
---
# Design notes

## First
#### Deeper
### Next
## Last
```

The displayed numbers are `1`, `1.1`, `1.2`, `2`. Number only actual ancestors:
skipping a heading level does not insert zero components. A heading above
`startLevel` stays unnumbered and resets the sequence. `numbering` accepts `off`
or `hierarchical` (default `off`); `startLevel` is an integer from 1 through 6
(default 2). ATX and setext headings share the policy; code fences do not count.

Front matter remains part of canonical source, source hashes and patch offsets,
but does not render as body text. Unknown YAML fields survive unchanged. Invalid
supported values or malformed YAML produce a visible diagnostic and default
options; no source rewrite occurs. Unterminated front matter stays literal body
source with a diagnostic.

Numbers are display-only spans marked `data-map="generated"` with no editable
source range. Heading source/anchor behavior stays unchanged. Body and rich-token
source ranges still count from the start of the full document, including front
matter and CRLF. These options apply to Markdown source; canonical HTML is not
interpreted as Markdown front matter. Server HTML reads and the browser
editor/outline support this policy in the September 24 release.

## Select an agent passage by matching text

**CLI 0.32.0+:** `notes select --text` publishes an agent selection; section
selection requires the server update adding `hash` and `range` to section reads.
Older server responses fail explicitly.

```bash
export DREAMLAKE_AGENT_ID="review-session-42"
export DREAMLAKE_AGENT_NAME="Codex"
NOTE_ID="your-note-id"
dreamlake notes select --text "The next step is tested in simulation." --note "$NOTE_ID"
dreamlake notes select --text "simulation" --section next-steps --occurrence 2 --note "$NOTE_ID"
dreamlake notes select --text "simulation" --section next-steps -o -1 --note "$NOTE_ID"
```

Use a stable task identity and your normal authenticated Notes access. The command
matches exact canonical source text, including whitespace and markup. It refuses
missing or ambiguous matches. `-o` aliases `--occurrence`: `1` selects the first
match, `-1` the last, and `-2` the second-last within the chosen scope. Zero and
out-of-range values fail without publishing. Receipts report the resolved
positive 1-based occurrence.
A section match downloads only that section, not the entire document. A whole-note
match reads source internally without printing it. Target resolution suppresses
read highlighting until a unique match is found.

It then sends `POST /namespaces/:slug/notes/:noteId/presence` with
`{action:"seek", hash, ranges:[{start,end}]}`. Ranges are half-open Unicode code-point
offsets in the whole canonical source. Section reads now return an additive `range`
in code points and the whole-source `hash`; legacy `start`/`end` stay UTF-16.
Old servers without section metadata fail explicitly. The server validates current
source and collaboration access. No source write or human-cursor change occurs.

**Plain text is the default for selection commands and agent workflows.** Omit
`--json` in normal tool calls and examples. The receipt confirms server acceptance and returns the quoted matched
text, scope, resolved match number/count, code-point range and separate expiry
times. Multiline excerpts escape newlines. Only an explicit machine integration
should request `--json`; that optional receipt includes exact `text` and
`scope` (`{kind:"note"}` or `{kind:"section",anchor:"next-steps"}`), alongside
`note`, `hash`, `range`, `occurrence`, `matches`, `published`, `selectionExpiresAt`
and `presenceExpiresAt`. It does not return the surrounding section or document. Browser rendering still
requires an active compatible RTC room and editor. Selection activity lasts eight
seconds and presence lasts sixty; a heartbeat renews presence only. Users can
navigate to the agent's selected passage through its location control.

Pass a retained `--hash "$HASH"` (`sha256:…`) to require the same source. If the
source changes before publication, `stale_range` fails without a guessed retry:
read the section again and select its current text. Duplicate/missing matches
publish no selection. Legacy `notes select "#contact" --note "$NOTE_ID"` and
`notes find` remain lookup operations, not explicit visible seek commands.

For address hints while reading Markdown, use `read NOTE --view markdown` with
the addressed-read CLI/server build. It preserves the selected source text and
inserts generated address/character/line comments. List-item targets use
hierarchical `li` IDs, such as `s1.ul2.li3`, including nested items. Containers
use `ul` or `ol`; every numeric suffix shares paragraph reading order. This
reading view is not
canonical source and must not be written back as a complete note.

## Manage existing share links

Available in CLI 0.32.4 and later; check `dreamlake notes share --help` for installed support.

Requires an authenticated login, an existing resource, and permission to
manage its sharing. Run these mutation steps only when the user has asked
to grant or revoke access. These commands change
metadata only; they do not upload content or create a new version.

```bash
# Find the release plan and inspect its source and current sharing.
dreamlake notes search "release plan"
NOTE="release-plan" # Replace with the id or slug from search.
dreamlake notes read "$NOTE"
dreamlake notes share get "$NOTE"

# Give signed-in recipients read access, then verify the returned link.
dreamlake notes share create "$NOTE" --role read
dreamlake notes share get "$NOTE"

# When link access is no longer needed, revoke it and verify.
dreamlake notes share revoke "$NOTE"
dreamlake notes share get "$NOTE"
```

`get` never enables sharing. It reports the resource URL, visibility, and
existing share URL. A resource URL alone does not grant access. `--json` provides
structured link metadata; `shareStatus: unavailable` means the server did not
expose the token to this caller, not that sharing is disabled.

```bash
NOTE="release-plan" # Your existing note id or slug.
dreamlake notes visibility "$NOTE" public
dreamlake notes visibility "$NOTE" private
```

Visibility and sharing are independent. Making a resource private does not
revoke links or accepted access. Revoking a link does not make a public resource
private. Use `--namespace <slug>` for another namespace.

Only the namespace owner or an eligible Note creator may manage sharing.
`create --role write` enables editing; the default is `read`. Updating the role
reuses the token and changes the role evaluated on subsequent requests for
everyone admitted through the link. Note IDs resolve their owning namespace automatically.

```bash
NOTE="release-plan" # Your existing note id or slug.
dreamlake notes share revoke "$NOTE" --revoke-accepted
```

Ordinary revocation clears the link and blocks subsequent link-derived access,
including for prior recipients. Their acceptance records remain: enabling
sharing again restores access under the current link role. `--revoke-accepted`
also deletes those records, so recipients must accept a valid link again. A collaborator who already has the room address may keep
editing until the room is rotated; this command does not rotate rooms.

```bash
NOTE="release-plan" # Your existing note id or slug.
# List acceptance records and stored roles as a readable table.
dreamlake notes share access "$NOTE"
```

```bash
NOTE="release-plan" # Your existing note id or slug.
USER_ID="user-id-from-access-list"
dreamlake notes share remove "$NOTE" "$USER_ID"
```

The access list defaults to a readable table; use `--json` for a structured
integration. It returns stored roles, which may lag behind the live link role.
Use `share get` to inspect the current link role.

Removing an acceptance record does not invalidate a circulating link; that link can admit
the user again. Membership and public access are unaffected.

## Saved versions

The version tag in the toolbar opens a compact revision graph. The right sidebar
uses one toolbar toggle for **Comments**, **Table of contents**, and **History**.
Choose **History** (the GitGraph icon) to see the graph there. Contents is the
default; the note remembers your chosen sidebar. **Working Draft** sits directly above its base version, with an edit
count and a GitCommitVertical save icon on that row. A small solid dot marks the draft endpoint; saved-version waypoints are hollow. Choose the icon, enter an optional title/tag
and summary, then save. Notes continues to autosave while you work; metadata
does not appear in the note body. New milestones receive stable numbers such
as `v3`, independent of their titles. Numbers can have gaps after failed saves.

Saved versions show their parent connections, including forks from a shared
base. The save form defaults to your draft's base; choose another **Base version**
to record a different ancestry. This records the relationship without replacing
or merging the live draft. The working draft follows the newest saved version
when history refreshes, including versions saved by another collaborator, so it
stays at the top and its edit count uses the latest checkpoint. This changes
only the history display and default save parent, not the note text or saved ancestry.
Older versions without recorded
parents remain unconnected.

The current edit marker shows its one-based index and total within that version
interval (for example, **Edit 439 of 443**), including when selected from a grouped tick.
Historical previews use the title-row status slot: **e439**, **preview**
for a saved version, or **e430–439** for a selected range. Version tags use a
lowercase **v** and are hidden while an intermediate edit or range is displayed. Hovering the preview label turns it red with a strikethrough;
clicking it returns to the working draft. The chevron opens history. The full preview label remains in the tooltip.
The history dropdown fits its content, capped at the remaining viewport height
with a 16px bottom gap; longer timelines scroll inside it. The sidebar and dropdown
share the editor selection, including resets and selected ranges. The magnifier
appears above the selected marker and displays its own red edit-index line on
hover. Only an explicitly selected edit or range creates a persistent marker.
The lens follows the pointer immediately; document and range previews settle
after a short pause, reusing a bounded cache of recent historical text.

Each small dot represents one retained intermediate edit; all retained edits
are shown. Hover or keyboard-focus a dot to preview its exact text directly in
the main body. The historical preview is read-only and isolated from live sync;
editor controls and saving are disabled while it is displayed. Leaving the dot
restores the prior selection, while clicking the dot keeps that edit selected.
There is no separate edit list. The magnifier's right edge stays fixed against
the timeline panel as the pointer moves horizontally. A larger magnified region spreads nearby dots
apart for selection. Scrolling previews nearby snapshots; clicking version text or activating it
with the keyboard selects that revision. Leaving a transient preview restores
the last selection. **Back to draft** returns to the still-mounted live editor.
The sidebar's **Contents** view follows Dockit's **On this page** format: compact
heading links, monospace subheadings, an accent-colored active heading, and a
curved progress rail. Section chevrons collapse or expand their child headings;
clicking heading text jumps directly to that section. The separate minimap
column is omitted.

Each saved version retains the exact server-confirmed text, author and date,
plus the available collaboration checkpoint and journal. It remains readable
after live history is compacted or a room is recreated. Compacted edits that were
already missing at save time cannot be recovered; partial counts say **retained
edits**. In a saved-version preview, **Compare / link** opens side-by-side
comparison and **Copy version link**. Saving never replaces the current note.
Tags may repeat; the version ID is unique and immutable. Summaries are written
by the person saving the version; automatic AI drafting is not included.

Saved history requires edit access, including accepted write-share access.
A public note or read-only share does not expose earlier text that may have
been removed. Version links do not grant access. If the note changes or is still
syncing while you save, review the current text and retry; no version is created
from a mismatched browser/server state.

### Version API

These authenticated endpoints are scoped to `/namespaces/:slug/notes/:noteId`:

- `POST /versions` accepts `{hash, tag?, summary?, parentId?}`. `hash` is the lowercase
  SHA-256 of the UTF-8 body the user intends to save. The server compares it
  with a coherent current read and returns `409 note_changed` on mismatch.
  Tags are at most 80 characters and summaries at most 2,000 characters.
  A successful `201` returns `id`, `tag`, `summary`, `hash`, `createdAt`,
  `createdBy`, `author`, `number`, and `parentId`. The optional nullable
  `parentId` must identify a version in this note; a missing/foreign parent
  returns `404 parent_not_found`. Omitting it records no parent. RTC-backed
  versions also include `revision`, `clock`, `editCount`, and `historyComplete`.
  The count measures retained content-edit messages, not keystrokes.
- `GET /versions` returns `{versions, nextCursor}` with up to 50 metadata
  entries, newest first. Send `?before=<nextCursor>` for older entries.
- `GET /versions/:versionId` returns the metadata plus `text`.
- `GET /versions/:versionId/history` returns the retained `{snapshot, journal}`
  for read-only replay, with the same editor access requirement. Legacy versions
  return `{snapshot: null, journal: []}`. This is not a content-write endpoint.

The content hash identifies text, not the identity-bearing RTC baseline used
for collaborative patches. Saving a version is a retained snapshot operation,
not a content write. There are no new CLI flags or Python SDK methods for this
surface yet; use the UI or authenticated REST API.

---

Source: https://docs.dreamlake.ai/sources

{/* The FigSrc* tags come from the site-wide mdxComponents map in
    site.config.ts — no import needed. */}

# Visualize a source

  A **source** is DreamLake's connection to your data — an S3 bucket or a
  Hugging Face repo linked into your namespace. Drop one `.dreamrc` file at a
  dataset's root and the app renders every episode in it: cameras, time
  series, timelines, 3D. Nothing is imported or converted — the app reads
  your storage in place.

## Connect your data

Linking happens in the dashboard: open **Sources** in your namespace
(`/source/<namespace>`) and connect the storage. Credentials stay
server-side, encrypted — never in files or URLs.

| Storage | Connect with | Get bytes in today |
| --- | --- | --- |
| S3 bucket | bucket credentials | `aws s3 cp --recursive ./my-dataset s3://bucket/prefix` |
| Hugging Face repo | OAuth | `hf upload you/dataset ./my-dataset --repo-type dataset` |

Then verify from a shell that the source holds what you think:

```bash
dreamlake source list                                # sources you can reach
dreamlake source browse [path] --source <name>       # list a directory
dreamlake source download <path> --source <name> -o ./out # spot-check a file
```

## Shape the dataset

Most robot-learning exports work **as-is** — a published dataset renders
unmodified, with one file added:

| Your dataset root holds | `format` | Anything to do first? |
| --- | --- | --- |
| `meta/info.json` (LeRobot v2.x / v3.0) | `lerobot` | no |
| `*.zarr.zip` or a `.zarr/` directory (UMI) | `umi` | no |
| `*.mcap` files — Foxglove schemas or plain ROS&nbsp;1 / ROS&nbsp;2 bags | `mcap` | no |
| `model/` + `episodes/*/frames.parquet` + `episode.json` | `folder` | no — a DreamLake sim-playback dataset renders as-is |
| anything else — videos, images, CSV, parquet | `folder` | one folder per episode |

Layout details and shape rules:
[prepare your data](https://viz.dreamlake.ai/dataset-viz/requirements).

## Make it render

The `.dreamrc` names which fields feed which **views** — that's the whole
job. Open the source in the app and the dataset renders:

```yaml file=".dreamrc"
version: 1
dataset:
  format: lerobot # lerobot | umi | mcap | folder
  episodes: auto
views:
  - view: videoStack
    cameras: ['observation.images.*']
  - view: lineChart
    series: [{ field: [action, '*'] }]
```

The full authoring workflow — reading the field inventory, every view and
its options, a live gallery of finished files —
[starts here](https://viz.dreamlake.ai/dataset-viz/start).

## Single MCAP files

Selecting one `.mcap` file in the browser renders it as a one-episode
dataset. Which config drives the render is a fixed chain — the first hit
wins:

1. **`<filename>.dreamrc`** beside the file — `test.mcap` looks for
   `test.mcap.dreamrc`. A config written *for this file*: its views render
   with the selected file as the one episode.
2. **The folder's `.dreamrc`**, when its `dataset.format` is `mcap` — the
   unified config for a folder of recordings, applied to just this file.
3. **The source root's `.dreamrc`**, same condition.
4. **No config at all** — the file still renders: a default view generated
   from its [Foxglove or ROS well-known schemas](https://viz.dreamlake.ai/dataset-viz/reference#the-default-mcap-view).
   Camera topics become a frame stack, point clouds a 3D pane, tf a moving
   robot or skeleton (below), numeric channels charts. The header marks it
   as generated, and **copy .dreamrc** hands you the exact YAML — save it
   as `<filename>.dreamrc` (step 1) and the layout is yours to edit.

The more standard the recording, the more the no-config default shows;
channels outside the Foxglove / JSON / ROS schema set fall back to the
metadata table with the reason stated.

## ROS bags and robots

Plain ROS bags need no conversion — ROS&nbsp;2 (rosbag2's own MCAP
output) and ROS&nbsp;1 alike. Images, point clouds and poses land in the
same views as their Foxglove twins, and the `/tf` tree renders in 3D with
Foxglove semantics: transforms compose down the declared parent chain, so
a tf-only recording plays as a **moving skeleton** — joints, bones, no
model required.

When the names a recording publishes — tf frame ids, or the joint names on a
`/joint_states` topic — carry a known robot's own naming, the default view
goes further and renders **the robot itself**: a Unitree&nbsp;G1 recording
opens as the G1, a DROID episode as a Franka Panda with its Robotiq gripper,
meshes streamed from the
[robot preset registry](https://huggingface.co/datasets/live9080/dreamlake-robots).
Unknown structures keep the honest skeleton — nothing is guessed. To put a
robot on a recording yourself, name its URDF in the 3D view:

```yaml file="<filename>.dreamrc"
- view: recon3d
  up: z
  tracks: [{ field: '/tf::*', as: transform3d }]
  models:
    - https://huggingface.co/datasets/live9080/dreamlake-robots/resolve/main/g1/g1_29dof.urdf
```

The viewer reads URDF directly — meshes resolve relative to the file (or
through a `packages:` map for `package://` references), each link drives from
its `/tf::<link>` track by name, and links the recording never publishes ride
their nearest tracked parent.

A bag that logs only **joint angles** and no per-link poses — very common,
since the angles are the state and the poses are derivable — is 3D too: bind
the topic with `joints:` beside a URDF and the viewer runs the forward
kinematics itself, gripper linkages included. Full detail:
[ROS bags & robot models](https://viz.dreamlake.ai/dataset-viz/robots).

## Sim recordings (MuJoCo & URDF)

A teleop recorder that runs MuJoCo can write a DreamLake **sim-playback
dataset** directly — one folder per episode, plus the exact model the
session ran snapshotted into `model/`. Each `frames.parquet` stores **named
channels** — one column per joint, seven per free body, keyed to MJCF names
by `episode.json` — so the data survives model recompilation and outlives
any single scene version. The `mujoco` view loads the snapshot and plays the
channels back **kinematically**: qpos in, forward kinematics out, never
stepping physics — scrubbing the shared timeline is random access,
frame-exact in either direction. Because channels are name-keyed, an `env:`
override plays the same data on a scene-only [env](/envs.md): hand channels
with no match there are skipped and listed, while objects and fixtures
replay on their own. `ctrl.*` columns carry the action stream for a
`lineChart`. The recorder drops this `.dreamrc` at the root:

```yaml file=".dreamrc"
version: 1
name: sharpa-teleop
dataset:
  format: folder
  episodes: "episodes/*/"
views:
  - view: mujoco
    qpos: [frames]          # named channel columns
    meta: [episode]         # episode.json — channels map + model ref
    height: 420
    # env: ns/laundry       # optional: play on a scene-only env
  - view: timeline           # shared clock + playback bar
  - view: lineChart
    series: [{ field: [frames, 'ctrl.*'] }]
```

The same contract has a **URDF flavor** for motion that isn't an MJCF scene —
a retargeted mocap clip, a policy rollout, anything that is "a robot
description plus per-frame joint values". `episode.json` says `sim: "urdf"`,
`model.path` names the dataset's URDF (with `model.files` listing every
mesh), and channels bind **URDF joints by name** — one column per
revolute/continuous/prismatic joint — plus one `freejoint` channel naming
the **root link** with seven columns (x, y, z, qw, qx, qy, qz — quaternion
**w-first**, meters, Z-up world) for the floating base. The `urdf` view
drives `setJointValue` and the base pose directly; joints the robot lacks
are listed, not fatal, and the same `env:` override plays the data on a
pushed URDF env:

```yaml file=".dreamrc"
version: 1
name: g1-dance
dataset:
  format: folder
  episodes: "episodes/*/"
views:
  - view: urdf
    joints: [frames]        # URDF joint columns, keyed by joint name
    meta: [episode]         # episode.json — sim "urdf", model + channels
    height: 480
  - view: timeline
  - view: lineChart
    series: [{ field: [frames, left_knee_joint] }]
```

Playback lives here, in sources; the envs you curate stay untouched —
pushing and versioning scenes is the [envs guide](/envs.md).

## Let Claude do it

Add the two [source skills](https://github.com/dreamlake-ai/dreamlake-skills),
point at a folder, and say *"visualize this dataset in DreamLake"*:

| Skill | Does |
| --- | --- |
| `dreamlake-source` | inspects the data, preps the layout, gets it linked, verifies the source |
| `dreamlake-dataset-viz` | writes and debugs the `.dreamrc` — bindings, validation, iteration |

```bash
git clone https://github.com/dreamlake-ai/dreamlake-skills
mkdir -p ~/.claude/skills
cp -r dreamlake-skills/{dreamlake-source,dreamlake-dataset-viz} ~/.claude/skills/
```

Install both — source gets the bytes connected, dataset-viz makes them render.

## Next steps

    The five-step authoring workflow, every view, and the .dreamrc gallery.

    The DreamLake-hosted flavor — collections with schemas you push to from
    the terminal.

---

Source: https://docs.dreamlake.ai/workflows

{/* FigWf* come from the site-wide mdxComponents map in site.config.ts —
    no import needed. */}

# Workflows

  A workflow is a typed graph of data production: ordered **stages** whose
  member nodes do the work — deterministic **compute** (UDFs), judgment-making
  **agents**, statistical **samplers**, and **control flow** — joined by typed
  data edges. You push it from the terminal and it renders as a live canvas.

> **Note:** This page is about the **WorkflowSpec** — the typed stage/node graph you push
>   as JSON and run on a canvas. Claude Code's JS orchestration scripts and Python
>   pipelines are also called workflows, share the `Workflow` server model, and
>   answer to the same CLI. If that is what you came for, start at
>   [CJS Workflows vs Python Pipelines](/workflows/cjs-vs-python.md).

## How you use it

One round, from a sentence to a published dataset. Skills live in
[dreamlake-skills](https://github.com/dreamlake-ai/dreamlake-skills).

1. **Install the CLI and the three skills.**

   [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) is where
   you talk to it — install that first.

   | Skill | Does |
   |---|---|
   | `video-labeling-workflow` | fills the template, drives the whole round |
   | `remote-source-check` | proves your source really holds those paths |
   | `workflow-publish` | validates and pushes, and asks which namespace |

   Install all three — the first invokes the other two by name.

   `--env prod` is worth typing. Without it `login` targets whichever
   environment is **active on that machine**, so anyone who has ever logged into
   staging lands there silently — and the failures that follow (an empty
   `source list`, a push to the wrong place) never point back at the cause.
   `dreamlake auth env list` shows which login environment is active.

   Install the standalone CLI from [the CLI guide](/cli.md) and check
   `dreamlake workflow --help`. The Python `dreamlake` package provides the
   SDK; it is not the supported CLI installation path.

2. **Say what you want — it asks for the data, verifies it, shows you what it found.**

3. **It pushes — validated against the schema and the graph rules first.**

4. **Review on DreamLake — iterate, hot-reload.**

5. **Run it — nodes light up, output streams.**

6. **Review at the gate, then approve.**

   The run publishes its dataset and stops. Select the gate node: **↗ Review
   dataset** opens what was produced, **✓ Approve & continue** completes the
   run. The link stays after approval — it is the way back to what was signed
   off.

## What a spec is made of

| Part | What it is |
|---|---|
| **Stages** | phases that group and order — not barriers; execution follows the edges |
| **Nodes** | the members of a stage, from four families |
| **Edges** | typed connections between ports (`samples`, `dataset`, `metrics`, …); types must match end to end, and a `collect` port fans several streams into one input |

| Family | Does | Runs today |
|---|---|---|
| `compute` | deterministic work — filter, transcode, train, publish (any UDF) | ✅ |
| `uda` | agent judgment — labeling, review, curation | ✅ |
| `control` | human **approval** gates | ✅ approval only |
| `sampler` | statistical subset selection | ⏳ spec-only |

The schema also accepts `condition`, `switch`, `loop` and `foreach` control
types. They pass validation, then stop a run with `not supported yet` —
vocabulary to design against, not behaviour to rely on.

A `uda` node declares the tools and **`permissions`** its agent may use, so
judgment never runs on raw credentials. Intermediate results stay in the
worker's run directory; what reaches DreamLake is what a `publish` node
writes.

## Version it

Pushes never overwrite. Each one appends an immutable version, and the
**spec picker** on the workflow page pins the canvas to any of them —
pick the latest to resume following pushes.

Editing a node's settings on the canvas and pressing **Apply** does the same
thing: the edited spec is validated and appended as the next version. Nothing
is edited in place, so a run always names the version it executed.

## Next steps

    The spec graph, Claude Code's JS orchestration scripts, and Python
    pipelines side by side — and the seven places where one of them does not
    exist yet.

    The full vocabulary — every family's inputs, outputs, and configuration,
    rendered with the real components.

    The grant registry uda nodes draw from — domains, verbs, and scopes.

    `dreamlake workflow push` and `list` — flags, namespaces, versioning.

---

Source: https://docs.dreamlake.ai/relay

# LLM Relay

  Agents need a model. Handing every user a provider API key does not scale and
  does not revoke. The relay puts the key on the server: you authenticate with
  the DreamLake token you already have, and DreamLake swaps credentials on the
  way out.

```
POST /relay/anthropic/v1/messages          ← what you call
     ↓  DreamLake token verified, dropped, provider key injected
POST https://api.anthropic.com/v1/messages
```

The provider's wire format is preserved **byte-for-byte in both directions**.
That is the whole design: the official SDKs, Claude Code, and the Claude Agent
SDK work against the relay unmodified. You change a base URL — nothing else.

## Quick start

Point any Anthropic client at the relay and give it your DreamLake token:

**Python tab:** The same two variables work for anything built on the Anthropic SDK — your own
agent loop, a script, a CI job.

**curl tab:** Or with no SDK at all:

**Claude Code**

```bash
export ANTHROPIC_BASE_URL=https://api.dreamlake.ai/relay/anthropic
export ANTHROPIC_AUTH_TOKEN=$(dreamlake token)   # your DreamLake token, not a provider key
claude "summarize the last three runs in this namespace"
```

**Python**

```python
import anthropic, os

client = anthropic.Anthropic(
    base_url="https://api.dreamlake.ai/relay/anthropic",
    auth_token=os.environ["DREAMLAKE_API_KEY"],
)

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[{"role": "user", "content": "What changed in this run?"}],
)
print(next(b.text for b in response.content if b.type == "text"))
```

**curl**

```bash
curl https://api.dreamlake.ai/relay/anthropic/v1/messages \
  -H "authorization: Bearer $DREAMLAKE_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

Streaming works the same way — set `"stream": true` and read the SSE events.
The relay does not buffer streams; chunks reach you as the provider emits them.

## Which model?

**Anthropic Claude, default `claude-opus-5`.** Three reasons:

1. **The agents are Claude-shaped.** CLI agents, Claude Code, and the Agent SDK
   all speak the Anthropic Messages API. Relaying that format verbatim means
   they need no adapter — just `ANTHROPIC_BASE_URL`.
2. **The stack already runs on it.** Hosted Dream Chat containers already call
   Claude. A second provider family would mean two prompt formats, two token
   accountings, and two sets of model IDs.
3. **Opus 5 is the right default tier** for agentic and coding work. Want
   cheaper turns? Pass `claude-haiku-4-5` in the body — the relay never
   rewrites your model, it only reports and (optionally) restricts it.

The relay does not pick models, inject system prompts, or count turns. It is a
credential boundary and a usage log. Agent behavior belongs in the agent.

An `openai` provider exists behind an optional key, because the pass-through is
provider-agnostic. It is not configured by default.

## What you can call

Everything under `/relay/:provider/` is forwarded unchanged, so the provider's
whole API comes along — not just chat completions:

| You call | Reaches |
| --- | --- |
| `POST /relay/anthropic/v1/messages` | `POST https://api.anthropic.com/v1/messages` |
| `POST /relay/anthropic/v1/messages/count_tokens` | the token-counting endpoint |
| `GET /relay/anthropic/v1/models` | the live model list |

The upstream host is fixed per provider, so the relay cannot be pointed at an
arbitrary destination.

To discover what a deployment actually offers:

```bash
curl https://api.dreamlake.ai/relay/providers -H "authorization: Bearer $DREAMLAKE_TOKEN"
```

```jsonc
{
  "default": "anthropic",
  "allowedModels": null,           // or a list, when the deployment restricts models
  "providers": [
    {
      "id": "anthropic",
      "configured": true,          // false → that provider answers 503
      "baseUrl": "https://api.dreamlake.ai/relay/anthropic",
      "defaultModel": "claude-opus-5"
    }
  ]
}
```

`baseUrl` is exactly what goes in `ANTHROPIC_BASE_URL`.

## Authentication

Send the DreamLake token on **either** header — the relay accepts both:

```
Authorization: Bearer <dreamlake token>
x-api-key: <dreamlake token>
```

Both exist because provider SDKs send the key differently depending on which
variable you set: `ANTHROPIC_AUTH_TOKEN` produces `Authorization`,
`ANTHROPIC_API_KEY` produces `x-api-key`. Either works, so you don't have to
remember which one your client picked.

Your token is verified the same way as every other DreamLake route, and is
**never forwarded to the provider**.

## Errors

| Status | Meaning |
| --- | --- |
| 401 | Missing, invalid, or expired DreamLake token |
| 403 | The deployment restricts models and yours isn't on the list |
| 404 | Unknown provider — call `GET /relay/providers` |
| 503 | That provider has no credentials on this deployment |
| 502 | Upstream unreachable |
| *anything else* | **The provider's own status and body, verbatim** |

That last row matters: a 429 from Anthropic reaches your SDK as a 429 with its
`retry-after` header intact, so your client's normal retry logic works. The
relay never reserializes a provider response, so no field is ever stripped.

## What it does not do

- **No per-user quota.** Any authenticated DreamLake user can spend tokens. A
  deployment can cap *which* models are allowed, not how many calls.
- **No caching, batching, or retries.** Your SDK's own retry logic works.
- **No prompt logging.** Request bodies are relayed, never stored — only
  metadata (user, model, status, duration, token usage) is logged.
- **Not a replacement for hosted chat.** [Hosted pages](/hosted-pages.md) run a
  whole agent container. This is a raw model API for callers running their own
  loop.

## Next steps

    The relay endpoints alongside the rest of the REST surface.

    Where a relayed model call fits in an agentic workflow.

---

Source: https://docs.dreamlake.ai/vault/environment-files

# Environment files in Vault

Store each environment file as one private Vault entry. The file contents, comments and formatting are preserved. These examples use `dreamlake/envs/dev-env` for development and `dreamlake/envs/prod-env` for production.

## Upload

Use a signed-in DreamLake CLI. Run these commands from the directory containing your environment files; replace `.env.dev` and `.env.prod` with your actual filenames.

```bash
# Development
dreamlake vault add --name dreamlake/envs/dev-env --file-name .env --stdin < .env.dev

# Production
dreamlake vault add --name dreamlake/envs/prod-env --file-name .env --stdin < .env.prod
```

`--stdin` reads the complete file without putting its contents in command arguments. `--file-name .env` saves a suggested filename; it does not create a local file. The Vault path and local filename are independent. Dots in Vault selectors identify fields, so the entry names use `dev-env` and `prod-env` rather than `dev.env` and `prod.env`.

Inspect metadata without printing secret values:

```bash
dreamlake vault show --name dreamlake/envs/dev-env
dreamlake vault show --name dreamlake/envs/prod-env
```

## Replace an existing entry

Read its current revision with `show`, then supply that revision explicitly:

```bash
dreamlake vault add --name dreamlake/envs/dev-env --if-match <revision> --file-name .env --stdin < .env.dev
```

Replace `<revision>` with the returned number. A revision mismatch means the entry changed; inspect it before trying again. Use the production path and file to update production.

## Restore

In the destination project directory, run this Python 3 snippet. It fetches the development file without printing its values, creates `.env` with owner-only permissions, and refuses to overwrite an existing file. Retrieval must succeed before the file is created.

```python
import os
import subprocess

data = subprocess.check_output([
    "dreamlake", "vault", "get", "--name", "dreamlake/envs/dev-env"
])
fd = os.open(".env", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "wb") as f:
    f.write(data)
print("Restored .env")
```

For production, change the Vault path to `dreamlake/envs/prod-env`. Keep restored files ignored by Git and let your application's usual dotenv loader read them.

Saving a file in Vault does not load it into your shell or deliver it to a remote run. `vault get --to-envs` on a whole-file entry exports one string; it does not parse dotenv lines into separate variables.

CLI syntax checked with DreamLake `0.23.0`. This guide does not upload any files automatically.

---

Source: https://docs.dreamlake.ai/workflows/cjs-vs-python

# CJS Workflows vs Python Pipelines

  A CJS workflow and a Python pipeline are not two dialects of one idea. They
  share a noun and almost nothing else: one discovers its shape by running,
  the other is read off the source without running. This page puts them side by
  side across eleven axes and then names, honestly, the seven places where one
  of the two does not exist yet.

## Part 1 — the three artifacts

Three separate things in this system are called a workflow. Two of them answer
to `dreamlake workflow`.

| | Artifact | Authored as | Stored as | Executed by |
|---|---|---|---|---|
| **W1** | CJS workflow — a Claude Code JS orchestration script | a `.js` exporting a `meta` literal plus `phase()` / `agent()` / `parallel()` | `Workflow.script` + `WorkflowVersion`, plus run traces | the Claude Code CLI's Workflow tool, locally |
| **W2** | WorkflowSpec v1 — the typed stage/node graph | hand- or agent-authored JSON | a DreamDB dataset; the server holds only `specVersion` / `specMeta` | a `workflow_runtime` worker off a Redis stream |
| **P** | Python pipeline | `.py` with `@dl.pipeline` + `@ls.udf` | `Pipeline.sourceCode` + `PipelineVersion.graph` | nothing — the graph is derived, never run |

W2 is the artifact the [Workflows guide](/workflows.md) and the
[node types reference](/workflows/node-types.md) describe. This page is about the
other two: **W1 against P**, with W2 present only where the comparison needs it.

### Two facts that make this genuinely confusing

**One CLI verb, two file formats.** `dreamlake workflow create` and
`dreamlake workflow update` take `--file <script.js>` and parse a `meta` literal
out of JavaScript. `dreamlake workflow push` takes a WorkflowSpec v1 JSON file
and writes it to DreamDB. Same command group, same workflow name, entirely
different artifact on each side of the flag.

**One record, two version counters.** The `Workflow` model carries both:

- `currentVersionHash` — a twelve-hex hash pointing at a `WorkflowVersion`, and
  a `WorkflowVersion` holds a `script`. That is the **JS** history.
- `specVersion` — a monotonic integer, the latest push counter into the
  workflow's DreamDB dataset, alongside `specMeta`
  (`{ description, stageCount, nodeCount, edgeCount }`). That is the **JSON**
  history.

Nothing keeps them in sync. A workflow can be at `currentVersionHash` `a1b2…`
and `specVersion` 7 with no relationship whatsoever between the two, because
they were written by two different commands describing two different artifacts.

**And a third `push`.** `dreamlake workflow push` also exists in the Python CLI,
with the same `<file> [--name]` shape and byte-identical output — both CLIs
re-serialize the spec at two-space indent so they append to the same dataset.
The TypeScript CLI acknowledges the split in its own error text: its hidden
`workflow append-local` subcommand answers
`no_writer — append-local needs the canonical Python writer (pip install
dreamlake); the TS CLI has no DreamDB writer`. The Python CLI stays the
canonical DreamDB writer, and dreamlake-server spawns it by name for spec
applies.

---

## Part 2 — eleven axes

### 0. What the name means

**W1.** One of three artifacts, and the least documented of them. `dreamlake
workflow` covers W1 (`create`, `update`, `show`, `push-run`, `watch-run`) and W2
(`push`) from the same command group, so the verb alone never tells you which
one you are operating on.

**P.** One artifact. `dreamlake pipeline` means exactly one thing: a Python file
with a `@dl.pipeline` entry point.

### 1. Where the graph comes from

**W1 — a runtime trace.** There is no static DAG for a CJS workflow. Phases and
agents are captured as the run executes; the renderable graph is derived from a
run's `trace` (`phases` + `agents`). Before the first run, only the phase
skeleton exists, built from the current version's `meta.phases`. With no version
at all there is nothing to render. **You cannot know the shape of a CJS workflow
without running it.**

**P — static derivation from source.** The tracer walks the Python AST. It never
imports the module and never executes a line, which is why every UDF body in the
canonical examples is a literal `...` and traces perfectly well. The graph is a
property of the text, available before anything has ever run — and, as Part 4
records, that is just as well, since nothing runs it.

### 2. The unit of work

**W1.** An agent call:

```js
await agent(promptString, { label, phase, schema, effort })
```

The prompt is a string. The options carry the display label, the phase the agent
belongs to, an output schema, and an effort level.

**P.** A decorated function:

```python
@ls.udf(kind="review")
def review_boxes(labels) -> Mask["R", "N"]:
    ...
```

The parameters are the node's input ports; the return annotation is its output
schema.

### 3. Typing of the connection

**W1 — none.** The prompt string *is* the edge. Whatever one agent produced
reaches the next one only because the script interpolated it into the next
prompt. The `schema` option types an agent's **output**, not the connection: it
constrains what that one agent returns and says nothing about who consumes it or
whether the consumer expects that shape.

**P — typed on both ends.** The tracer reads input ports off the function's
parameter list, gives every UDF that returns something exactly **one** output
port (`out`), and reads the return annotation's names into `columns` —
`Tuple["boxes", "classes", "confidence"]` becomes three column names on the
node. A sink UDF with no return annotation gets no output port at all. Every
edge additionally carries `kind: "data" | "mask"`.

### 4. Fan-out

**W1.** An array of thunks:

```js
const findings = await parallel(
  targets.map((t) => () => agent(`Scout ${t} and report`, { label: t, phase: 0 })),
)
```

`targets` is an ordinary JavaScript array, usually parsed out of a previous
agent's output. **The width is computed at runtime.** Nothing before the run
knows whether this is three agents or thirty.

**P.** Call the UDF more than once, or write a comprehension. Each call mints a
fresh node id from the function name — `detect_objects`, then
`detect_objects_2`, then `detect_objects_3`. This is static, and it has a hard
edge: **loops never unroll.** The tracer walks a `for` body exactly once, so

```python
for i in range(3):
    x = refine(x)
```

produces **one** `refine` node, not three. Three calls written out give three
nodes; three iterations of one call give one.

### 5. Fan-in

**W1.** Ordinary array handling, then string concatenation into the next prompt:

```js
const notes = findings.filter(Boolean).map((f) => f.summary).join('\n\n')
await agent(`Synthesize these scout reports:\n\n${notes}`, { phase: 1 })
```

The join is the fan-in. There is no merge construct — the next agent simply
receives a longer prompt.

**P.** Pass several results into one UDF, and one edge per argument lands on that
node. The tracer then labels it: an untagged UDF whose **data** fan-in comes from
two or more distinct non-source nodes is re-kinded `merge`. Only `data` edges
count, and inputs drawn from a `source` node are excluded, so a side input such
as a prompt table does not accidentally promote a stage to a merge.

### 6. State between steps

**W1.** Ordinary JavaScript variables in one module scope. The script is a
normal ES module: `const` bindings hold agent results, and they reach the next
step as **interpolated prompt text**. There is no store, no artifact registry,
and no way to inspect an intermediate other than reading the run trace.

**P — provenance sets.** The tracer tracks, for every Python local, the set of
nodes its data descends from, each tagged `data` or `mask`. When both tags reach
the same node, **`data` dominates `mask`**. Consuming a value in mask position
downgrades its whole provenance. Method calls (`review.all(axis=0)`), subscripts
(`labels[consensus]`) and operators (`~consensus`) **pass provenance through
without creating a node** — they are how a value is reshaped, not a stage of
work.

### 7. Control flow

**W1.** Plain JavaScript `if`. It is untracked and invisible to the trace: the
trace records phases and agents, so a branch that skips an `agent()` call simply
leaves that agent out of the trace, and a branch that fires no `phase()` leaves
no mark at all. You cannot read a CJS workflow's branching structure off its
graph, because the graph is only what happened.

**P.** The tracer walks **both** branches of an `if/else` — an intentional
over-approximation, so every path's nodes appear. A variable assigned in both
branches gets the **union** of the two provenance sets, so a downstream node
connects to both and nothing dangles. The `else` branch walks from the pre-`if`
bindings rather than the `if` branch's, because the branches are independent.
And **the condition is discarded**: `stmt.test` is evaluated in mask role for its
provenance only. The graph shows what a branch might touch, never which way it
went.

### 8. Failure

**W1.** A failed agent yields a falsy entry rather than throwing, which is why
`.filter(Boolean)` is idiomatic on every `parallel` result. That idiom silently
swallows the failure. Partial failure is entirely the calling script's problem
to notice and report; nothing in the runtime stops the workflow because two of
five scouts came back empty.

**P.** The opposite discipline. Any undecorated call inside a `@dl.pipeline`
**raises at trace time**:

```
pipeline calls undecorated function 'to_dataset' — every function called in a
@dl.pipeline must be a @ls.udf / @dl.node (wrap framework helpers like
to_dataset/requeue in a udf)
```

No hidden helpers, no silent passthrough. The one exemption is a `for` loop's
*iterator* expression (`batch(src, n=64)`, `stream(…)`), evaluated leniently so
a structural helper there does not raise; the loop **body** is strict again.

### 9. Execution

**W1.** The Claude Code CLI's Workflow tool runs the script locally and rewrites
a `wf_<runId>.json` run file under the session's `workflows/` directory as it
goes. `dreamlake workflow push-run` and `watch-run` reduce that file and PUT it
to the server, which is how a local run becomes a visible run.

**P.** Nothing executes it. `dreamlake pipeline create --file` stores the source
and the derived graph; that is the entire lifecycle. There is no runner, no
scheduler and no queue on the pipeline side.

### 10. Storage, versioning, renderer

**W1.** `Workflow` (identity, metadata) → `WorkflowVersion` (an immutable
snapshot of `script` plus the parsed `meta`) → `WorkflowRun` (a mutable trace
snapshot, upserted while the run progresses). Rendered as a metro map: phase
bands with agent cards strung along a spine.

**P.** `Pipeline` → `PipelineVersion` (`sourceCode` plus the derived `graph`) →
`NodeState` for runtime status. Rendered by uikit's `` as node
cards joined by typed edges, solid for `data` and dashed for `mask`.

Both version immutably, and both mint the same kind of identifier: a
**twelve-character hash**, `SHA256(id:timestamp:nonce).slice(0, 12)`.

---

## Two real samples

### W1 — a CJS workflow

The `meta` literal and its storage contract are defined by dreamlake-server and
are exact. The `phase` / `agent` / `parallel` bindings come from the Claude Code
CLI's Workflow tool, which is not part of this repository — treat the body below
as the shape of the fan-out, not as a normative signature.

```js file="scout.js"
export const meta = {
  name: 'workflow-feature-scout',
  description: 'Map the five subsystems a feature touches, then synthesize.',
  phases: [
    { title: 'Scout', detail: '5 parallel readers' },
    { title: 'Synthesize', detail: 'one writer' },
  ],
}

export default async function run({ phase, agent, parallel }) {
  await phase(0)
  const targets = ['server', 'cli', 'uikit', 'docs', 'schema']
  const findings = await parallel(
    targets.map((t) => () => agent(`Read the ${t} and report what it owns.`, {
      label: t,
      phase: 0,
      effort: 'medium',
    })),
  )

  await phase(1)
  const notes = findings.filter(Boolean).map((f) => f.summary).join('\n\n')
  return agent(`Synthesize these scout reports:\n\n${notes}`, { phase: 1 })
}
```

> **Warning:** Both the Studio parser and dreamlake-server lift `meta` out of the script text
>   **without executing it** — a balanced-brace scan from the first `{` after
>   `export const meta`, then a constrained recursive-descent read of objects,
>   arrays, strings, numbers, `true` / `false` / `null`, comments and trailing
>   commas. Identifiers, calls and arrow functions are treated as unparseable and
>   skipped, never evaluated. So `name: WORKFLOW_NAME` does not resolve to a
>   string — it resolves to nothing, and the server returns **`400
>   invalid_script`** because `meta.name` must be a non-empty string. The same
>   applies to `meta.description`. `phases` is tolerant by comparison: it defaults
>   to `[]`, non-object entries and entries without a string `title` are dropped
>   silently, and `detail` is kept only when it is a string.

### P — a Python pipeline

```python file="image_object_annotation.py"
import dreamlake as dl
import lakeshore as ls
from dreamlake import batch, requeue, to_dataset
from lakeshore.types import Mask, Tensor, Tuple


@ls.udf(kind="source")
def load_images() -> Tuple["images"]:
    """Pull the batch of images to annotate."""
    ...


@ls.udf
def detect_objects(images: Tensor["N", "H", "W", 3]) -> Tuple["boxes", "classes", "confidence"]:
    ...


@ls.udf(kind="review")
def review_boxes(labels) -> Mask["R", "N"]:
    """R reviewers pass/fail each box."""
    ...


@ls.udf(kind="sink")
def save_dataset(rows):
    to_dataset(rows)


@ls.udf(kind="sink")
def rework(rows):
    requeue(rows)


@dl.pipeline
def image_object_annotation():
    src = load_images()
    for items in batch(src, n=64):
        labels    = detect_objects(items.images)
        review    = review_boxes(labels)

        consensus = review.all(axis=0)       # method call: provenance passes through
        save_dataset(labels[consensus])      # subscript: the mask gate
        rework(labels[~consensus])           # unary op: still the same provenance
```

Read the last three lines against axis 6. `review.all(axis=0)` and `~consensus`
create no nodes — they carry `review_boxes`'s provenance forward with a `mask`
tag. `labels[consensus]` mixes a `data` provenance (the subscripted value) with a
`mask` provenance (the slice), so `save_dataset` ends up with a solid edge from
`detect_objects` and a dashed one from `review_boxes`. That is the whole of
"tapping data off the main stream" in the pipeline model — no sampler function
is involved, because there isn't one.

---

## Part 3 — the CLI, both sides

Neither command group is documented at [/cli](/cli.md) today, so both are recorded
here.

```bash
# W1 — the JavaScript orchestration script
dreamlake workflow create <name> --file <script.js> [--message <text>]
dreamlake workflow update <name> --file <script.js> [--message <text>]
dreamlake workflow show   <name>
dreamlake workflow list

# W1 — run traces, pushed from the local wf_*.json the Workflow tool writes
dreamlake workflow push-run  <name> <wf_*.json>
dreamlake workflow watch-run <name> <wf_*.json> [--interval 5]

# W2 — a WorkflowSpec v1 JSON, NOT the JS
dreamlake workflow push <spec.json> [--name <name>]

# P — the Python pipeline
dreamlake pipeline create <name> --file <pipeline.py>
dreamlake pipeline update <name> --file <pipeline.py>
dreamlake pipeline version list <name>
dreamlake pipeline version show <name> <hash>
dreamlake pipeline node    list <name> <hash>
dreamlake pipeline node    show <name> <hash> <nodeId>
```

Two details worth knowing before you use them.

**`workflow push` takes the file positionally, not the name.** The workflow name
comes from the spec's own `name` field unless you override it with `--name`.
This differs from every other verb in the group, which takes `<name>` first —
another consequence of `push` operating on a different artifact from its
siblings.

**`watch-run` is designed to be backgrounded** alongside the Workflow tool. It
polls the local run file and pushes a trace snapshot on each tick until the file
leaves `running`, then pushes once more so the terminal state lands. Every push
is size-budgeted below the server's body limit and degrades deterministically —
free-text previews are capped first, then log lines, then `result` is replaced
with a size marker. The status, the phase/agent skeleton and the run totals
always survive, because those are what the run page renders. If the terminal
push were dropped, the server-side run would never leave `running` and the
detail page would poll it forever.

---

## Part 4 — the honest gaps

This is the part that makes the page worth writing. Everything above describes
what the two systems *mean*. This describes what is not there.

> **Warning:** The `.py` files above trace correctly and will not import. The shipped
>   `dreamlake` package exports no `pipeline`, no `node`, no `batch`, no `stream`,
>   no `to_dataset` and no `requeue`. The real `udf` signature is
>   `udf(fn=None, *, queue=None, transport="auto", config=None)` —
>   **no `kind=`**. `kind` is notation the tracer reads out of the decorator's
>   keyword arguments; the runtime never sees it. `lakeshore.types` does not exist,
>   so `Mask`, `Tensor` and the string-literal `Tuple` are annotations with no
>   implementation behind them. And the canonical import for the real package is
>   `import dreamlake.lakeshore as dls`, not `import lakeshore as ls`.
>
>   The conclusion follows directly: **those `.py` files are a specification format
>   that happens to be Python syntax.** They work precisely because the tracer
>   parses text and never imports a module. Do not read them as runnable code.

> **Warning:** dreamlake-server calls an external tracer at `PIPELINE_PARSER_URL/trace`. When
>   that variable is unset it falls back to `parsePython()`, an in-process mock
>   that matches only a **bare `@ls.udf` line** — not `@ls.udf(kind="source")` —
>   infers `kind` from whether the function name starts with `tr_`, and returns
>   `inputs: []` and `edges: []`. That is an empty graph with a few disconnected
>   nodes in it. Real graphs require the external `dl_trace` service; without it,
>   a pushed pipeline renders as unconnected cards.

> **Warning:** There is no way to see a CJS workflow's shape without running it, and
>   `meta.phases` does not substitute for one. It is a hand-written label list
>   with **no relationship to the `agent()` calls the script actually makes** —
>   nothing validates that a phase exists for every `phase: n` an agent declares,
>   or that a declared phase is ever entered. It is display metadata that happens
>   to be ordered.

> **Warning:** The edge type system documented at [/workflows/node-types](/workflows/node-types.md)
>   — typed ports, `samples` / `table` / `dataset` / `model` / `metrics`, branch
>   ports, collect ports — applies to **W2 only**. None of it exists for a JS
>   script, where the only connection between two steps is a string that one of
>   them wrote into the other's prompt.

> **Warning:** No `uda`, no permission grants, no `tools` declaration. A "review" step in a
>   pipeline is a UDF with `kind="review"` — an ordinary function node with a
>   cosmetic label, which the renderer draws differently and the tracer treats
>   identically to a transform. The whole `uda` concept, and the grant taxonomy at
>   [/workflows/agent-permissions](/workflows/agent-permissions.md), lives only in W2.

> **Warning:** Neither a CJS script nor a Python pipeline has one. W2 has a real
>   `approval` control node and a matching server endpoint
>   (`POST …/runs/:runId/approve`, which resumes from a checkpoint against the
>   same spec version the run started on). A CJS workflow that needs a human in
>   the loop has to arrange it in JavaScript; a Python pipeline has nowhere to put
>   it, because nothing executes the pipeline in the first place.

> **Warning:** dreamlake-server enqueues a run onto a Redis stream: `XADD` to `WF_QUEUE`,
>   defaulting to `labeling_task`, carrying the full spec inline so the worker
>   never has to read DreamDB. The comment in the route names a `workflow_runtime`
>   worker as the consumer. **No such consumer was found anywhere in this
>   checkout** — not the string `workflow_runtime`, not a reader of
>   `labeling_task`. It may be a separately deployed service. Until that is
>   confirmed, W2's "push it and it runs" story is unproven, and this page will not
>   assert it either way.

---

## Related

    The W2 vocabulary — every node family's inputs, outputs and configuration,
    and the artifact type system on every edge.

    The grant registry uda nodes draw from — domains, verbs, and scopes. W2 only.

    The Python authoring vocabulary, one construct per page, each with a live
    node view.

    The rest of the `dreamlake` command surface.

---

Source: https://docs.dreamlake.ai/envs

{/* FigEnv* come from the site-wide mdxComponents map in site.config.ts —
    no import needed. */}

# Envs

  An env is a **simulation environment** — a directory holding one MJCF scene
  or one URDF robot, plus its assets — that you push from the terminal and
  open as a live, interactive 3D page in the dashboard.

## Browsing in the app

`/<namespace>/profile?tab=envs` and `/<namespace>/envs` reuse the same
Environments catalog. Your own namespace and organizations you belong to show
resources and actions allowed by your permissions. Signed-out visitors and
signed-in visitors to other namespaces see public resources only, without
creation or modification controls. Profile uses an avatar rail; the application
uses resource navigation for the namespace in the URL.

Your own Envs catalog also includes recent environments from your organizations. Public environments and valid Env share-token links open without sign-in.

The application sidebar shows the resource owner's avatar and links, including
for anonymous public readers. Your signed-in identity and personal/organization
switcher are separate from that owner. See [Profiles and workspaces](/workspaces.md).

The detail header returns anonymous readers to `/<namespace>/profile?tab=envs`
and signed-in readers to `/<namespace>/envs`. Details opened inside a project
retain their return-to-project action. There is no extra sign-in navigation bar.

## Generate with chat

Members can also create and edit envs from the browser, by prompting an
embedded agent that runs the
[scene-generation skill](/scene-generation/quickstart.md). The chat panel
ships with the web app — it appears once an app deployment that includes
env chat reaches your server:

1. In your namespace's Envs catalog, click **+ new env** — in the page
   header next to the Environments/Libraries switch, and offered again by
   the empty catalog's placeholder. One click opens a fresh *draft* with an
   auto-minted name (`env_xxxxxx`) — no dialog, nothing to type first, and
   nothing exists on the server until the agent's first successful push.
2. The draft opens straight into the **intro composer** — describe the
   scene there; the agent sources assets, measures, composes, validates,
   and publishes with `dreamlake env push`.
3. On the first successful push the draft becomes the **saved preview** —
   the interactive viewer on the pushed version, chat still beside it.
4. **Follow-up prompts create new versions** of the same env. The viewer
   tracks the latest; picking an older version in the header pins it, and
   a "vN available" button jumps back to latest.
5. Editing an **existing** env works the same: open its page as a member
   and prompt the chat panel next to the viewer. Read-only viewers, share
   links, and anonymous visitors never see the chat.
6. To grow a **new** env out of an existing one, start from the catalog,
   not from the source env's page — the chat edits the env whose page it
   sits on. Click **+ new env** for a fresh draft, then ask it to start
   from the source env at a pinned version; the source env keeps its own
   versions, untouched (details in the
   [Quickstart](/scene-generation/quickstart.md)).

The env chat opens in **Auto** permission mode, so one prompt can carry
through the whole workflow — the agent runs the scene tools and
`dreamlake env push` without per-command approval. The composer's
permission control still works as usual: switch to **Ask permissions** or
**Plan mode** for a read-only conversation (the agent inspects and answers
but does not generate or push), and switch back to Auto when you want it
to build. A read-only choice is respected for as long as you keep it — the
page sets the mode only once, on open, and never overrides your selection.
Env membership still governs what a push may touch: the mode routes what
the agent may *run*, not what your account may *write*.

The install-and-use guide for the same workflow from a local agent —
ordinary create / edit / reuse prompts included — is the
[Scene Generation Quickstart](/scene-generation/quickstart.md).

**Troubleshooting the preview when running the app from source.** If the
viewer panel shows an error fallback instead of the scene and the console
logs `R3F: Hooks can only be used within the Canvas component!`, that is a
dev-server fault, fixed in the app source on 2026-09-29: the dev server
could load two copies of the 3D renderer and which copy a session got
depended on load order — so the crash appears and disappears between
checkouts, and its absence on one run proves nothing. If you see it, your
source checkout predates the fix: update to a checkout that carries it and
restart the dev server. In that source's dependency graph the production build
resolves a single renderer copy, which bounds the fault to the dev server
— an inference about the current source only, not an audit of anything
previously deployed. Count the scene as loaded only when its actual
geometry is visible and the simulation controls respond; that console
error is failure evidence, and a page shell or a bare `<canvas>` is not
success — the canvas can mount and then unmount again while the model
loads.

## Push one

```bash
dreamlake env push ./cassie
```

The entry file is auto-detected — the one root-level `*.xml`/`*.mjcf`
containing `<mujoco>`, or (with no MJCF around) the one root-level `*.urdf`
containing `<robot>`, which also sets the env's type to `urdf`. Relative
`<include>`, `<mesh file="…">` and `package://` references keep working
exactly as they do on disk. The CLI prints an **open link**.

| Flag | What it does |
|------|--------------|
| `--entry scene.mjcf` | Pick the entry when there are several candidates |
| `--type isaaclab` | Simulator family — stored and pullable; `mujoco` and `urdf` have viewers |
| `--visibility public` | Anyone can open the viewer, no login |
| `--name`, `--title` | Identity (defaults to the directory name) |
| `--thumbnail cover.png` | Set the gallery cover yourself (PNG ≤ 512 KiB) — see [Thumbnails](#thumbnails) |

## Version it — only changes upload

Push the same env again and you get **v2**. Files are content-addressed, so
unchanged meshes and textures are never uploaded or stored twice — the CLI
tells you exactly what moved:

```txt
✓ pushed you/cassie v2 — 20 files (1 uploaded 12.4 KB, 19 reused)
```

## Drive it

For a **mujoco** env the viewer is a real simulation, not a screenshot: the
engine runs on load, and the toolbar gives you **play / pause / reset /
speed**.

- **Sliders** — every actuator (`ctrl`, with its real range) and every
  hinge/slide joint, straight from the model.
- **t = 0 is your authored initial state** — when the model defines a
  `<keyframe>`, the viewer opens at (and **reset** returns to) keyframe 0,
  including its `ctrl`; without one it uses the compiled defaults (qpos0).
  *Keyframe honoring is a source change awaiting the next viewer
  deployment: the prior source baseline (and its wasm runtime) opens at
  qpos0 regardless of keyframes, so until the deploy — verify in the app —
  expect qpos0.*
- **⌥ / Alt + drag** — pull any body with a mass-scaled spring force, like the
  MuJoCo app's perturbation.
- **files** — the version's full file listing, entry highlighted.
- The first member visit renders the gallery **thumbnail** — see
  [Thumbnails](#thumbnails) for how the angle is chosen and how to control it.

A **urdf** env opens as a poseable robot instead — no physics, pure
kinematics: every non-mimic revolute / continuous / prismatic joint gets a
slider with its real limits, **dragging a link in the scene rotates its
joint directly** (orbit pauses while you hold it), and **reset** returns the
pose to zero. Meshes referenced as relative paths or `package://` URIs
resolve against the pushed directory.

## Thumbnails

The env grid's cover image is rendered in the browser the first time a member
opens a new version: a fixed 16:10 PNG with a **transparent background**, at
the scene's initial (t=0) pose — physics is held until the capture, so the
cover shows the authored t=0 state (see [Drive it](#drive-it)), not half a
second of free fall.

The camera angle is chosen from the scene itself, in priority order:

1. **A camera named `thumbnail`** — add one to your MJCF and the cover (and
   the viewer's opening shot) is exactly that camera:

   ```xml
   <worldbody>
     <camera name="thumbnail" pos="1.6 -1.8 1.4" xyaxes="0.75 0.66 0 -0.28 0.32 0.9"/>
     …
   </worldbody>
   ```

2. **The first `<camera>` in the model** (including `<include>`d files) —
   scenes authored with a hero camera need no rename.
3. **The free-camera stance MuJoCo's own viewer would use** —
   `<visual><global azimuth="…" elevation="…"/></visual>` plus
   `<statistic center="x y z" extent="…"/>` when authored. This is the
   cheapest lever: two lines, and the cover matches what you see in
   `simulate`:

   ```xml
   <statistic center="0 0 0.7" extent="1.2"/>
   <visual>
     <global azimuth="120" elevation="-20"/>
   </visual>
   ```

4. **A geometry fit** — bounding sphere of all geoms (ground planes
   excluded), from a three-quarter angle. URDF robots always use this fit.

Two overrides beat all of the above:

- **The camera button in the viewer toolbar** (members only, latest version):
  orbit to any angle and click it — that exact view becomes the cover, and
  the angle is remembered, so **future versions auto-capture from it** too.
- **`dreamlake env push --thumbnail cover.png`** stores your own image
  (≤ 512 KiB PNG) and marks it manual, so the viewer won't overwrite it for
  that version. Works on a no-change push (thumbnail-only update).

## Pull it back

```bash
dreamlake env pull cassie          # latest → ./cassie/
dreamlake env pull cassie@1 -o v1  # any version
```

Every file is verified against its content hash on the way down — the
directory you get is byte-identical to the one that was pushed.

## Env layers

An env can also be **composed from other envs**. A layer stack
(`dreamlake.layers.json`) is an ordered list of **ops** — one flat object
per line, in the vocabulary of vuer's imperative updates — and
materializes into an ordinary `mujoco` env. No layer has a special role,
and later ops win; swapping the gripper is editing one line and
re-pushing. The pushed version carries both the flat artifact (what every
viewer and SDK reads) and the pinned stack, so any composed env can be
reopened, edited, and recomposed later.

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "layers": [
    { "tag": "Merge",  "src": "you/kitchen" },
    { "tag": "Attach", "src": "you/sharpa-right", "key": "right",
      "at": "world", "pos": [0.45, -0.12, 0.30], "joint": "free-anchored" },
    { "tag": "Update", "key": "obj/mug", "pos": [0.30, 0.10, 0.02] },
    { "tag": "Remove", "key": "body:fixture/plant" }
  ]
}
```

```bash
dreamlake env compose          # materialize ./dreamlake.layers.json locally
dreamlake env push <out-dir>   # push artifact + pinned stack as one version
```

| op | what it does |
|----|--------------|
| `Merge` | union the env's MJCF into the stack — a same-name collision is an error |
| `Attach` | graft the env's subtree at a target under the identity root `key` (`right` makes `right:palm`), with a mount pose and joint mode |
| `Update` | inline sparse opinions: `key` addresses one element, every other prop is an MJCF attribute — nothing else is touched |
| `Remove` | delete the addressed element and its subtree — drop the line and it's back |
| `Patch` | `Update`-style opinions from a sparse-MJCF file or env, for big opinion sets |

`src` is one string: `ns/name[@v]` is a registry env (unversioned floats),
a `./`-prefixed path is a local directory or file.

> **Note:** Materialization is a real MuJoCo build, so `dreamlake env compose`
>   delegates it to the engine in **dreamlake-py** — install it with
>   `pip install "dreamlake[compose]"` (Python + MuJoCo) on the composing
>   machine. Push / pull / list need no Python.

Every field, the exact semantics, and six annotated stacks:
[Env Layers Reference](/envs/layers.md).

## Under the hood

Uploads go straight to storage with short-lived scoped credentials, and reads
are presigned URLs — **env bytes never pass through the API server**. The
read side is two plain REST calls (`…/versions` and `…/versions/:v`), so any
HTTP client can list and download an env without special tooling.

## Delete it (safely)

```bash
dreamlake env delete cassie              # soft delete (restorable)
dreamlake env restore cassie             # bring it back
dreamlake env delete cassie --permanent  # erase storage — no undo
```

## Let Claude do it

Add the [envs skill](https://github.com/dreamlake-ai/dreamlake-skills),
point at a repo, and say *"push the MuJoCo scenes in here to DreamLake"*:

```bash
git clone https://github.com/dreamlake-ai/dreamlake-skills.git ~/dreamlake-skills
mkdir -p ~/.claude/skills
ln -s ~/dreamlake-skills/dreamlake-envs ~/.claude/skills/
```

Update with `git -C ~/dreamlake-skills pull --ff-only`. If a skill already
exists, preserve local edits before replacing it with a symlink.

The `dreamlake-envs` skill does the part that isn't a single command:
extracting a **self-contained directory** from a scene that references
meshes outside itself (collecting the robot folders, rewriting the relative
paths), verifying the result still compiles before pushing, and running the
pull-back round-trip check after.

## Next steps

Recorded teleop episodes don't live here — they play back inside
**sources**, each dataset carrying its own model snapshot, with the env
itself unchanged: [visualize a source](/sources.md).

    One skill install, then build / edit / reuse scenes with ordinary
    prompts — locally or from the env page's chat.

    The `dreamlake.layers.json` contract — merge / attach / override, field
    by field, with annotated stacks.

    Every flag — names, types, entries, visibility, limits.

    The REST endpoints behind push, versions, and presigned reads.

---

Source: https://docs.dreamlake.ai/vault/shared-scopes

# Organization and team vaults

In the Vault dashboard, use **Save in** to choose Personal, an organization, or a team before creating an entry. The selector lists organizations you belong to and teams where you are a direct member. Personal remains the default on your own profile.

Organization members can save and read organization entries. Team entries require both organization membership and direct team membership. Team visibility, organization ownership, and membership in a parent team do not by themselves grant access to team secrets. Manage membership through the existing organization and team settings.

Each scope has separate storage. Identically named organization and team entries remain independent. Changing the selector opens another vault; it does not move or share existing entries. Leaving the organization or team removes access on subsequent requests. Deleting an organization, team, or its namespace also removes access.

Shared vaults support entry creation, metadata listing, reading, replacement, retirement, restoration, and write-outcome recovery. Access keys, OTP generation, remote setup, host-credential bindings, and encryption-key administration remain personal-only. Existing CLI and SDK commands continue to use the personal vault by default.

The API selects a shared scope with `X-Vault-Scope: org:<organization-id>` or `X-Vault-Scope: team:<team-id>` on every request. Authenticated account sessions can discover their available scope IDs and entry prefixes through `GET /v1/vault/scopes`. Omitting the header selects the personal vault. The server validates current membership rather than trusting the supplied scope or entry path.

---

Source: https://docs.dreamlake.ai/workflows/node-types

# Workflow Node Types

  A workflow is a spine of ordered stages; typed member nodes fan out from
  their stage and connect through typed data edges. This page defines every
  node family and the data types edges can carry — rendered with the real
  canvas components.

The vocabulary is grounded in established systems: the artifact type system
follows Kubeflow Pipelines v2 and Flyte, control flow follows BPMN 2.0 and
the workflow control-flow patterns literature, and samplers use statistical
naming with Spark/SQL parameter conventions.

## Stage

A **stage** groups the work of one phase and is rendered as a node on the
spine. Stages are **hubs, not barriers**: work converges into a stage node
and fans out to its members, but data edges may cross stage boundaries
freely. Stage order (the array order in the spec) is the spine.

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | `^[a-z0-9][a-z0-9_-]{0,63}$`, unique |
| `title` | string | display name |
| `detail` | string? | one-line description |

## Compute (UDF)

A **compute** node runs a user-defined function on Lakeshore. The
`provider` block follows the Lakeshore provider schema: a **launcher
class** (`SSH` · `SLURM` · `EC2` · `GCE` · `Kube`) or a named server-stored
provider, plus per-machine RunConfig fields.

| Field | Type | Notes |
| --- | --- | --- |
| `compute.udf` | string | UDF reference, e.g. `pipelines.bimanual_filter` |
| `compute.params` | object? | static UDF arguments — small inline values are node **parameters**, never port data (the KFP/Snakemake split) |
| `compute.provider` | ProviderRef? | `provider` (named) XOR `launcher` + `kwargs`; per-machine: `instance_type`, `image`, `partition`, `resources`, `runner` |
| `compute.dispatch` | `direct` \| `daemon` | how the launch happens; defaults per launcher |
| `execution` | ExecutionPolicy? | `retry {max_attempts (1 = no retry), retry_on, backoff {initial, factor, max}}`, per-attempt `timeout`, `cache {enabled, version}` |

Secrets in provider kwargs must use `{"$secret": "name"}` markers — never
inline credentials.

## UDA (User-Defined Agent)

A **uda** node runs a remote agent. Field names follow agent-framework
conventions (OpenAI Agents SDK, Claude Agent SDK, A2A):

| Field | Type | Notes |
| --- | --- | --- |
| `uda.instructions` | string | the system prompt (fixed persona/behavior — distinct from any per-run input) |
| `uda.description` | string? | *when to delegate* to this agent (routing metadata) |
| `uda.model` | string? | model id |
| `uda.tools` | string[]? | tool grants by name — tools are **not** permission strings |
| `uda.permissions` | string[] | data/resource grants — see [Agent Permissions](/workflows/agent-permissions.md) |
| `uda.max_turns` | number? | turn budget |
| `uda.output_schema` | object? | JSON Schema for the structured final output |
| `uda.provider` XOR `uda.queue` | ProviderRef / string | where the agent runs: a provider/host, or a Lakeshore queue |
| `execution` | ExecutionPolicy? | retry + timeout only — **`cache` is forbidden on agents**: agent runs are non-deterministic; caching one replays a stale answer |

## Sampler

Sampler strategies use statistically correct names. The result of
`bernoulli` is **probabilistic in count** — that is what SQL
`TABLESAMPLE BERNOULLI` and Spark `df.sample(fraction)` actually do.

| Strategy | Parameters | Semantics |
| --- | --- | --- |
| `bernoulli` | `fraction` ∈ (0, 1], `min_size?`, `seed?` | each item kept independently with probability `fraction`. `min_size` is a DreamLake extension: if `fraction·N < min_size`, degrade to an exact-size random sample |
| `random_n` | `size`, `with_replacement? = false`, `seed?` | exact-size simple random sample (reservoir sampling is the streaming implementation) |
| `stratified` | `stratify_by`, `fraction?` or `fractions?` (per-stratum map), `min_size?`, `seed?` | per-stratum sampling, Spark `sampleBy` shape |
| `first_n` | `size` | head/LIMIT — deterministic and order-dependent; **not** a statistical sample |

**Signature**: samplers take exactly one input, restricted to the
collection-like types (`samples` · `table` · `directory`), and are
**type-preserving** — the output port is derived with the same type (a sample
of a clip collection is a clip collection).

**Determinism**: identical input + identical `seed` ⇒ identical sample
(SQL `REPEATABLE` semantics). Absent seed ⇒ non-reproducible (the run records
the effective seed).

## Control flow

| Type | Out ports | Semantics |
| --- | --- | --- |
| `condition` | `true: T`, `false: T` | binary exclusive choice (`expression`) |
| `switch` | one per case + **required `default`**, all `T` | n-way exclusive choice (WCP-4); first matching case wins; `default` keeps routing total |
| `loop` | `out: T` | `mode: 'while'` — condition-bounded, `until` + `max_iterations` **required** (no unbounded loops); `mode: 'foreach'` — collection-driven (`over`, `max_concurrency`) |
| `approval` | `out: T` | human gate with Argo-suspend semantics: pauses until a decision; timeout without decision ⇒ `error`, **never auto-approve** |

Control nodes are **type-preserving pass-throughs**: every derived out port
carries the input port's type `T`.

Plain fan-out and fan-in are **implicit in edges** — there are no
AND-gateway nodes. An input port accepts **one inbound edge** by default;
fan-in is either a `collect: true` port (ordered collection of same-type
producers) or the XOR-merge exception (branches of the same condition/switch
may share a target port, since at most one fires).

## Edge data types

Every port carries a type from a closed **artifact lattice**. `artifact`
is the root and doubles as "any": any subtype is accepted where `artifact`
is expected.

| Type | Meaning |
| --- | --- |
| `artifact` | root — compatible with everything |
| `file` / `directory` | opaque blob, single vs multipart; format is metadata, not more types |
| `table` | schema-carrying tabular data (a *shape*) |
| `dataset` | a versioned data *product* — shards + manifest |
| `model` | trained model / checkpoint |
| `metrics` | evaluation metrics |
| `samples` | DreamLake domain type — an addressable collection of media samples / episodes |

Incompatible connections are flagged on the canvas before anything runs.
Small inline values (strings, numbers, JSON config) are **node
configuration**, not edge data — a type never exists on both sides of the
parameter/artifact boundary.

## Run states

During a run, each node carries a state — `idle` · `queued` · `progress` ·
`done` · `error` · `skipped` — tinting the same card. Agent instances fan
out under their uda node:

## The canvas

Stages are hubs the work flows through — members fan out from their stage
node and converge into the next. Two orientations, one card style:

---

Source: https://docs.dreamlake.ai/libraries

# Asset Libraries

  A **library** is a collection of reusable assets — MuJoCo models, URDF
  robots, meshes, textures, or any files at all — stored exactly as you pushed
  them and searchable per asset. Find a model, preview it in 3D, download just
  its files, and drop them into your own scene.

Libraries exist for the *"I need a mug for this scene"* problem: scene
generation feeds on big open asset repos (Google Scanned Objects is 1,030
models across ~36,000 files; MuJoCo Menagerie is 88 robots), and what you
want from them is never the repo — it's **one asset**, found by name or
meaning, with all of its files and none of the rest. Your own models come
first: a library is where your team's robots and props live; the curated
mirrors of open repos are a convenience on top.

Two ideas make everything below fall out naturally:

1. **Your directory is the format.** A library source is your files plus one
   *optional* `dreamlake.yml`. There is no manifest to write and no hash to
   compute — `push` discovers assets by convention and generates every piece
   of bookkeeping itself.
2. **Files are stored verbatim.** The original relative path *is* the storage
   key. Nothing is rewritten, rehashed into opaque blobs, or wrapped — so a
   pull is byte-identical and an incremental push only uploads what changed.

Everything generated — the wire manifest, rendered thumbnails, search
embeddings — lands in a reserved `.dreamlake/` area in platform storage,
never in your directory.

## Browsing in the app

Libraries share the **Environments** surface: `/<namespace>/envs` has an
`Environments | Libraries` segment switch (`?tab=libraries`); there is no
top-level Libraries nav entry, and `/<namespace>/libraries` redirects to that
tab. A library card opens `/<namespace>/libraries/<name>` — a filterable grid
of its assets, thumbnails only, no live 3D. Clicking a card does not navigate:
the asset opens as a resizable panel beside the grid at `?asset=<id>`, so
scroll position and filters survive. That URL is shareable and loads the panel
directly.

`/libraries` is the global search page: it lists every library you can see
(public ones plus your own), and searches across whichever of them you select.

Visibility works like envs: libraries are **private by default**, members see
everything in their namespaces, everyone else sees `public` libraries only,
and a private library can be opened through a `?share=<token>` link. Hidden
and missing look identical from outside (404) — private names are not
probeable.

## Your directory is the format

A pushable library is any directory. The conventions:

```
menagerie-lib/
  unitree_go2/          ← one top-level directory = one asset, id "unitree_go2"
    scene.xml           ←   entry point, auto-detected (MJCF scene)
    go2.xml
    assets/…            ←   everything inside belongs to the asset
  aloha/                ← another asset
  turntable.glb         ← a loose top-level file = a single-file asset
  dreamlake.yml         ← optional curation metadata (below)
```

- **One top-level directory = one asset.** The directory name is the asset
  `id` (path-safe: `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$`) — it is what search
  returns and what `pull --asset` downloads. Every file inside belongs to the
  asset.
- **Loose top-level files become single-file assets.**
- **Kind, format and entry are detected**, first match wins: `mjcf` (an
  `.xml` containing `<mujoco`), `urdf` (a `.urdf`, or an `.xml` containing
  `<robot`), then the two compressed-splat *directory* layouts — **SOG**
  (a `meta.json` beside its `means_l.webp` / `means_u.webp` planes) and
  **SOG-LOD** (a `lod-meta.json`), which land as `kind: splat` with
  `format: sog` / `lod` — then the single-file rules `mesh`
  (`glb` `gltf` `obj` `stl`), `splat` (`ply` `splat` `spz` `ksplat`),
  `image` (`png` `jpg` `jpeg` `webp`). Anything else is a plain `file`
  asset. For MJCF it prefers `scene*.xml` as the entry and exposes the
  alternatives (scene vs. bare robot) as entry points — the switcher you see
  in the preview. Kind only picks the viewer; uploading, searching, and
  downloading are kind-agnostic.
- **A shipped `thumbnail.*` or `preview.*`** (png/jpg/jpeg/webp) directly at
  the asset root becomes that asset's thumbnail, no `dreamlake.yml` needed.

> **Warning:** `mesh`, `splat` and `image` fire only when the asset contains **exactly
>   one** file of that family — two `.ply` files fall through to `file`. (The
>   families are counted separately, so a `thumbnail.png` beside one `.ply`
>   does not spoil the splat count.) The multi-file splat layouts are the
>   exception: SOG and SOG-LOD directories are recognized by convention, so
>   they need no `dreamlake.yml`. SOG is content-checked, not name-checked — a
>   `meta.json` without the plane files, or one that is not a splat
>   descriptor, stays a plain `file`.

An asset is one *logical* thing — a model with its meshes, textures and
collision geometry, or a single file.

### `dreamlake.yml` — optional curation

Zero-config push works with no metadata at all. One optional `dreamlake.yml`
at the root adds what the CLI cannot infer — every key is optional:

```yaml file="dreamlake.yml"
library: # identity for the catalog card
  title: MuJoCo Menagerie
  description: High-quality MJCF robot models curated by Google DeepMind.
  provider: Google DeepMind
  homepage: https://github.com/google-deepmind/mujoco_menagerie
  license: Apache-2.0 # library-wide default, per-asset overridable
  tags:
    - robots
    - mujoco
  upstream:
    repo: https://github.com/google-deepmind/mujoco_menagerie
    commit: abc123…

discover: # override the discovery conventions (globs, * and **)
  assets:
    - "*" # which top-level entries become assets (default)
  exclude:
    - "docs/**" # never assets, never uploaded

defaults: # category / license / tags only; tags merge, the others fall back
  category: robot

assets: # per-asset overrides, keyed by asset id
  unitree_go2:
    title: Unitree Go2
    description: Quadruped robot with detailed collision geometry.
    category: quadruped
    tags:
      - quadruped
      - unitree
    license: BSD-3-Clause
    attribution: "© Unitree Robotics" # required credit line (CC-BY etc.)
    kind: mjcf # override detection (kind / format / entry)
    entry: unitree_go2/scene.xml # override the detected entry
    entryPoints:
      scene:
        kind: scene
        file: unitree_go2/scene.xml
      go2:
        kind: robot
        file: unitree_go2/go2.xml
    thumbnail: unitree_go2/go2.png # your own image instead of a render
```

Per-asset overrides also accept `files:` globs to reshape which files belong
to an asset. Paths are relative to the library root. `dreamlake.yml` is a
normal source file — it is pushed, pulled, and versioned with your tree.

You never write hashes, sizes, or file inventories: that is the wire
manifest's job, and the CLI generates it at push time (see
[Under the hood](#under-the-hood)).

### Start from a known repo

`dreamlake-py` ships importers that turn well-known repo layouts into a clean
source directory — the asset files plus a generated `dreamlake.yml`, nothing
else:

```bash
# MuJoCo Menagerie — 88 robots, scene/robot entry points, per-model licenses
python -m dreamlake.assets_tools.import_menagerie \
  ~/Code/asset_library/mujoco_menagerie ./menagerie-lib \
  --subset aloha,agility_cassie,unitree_go2

# Google Scanned Objects (mujoco_scanned_objects mirror) — 1,030 household objects
python -m dreamlake.assets_tools.import_mujoco_scanned_objects \
  ~/Code/asset_library/mujoco_scanned_objects ./gso-lib
```

Importers only prepare source. Thumbnails and embeddings are push-time steps
now — the flags below.

## Push it

```bash
dreamlake library push ./menagerie-lib --namespace my-team --library menagerie
# ✓ my-team/menagerie revision 1 — 197 uploaded, 0 unchanged, 0 removed
```

That is the whole workflow: the CLI discovers the assets, detects kinds and
entry points, applies `dreamlake.yml` if present, hashes your files (with a
local cache, so re-pushes don't re-read an unchanged tree), builds the wire
manifest, and uploads. In order:

1. It fetches the remote manifest and **diffs by sha256** — only new or
   changed files upload. The server mints presigned upload URLs in batches
   (≤ 1,000 files / 10 GiB per batch, looped); bytes go straight to storage,
   never through the API server.
2. It calls **register**: the server validates the uploaded manifest, bumps
   the library `revision` (a compare-and-swap counter — concurrent pushes
   lose cleanly with a 409 and retry), and updates the catalog row.
3. After register, the server **reconciles** storage: any file outside the new
   manifest is deleted server-side. Clients never hold delete permission —
   storage always equals exactly what the manifest declares.

Re-push after deleting one model from a 1,030-model library and the plan
reads: *2 to upload, 171 unchanged, 24 removed* — seconds, not a re-upload.

Push treats your directory as the source of truth — which matters once a
library is also edited remotely ([add / rm](#add-or-remove-one-asset)). If
the remote has moved since this directory last registered **and** the plan
would delete assets, push stops and lists exactly what it would delete:
pull to merge, or re-run with `--force` to delete them deliberately. A push
that only adds or updates files never triggers the guard.

Flags that add work at push time:

```bash
dreamlake library push ./menagerie-lib --thumbnails --embed
```

- `--thumbnails` renders 640 px WebP previews of your models (offscreen
  MuJoCo rendering with auto-framing). Renders land as **platform artifacts**
  under the reserved `.dreamlake/` area in storage — your directory stays
  untouched. Search cards and the library grid live on these — ship them. A
  re-push without the flag carries the existing thumbnails forward; an asset
  that already has a thumbnail (its own `thumbnail.*`/`preview.*` file, or a
  `thumbnail:` in `dreamlake.yml`) uses that instead of a render.
- `--embed` computes the vectors that turn on
  [semantic search](#search-it) — image vectors of the thumbnails, text
  vectors of the metadata. It requires `--thumbnails` in the same push
  (the image vectors embed the fresh renders). Vectors are content-hash
  cached locally, so re-running after an edit only re-encodes what changed.
- `--model <name>` picks the encoder `--embed` uses: `siglip2` (the default,
  and the only space DreamLake searches), `clip` (legacy), or a raw
  `open_clip` model name. Omit it and the Python tool decides, which is where
  `DREAMLAKE_EMBED_MODEL` is still read. Passing it without `--embed` is an
  error.
- `--dry-run` prints the plan (uploads, unchanged, removals) and exits;
  `--verify` re-hashes every local file and re-downloads the remote
  manifest, bypassing both local caches. `--force` overrides the drift
  guard, and `--json` puts a machine-readable result on stdout.

Both `--thumbnails` and `--embed` shell out to the `dreamlake` Python
tooling — `pip install "dreamlake[compose]"` for rendering (MuJoCo),
`pip install "dreamlake[embed]"` for vectors. Everything else is pure CLI,
and a missing interpreter is a warning, not a failed push.

> **Warning:** The renderer loads models in MuJoCo, so `mjcf` assets are the only ones it
>   can render today; `mesh`, `splat` and `image` assets are skipped and
>   counted in the push summary's `skipped`. Put a `thumbnail.png` (or
>   `preview.png`) at the asset root, or name one with `thumbnail:` in
>   `dreamlake.yml`. This matters beyond the grid: `--embed` builds its image
>   vectors from thumbnails, so an asset without one contributes text vectors
>   only.

> **Warning:** Search always sees the latest revision, and pulls fetch the current files.
>   When an asset matters to a scene, pull it and vendor it into the scene —
>   the platform keeps libraries current, not archival.

## Search it

Three scopes, one behavior:

```bash
# inside one library
curl "$API/namespaces/my-team/libraries/menagerie/search?q=cassie&category=biped"

# across chosen libraries (the /libraries page and the CLI use this)
curl "$API/library-search?q=gripper&libraries=my-team/menagerie,acme/gso&kind=mjcf"

# from the terminal — scope defaults to every library you can see
dreamlake library list --all
dreamlake library search "coffee mug" --library fortyfive/scanned-objects
```

Keyword search scores `title`, `tags`, `id` and `description` with filters on
`category` / `kind` / `license` / `tag`. Empty query = browse mode (filters
still apply). With no `--library`, the CLI searches the 50 most recently
updated libraries you can see; the API caps an explicit list at 50 too.

Two public libraries to try: `fortyfive/menagerie` (68 MJCF robots) and
`fortyfive/scanned-objects` (129 household objects).

**Semantic search** turns on per library when you push with `--embed`:

```bash
dreamlake library push ./menagerie-lib --thumbnails --embed
#   vectors: .dreamlake/vectors.json + .dreamlake/vectors.f32 (open_clip/ViT-B-16-SigLIP2/webli, 768-d)
```

The embeddings are SigLIP2 image vectors of the thumbnails and text vectors
of the metadata (768-d), stored as a platform artifact alongside the
manifest. At query time the server embeds your query text in-process — an
fp16 ONNX SigLIP2 text tower ships inside the server, no external service —
then fuses vector similarity with the keyword ranking and marks the response
`semantic: true`. Because SigLIP2 is multilingual, non-English queries work:
keyword tokenization is ASCII-only, so a Chinese query carries no keyword
tokens and ranks by vector alone.

Semantic ranking is used only when the library's sidecar was produced by the
**same model** as the active query encoder — `open_clip/ViT-B-16-SigLIP2/webli`.
The sidecar records its model id and the server compares it; a mismatch falls
back to keyword-only rather than scoring vectors from a different space. Both
SigLIP2 and the retired CLIP encoder are 768-d, so dimensionality cannot catch
this — only the model id can.

You do not normally have to think about it: `dreamlake` ≥ 0.25.0 embeds with
SigLIP2 by default, the push prints the encoder it actually used (the line
above), and a sidecar outside the query space warns loudly while still
completing the push. When you do want to be explicit, `--model siglip2` pins
it. `--model clip` is the legacy escape hatch — useful if you embed for
something other than DreamLake, and keyword-only here by design.

That makes `semantic` a three-way answer, on a library row and in
`library info`: `true` (vectors present and compatible), `false` (no
sidecar, or one the active encoder will not use), `null` (registered before
the flag existed). Searching never fails because embeddings are missing or
mismatched — it quietly degrades, so check the flag rather than inferring it
from result quality.

Search hits return `namespace/library/assetId` plus a presigned thumbnail,
the effective `license`, and two pull-cost signals: `files` (`{count,
bytes}`) and `digest`, a `sha256:…` over the asset's sorted path/hash lines.
The digest identifies the exact file set — equal digests mean a pull would
transfer nothing — so a hit alone is enough to decide whether to download.
In the terminal each hit is one grep-friendly line — `ns/lib/asset  score
kind  license  — description` — closed by a `12 of 40 hits · semantic on`
footer; `--license` and `--offset` complete the filter set, and `--json`
returns the raw response:

```bash
dreamlake library pull acme/gso --asset Cole_Hardware_Mug_Classic_Blue -o ./scene/assets
```

## Check before you download

Two commands answer questions a download shouldn't be the way to ask:

```bash
dreamlake library info acme/gso                     # the library's shape
dreamlake library info acme/gso --asset Cole_…      # one asset's decision card
dreamlake library stat acme/gso --asset Cole_… -o ./scene/assets
```

`info` reads the catalog row and the manifest — nothing else — and prints
either the library summary (asset and file counts, total size, kind /
category / license counts, whether semantic search is on) or one asset's
card: entry points, file count and bytes, effective license, `meta`, and a
content `digest` that identifies the asset's exact file set.

Both commands keep the downloaded manifest in a local cache keyed by the
library's `revision`, so repeated checks against an unchanged library cost
one small catalog read and no manifest download — which is what makes them
practical against a 60 MB manifest. `--verify` re-downloads.

`stat` compares that manifest against a local directory and answers with
exactly one of `up-to-date` (exit 0), `stale: 2 files changed, 1 missing —
pull would fetch 812 KB`, or `absent: full pull = 34 files, 4.8 MB` (both
exit 1) — without transferring a byte. The exit code makes it scriptable:

```bash
dreamlake library stat acme/gso --asset $ID -o ./scene/assets \
  || dreamlake library pull acme/gso --asset $ID -o ./scene/assets
```

## Preview it

The asset panel mounts a viewer chosen by `kind`:

| `kind` | Viewer |
|---|---|
| `mjcf` | The interactive MuJoCo viewer (same engine as [Envs](/envs.md)): physics, actuator sliders, alt-drag forces. |
| `urdf` | The URDF poser with joint gizmos. |
| `mesh` | GLB/GLTF, OBJ, STL and mesh PLY. |
| `splat` | 3D Gaussian splats — see below. |
| anything else | A file listing with per-file downloads. |

Entry points render as a switcher — flip between `scene.xml` and the bare
robot without leaving the panel. Files load through short-lived presigned
URLs and are cached per content hash, so assets sharing files download them
once.

### 3D Gaussian splats

Splat assets render through [Spark](https://sparkjs.dev). Supported:
`.ply` (including PlayCanvas `.compressed.ply`), `.splat`, `.ksplat`,
`.spz`, plus two multi-file layouts — **SOG** (a `meta.json` with sibling
WebP planes) and **SOG-LOD** (a `lod-meta.json` naming per-level nodes).

The viewer picks the flavor from the wire `format` when it is `sog` or
`lod`, otherwise from the entry file's extension, otherwise from the entry
filename (`meta.json` → SOG, `lod-meta.json` → LOD).

Push a SuperSplat export as-is and all three are filled in for you: the CLI
detects the directory layout, sets `kind: splat` with `format: sog` or
`lod`, and points `entry` at the meta file. `library add` does the same for
a single asset. Override it in `dreamlake.yml` only when your layout is
unusual enough that detection misses it:

```yaml file="dreamlake.yml"
assets:
  courtyard:
    kind: splat
    format: sog # or: lod
    entry: courtyard/meta.json # or: courtyard/lod-meta.json
```

LOD assets render the **coarsest level only**, as a static preview — enough
to recognize a scene without pulling a multi-hundred-megabyte tree. There is
no distance-based level switching.

### Coordinate conventions

3DGS trainers emit the COLMAP/OpenCV camera frame — **Y-down**, Z-forward.
three.js is **Y-up** right-handed. The viewer therefore applies exactly one
π rotation about X to every splat mesh; Spark itself imposes no convention,
and nothing else in the pipeline rotates the data.

The practical consequence: assets exported by SuperSplat
(`.compressed.ply`, SOG, SOG-LOD) are Y-down and render correctly. Polycam's
raw `.ply` exports are **already gravity-aligned to Y-up** at export, so the
flip double-corrects them and they appear upside-down. Rotate such an export
before pushing it; a provenance-based exemption is not implemented.

## Pull it back

```bash
dreamlake library pull my-team/menagerie -o ./menagerie-copy   # clean source tree
dreamlake library pull my-team/menagerie --asset unitree_go2   # one asset's files
dreamlake library pull my-team/menagerie --all -o ./mirror     # source + platform artifacts
```

Pulls verify every file against its manifest sha256 and materialize original
relative paths. The default pull returns exactly the **clean source
directory** — platform artifacts under `.dreamlake/` (and the generated files
of legacy pushes) are skipped — so a full pull followed by `diff -r` against
your source directory is byte-identical, `dreamlake.yml` included. `--all`
adds the platform artifacts (wire manifest, rendered thumbnails, vector
sidecars) for mirroring or debugging.

Pulls are also incremental: files already on disk with the right sha256 are
skipped, and pulling into a non-empty directory syncs it — only stale or
missing manifest files are written, extra local files are never touched.
Re-running a pull you already have costs one manifest read and zero bytes.

## Add or remove one asset

You don't need the whole library on disk to change one thing in it:

```bash
dreamlake library add fortyfive/props ./my-mug --title "Blue mug" --category household
# ✓ fortyfive/props revision 8 — asset my-mug added (34 files, 4.8 MB)

dreamlake library rm fortyfive/props my-mug old-chair
# ✓ fortyfive/props revision 9 — 2 assets removed, 41 files reclaimed
```

`add` runs the same discovery as push on one directory (or one loose file),
takes its metadata from flags (`--id`, `--title`, `--description`,
`--category`, `--tags`, `--license`, `--attribution`), and appends the asset
to the remote manifest. An existing id is an error unless `--replace` —
which is how you update one asset in place. Files the library already holds
(shared meshes, unchanged bytes under `--replace`) are not re-uploaded.

`rm` never transfers a byte: it removes the manifest entries, and the server
reclaims every file no remaining asset references. It refuses to empty a
library — delete the library itself instead. Both commands converge under
concurrency through the same revision compare-and-swap as push, and both
are what the [push drift guard](#push-it) protects: a wholesale push from a
stale directory will stop rather than silently undo a remote `add`.

## Under the hood

```
libraries/<namespace>/<name>/
  files/<original relative path>          ← your files, verbatim (dreamlake.yml included)
  files/.dreamlake/manifest.json          ← wire manifest — generated, machine-owned
  files/.dreamlake/thumbnails/<id>.webp   ← rendered by push --thumbnails
  files/.dreamlake/vectors.{json,f32}     ← embedding sidecar from push --embed
```

One prefix per library in platform storage. `.dreamlake/` is a **reserved
dot-directory**: only platform-generated artifacts live there, user asset
paths may never enter it, and generated paths may never leave it — that is
what keeps your files tree clean.

### The wire manifest — generated, you never edit this

`.dreamlake/manifest.json` (schema `dreamlake.assets/v1`) is the API contract
between the CLI and the server: the single source of truth every catalog row,
search result, and preview derives from. The CLI regenerates it wholesale on
every push — treat it the way you treat a lockfile you didn't write. If you
integrate over HTTP instead of through the CLI, this is the document you
produce and register.

| Field | Meaning |
|---|---|
| `schema` | Always `dreamlake.assets/v1`. |
| `library` | Catalog identity: `name`, `type` (default `3d`), `title`, `description`, `provider`, `homepage`, `license`, `tags`, `upstream`. |
| `assets[].id` | Unique within the library, path-safe. |
| `assets[].kind` / `format` | Viewer dispatch only. Any token matching `^[a-z0-9][a-z0-9._-]{0,31}$`; `kind` defaults to `file`. `format` is a free sub-type — detection sets it for the splat container layouts (`sog`, `lod`), `dreamlake.yml` can set any value. |
| `assets[].entry` / `entryPoints` | The file(s) a viewer opens; must be listed in the asset's `files`. |
| `assets[].files` | `{path, size, sha256}` objects, paths relative to the library root. sha256 drives the incremental push diff and pull verification. |
| `assets[].thumbnail` | One of the asset's own files, or a platform artifact listed in `generated[]`. |
| `assets[].meta` | Free-form JSON (`dof`, `triCount`, mass…), ≤ 8 KB. |
| `generated[]` | Platform artifacts the push uploaded (thumbnails, vectors) — every path lives under `.dreamlake/`. **Declaring an artifact here is what makes it exist**: the reconcile keeps only what the manifest lists, and the vectors sidecar is read for search only when both halves are declared. |

Limits: ≤ 50,000 assets, ≤ 1,000,000 file entries, ≤ 60,000 `generated[]`
entries, manifest ≤ 100 MB. For scale, a production library of 14,355
Gaussian-splatting scenes produces a manifest of roughly 60 MB. Assets may
share files (a common mesh pool is fine); the same path with two different
hashes is rejected.

> **Warning:** Only relevant if you integrate over raw HTTP; the CLI does this for you.
>   If you upload `.dreamlake/vectors.json` and `.dreamlake/vectors.f32`, list
>   **both** in `generated[]`. An undeclared sidecar does not exist: register
>   reports `semantic: false`, search stays keyword-only, and the
>   post-register reconcile — which keeps storage equal to the manifest —
>   deletes the files. One rule, three places, no partial state.

Libraries pushed under the old model (a hand- or importer-generated
`assets.json` at the files root) keep working: the server reads the legacy
location as a fallback, and the first push from the current CLI migrates them
to `.dreamlake/manifest.json`.

The catalog row (Mongo) holds identity, visibility, the revision counter, and
cheap mirrors for filter chips (categories / kinds / licenses / counts).
**Per-asset data lives only in the manifest** — search runs server-side over
a revision-keyed in-memory cache of it, so a register invalidates everything
atomically and nothing can drift.

| Call | Purpose |
|---|---|
| `POST …/libraries/:name/upload-authorizations` | Presigned upload batch (members) |
| `POST …/libraries/:name/register` | Validate manifest, bump revision, reconcile files |
| `GET …/libraries/:name` / `…/manifest` | Catalog row / full parsed manifest |
| `GET …/libraries/:name/assets/:assetId` | One asset + presigned file URLs (the preview payload) |
| `POST …/libraries/:name/files-presign` | Presigned GETs for manifest paths (the pull payload) |
| `GET …/libraries/:name/search` | Search inside one library |
| `GET /libraries` · `GET /library-search` | Visible-library list · cross-library search |

Request/response schemas for every call, the full `dreamlake.assets/v1` field
contract, and the composed read patterns are in
[Libraries Reference](/libraries/reference.md).

Soft delete hides a library (restorable); **purge** permanently deletes the
row and every stored object.

## Next steps

- [Libraries Reference](/libraries/reference.md) — the machine contract: endpoint
  schemas, the wire manifest, and how an agent composes them.
- [Envs](/envs.md) — single runnable environments; a library is where an env's
  ingredients come from.
- [CLI](/cli.md) — install and authenticate `dreamlake`.
- [Search](/search.md) — platform-wide search surfaces.

---

Source: https://docs.dreamlake.ai/workflows/agent-permissions

# Agent Permissions

  Every user-defined agent (uda node) declares what it may touch. Grants are
  flat, auditable strings in the IAM style — <code>domain.resource.verb</code> —
  validated when a workflow version is saved.

> **Status**: permission grants are **defined, stored, and validated for
> well-formedness**. Runtime enforcement ships with the execution engine.

> **Note:** Grants govern **resources** — datasets, nodes, queues. They do not govern
>   **tools and files**; that is Claude's `allow` / `ask` / `deny` rule syntax,
>   documented on [Agents](/lakeshore/agents.md#permissions--what-it-may-touch). A
>   `uda` node and a declared agent both carry a `tools` list and a permission
>   block, and in both cases the two lists are validated independently.

## Grant grammar

```
grant   := domain "." resource "." verb (":" scope)?
domain  := lowercase identifier        e.g.  dreamlake, lakeshore
resource:= lowercase identifier        e.g.  datasets, providers, queues
verb    := read | create | update | delete | <registered custom verb>
scope   := resource qualifier          e.g.  @acme/robotics/grasp-v2, gpu-a10g
```

The format follows Google Cloud IAM (`service.resource.verb`, as in
`storage.objects.get`). The verb set follows the Kubernetes/IAM CRUD
convention, with `get`/`list` collapsed to **`read`** (we do not enforce
them differently). Domain actions that are not CRUD — like publishing a
dataset version — are **registered custom verbs on a specific resource**
(the way Kubernetes registers `impersonate` or `bind`), never a global verb.

## Registry

| Grant | Meaning |
| --- | --- |
| `dreamlake.datasets.read` | read datasets and dataset versions |
| `dreamlake.datasets.create` | create datasets / write new data |
| `dreamlake.datasets.update` | modify dataset metadata / annotations |
| `dreamlake.datasets.delete` | soft-delete datasets |
| `dreamlake.datasets.release` | **custom verb** — publish an immutable dataset version |
| `dreamlake.nodes.read` / `.create` / `.update` / `.delete` | the Node tree: episodes, folders, files |
| `dreamlake.artifacts.read` / `.create` / `.update` / `.delete` | renderable artifacts |
| `dreamlake.providers.read` / `.create` / `.update` / `.delete` | provider administration |
| `dreamlake.workflows.read` / `.create` / `.update` / `.delete` | workflow definitions and versions |
| `dreamlake.workflows.run` | **custom verb** — launch a workflow run |
| `lakeshore.queues.submit:<queue>` | **custom verb, scope required** — submit work to a queue |
| `lakeshore.queues.consume:<queue>` | **custom verb, scope required** — consume work from a queue |

Unknown domains, unknown resources under a known domain, and unknown verbs
are validation **errors** — the registry is closed, and grows by
registration, not convention drift.

## Scoped grants

A `:scope` suffix narrows a grant to a resource path:

```
dreamlake.datasets.read:@acme/robotics/grasp-v2
lakeshore.queues.submit:gpu-a10g
```

Unscoped grants apply namespace-wide. Queue verbs always require a scope.

## Tools are not permissions

Tool access is declared in the uda node's own **`tools`** field
(`tools: ["Read", "Bash"]`), following Claude's agent spec — the same field
name, the same semantics, and the same "omit to inherit everything" default.
Permission strings govern **data and resources**; the tools list governs
**capabilities**. The two lists are validated independently.

Which *files* a tool may touch, and which *commands* Bash may run, is a third
thing again — Claude's `Read(…)` / `Edit(…)` / `Bash(…:*)` rule syntax. A `uda`
node does not carry one today; a declared agent does. See
[Agents → Rule syntax](/lakeshore/agents.md#rule-syntax).

```json
{
  "kind": "uda",
  "title": "vlm_annotator",
  "uda": {
    "instructions": "Label task, sub-task and active hand for each clip",
    "model": "qwen-vl-72b",
    "tools": ["Read"],
    "permissions": [
      "dreamlake.datasets.read",
      "dreamlake.datasets.create",
      "lakeshore.queues.submit:gpu-a10g"
    ],
    "queue": "gpu-a10g"
  }
}
```

## Why not `edit`, `remove`, or `ToolUse.*`?

- **`edit` → `update`, `remove` → `delete`**: no major permission system
  (IAM, Kubernetes RBAC, GitHub fine-grained) uses `edit` or `remove` as
  verbs; `update`/`delete` map 1:1 to REST methods and to both IAM and
  RBAC.
- **`ToolUse.Bash` → `tools: ["Bash"]`**: tool grants as permission
  strings would duplicate a concept every agent runtime already models as
  a first-class field, and would leave the runtime with two sources of
  truth for the same capability.

---

Source: https://docs.dreamlake.ai/scene-generation/quickstart

# Scene Generation Quickstart

  Install one agent skill, then ask for scenes in plain language — *"build a
  kitchen counter with a mug and a cocoa tin"* — and get back a rendered,
  physically validated, versioned [env](/envs.md) you can keep editing with more
  prompts. This page is the install-and-use guide; the full method lives in
  the [Scene Generation](/scene-generation.md) technical guide.

## What the skill gives you

`dreamlake-scene-generation` teaches a coding agent (Claude Code, or any
Skills-compatible client) the complete scene workflow:

- **Source assets from anywhere** — download models from the internet (the
  [MuJoCo Menagerie](https://github.com/google-deepmind/mujoco_menagerie) is
  the curated first stop for robots), use files you already have, author
  props procedurally as plain MJCF, or pull from a
  [DreamLake asset library](/libraries.md) when one is available. The library is
  a convenience — hash-verified pulls and versioned reuse — not a required
  first step.
- **Measure instead of guessing** — bundled inspection tools read each
  model's real dimensions and bounding boxes, so objects rest *on* tables
  instead of floating above them or launching out of them.
- **Validate the physics** — a short simulation checks penetration, support
  forces, and that props stay where they were placed, with explicit per-body
  assertions rather than a vague "looks stable".
- **Render and publish** — camera renders for your eyes, then
  `dreamlake env push` publishes a versioned env with an interactive
  [browser viewer page](/envs.md), private by default.
- **Edit and reuse with more prompts** — a published scene stays editable:
  the agent pulls it back, changes what you asked for, and pushes a new
  version; existing scenes can seed new ones.

These scenes were produced by exactly this loop, from ordinary prompts,
during the skill's evaluation runs:

![A warm kitchen prep counter with a butcher-block top, a cutting board, a red patterned mug, and a cocoa tin under a key light.](/images/scene-generation/kitchen-hero.png)

![A UR5e robot arm work cell: the arm mounted on a workbench with small parts placed on the table surface.](/images/scene-generation/workcell-hero.png)

![A pottery display: bowls, a jug, cups, and a plate resting on a two-tier work table, with a shelf of glazed cups behind.](/images/scene-generation/pottery-hero.png)

## Prerequisites

- **`dreamlake` CLI ≥ 0.35**, logged in (`dreamlake login`).
- **Python** — how much depends on the route the agent takes:
  - **Raw MJCF scenes** need only the skill's inspection/validation tools'
    dependencies: `mujoco` (≥ 3.2) and `numpy`. The layer composer is
    **optional** — a scene authored as one self-contained MJCF directory is
    pushed directly, no `dreamlake[compose]` install involved.
  - **Layer-composed scenes** (`dreamlake env compose`) additionally need
    the composer: dreamlake-py ≥ 0.23 with **MuJoCo 3.14**. Details
    in [Scene Generation § Requirements](/scene-generation.md#requirements).
- **An agent that reads Skills** — Claude Code is the reference client.

A plain `pip install "dreamlake[compose]"` does **not** guarantee MuJoCo
3.14 — dreamlake 0.23.0 declares `mujoco>=3.2` (0.23.1 raises the floor
to `>=3.8`), and composition fails below 3.8 either way. Use a fresh venv
with pinned versions (the validated combination: Python 3.11, dreamlake-py
0.23.x, MuJoCo 3.14.0, NumPy 2.x), and verify what you got:

```bash
python3 -m venv ~/.venvs/dreamlake-scenes
source ~/.venvs/dreamlake-scenes/bin/activate
pip install "dreamlake[compose]==0.23.1" "mujoco==3.14.0"

python -c "import dreamlake, mujoco; print(dreamlake.__version__, mujoco.__version__)"
# expect: 0.23.1 3.14.0
dreamlake --version    # ≥ 0.35

# the CLI's compose step finds this venv through DREAMLAKE_PYTHON
# (there is no --python flag):
export DREAMLAKE_PYTHON="$(command -v python)"
```

Raw-MJCF-only setups can install just `pip install "mujoco==3.14.0" numpy`
into the venv instead.

## Install the skill

The skill is distributed through the public
[dreamlake-skills](https://github.com/dreamlake-ai/dreamlake-skills)
repository. Each top-level directory there is one complete, self-contained
skill folder — `SKILL.md`, action guides, the runnable `tools/`, and the
generated reference pages. Install the **whole folder**, and **symlink
rather than copy**, so a `git pull` in the checkout updates the installed
skill:

```bash
git clone https://github.com/dreamlake-ai/dreamlake-skills.git ~/dreamlake-skills

# user-scoped — available in all your projects
mkdir -p ~/.claude/skills
ln -s ~/dreamlake-skills/dreamlake-scene-generation ~/.claude/skills/

# or project-scoped — only inside one repository
mkdir -p .claude/skills
ln -s ~/dreamlake-skills/dreamlake-scene-generation .claude/skills/
```

If your clone predates this skill, `git -C ~/dreamlake-skills pull --ff-only`
first; a checkout that already carries `dreamlake-scene-generation/` works
as-is.

Keep the trailing slash on the destination: `ln -s <src> ~/.claude/skills/`
refuses to clobber an existing entry of the same name. If `ln` reports
`File exists`, inspect the existing skill and preserve local edits before
replacing it.

**Updating safely.** Because the install is a symlink, updates are just
`git -C <checkout> pull --ff-only`. If you have customized the skill,
commit your edits on a local branch first and `git pull --rebase` (or
merge) so an update can never silently overwrite them — never edit an
uncommitted working tree you also pull into.

The agent discovers the skill from its frontmatter and picks it up when a
scene request matches — no registration step.

## Use it — ordinary prompts

No special syntax. Describe the scene, name the outcome you want:

**Create:**

> Build a breakfast table scene — a wooden table with two mugs and a bowl
> resting on it, warm lighting, a nice camera angle — and publish it to my
> namespace as `breakfast-table`.

**Edit** (a published scene stays editable — same name, new version):

> In `breakfast-table`, move the blue mug 10 cm to the left, dim the key
> light a little, and push the result.

**Reuse** (an existing scene can seed a new one):

> Start from `breakfast-table` and add a robot arm from the MuJoCo Menagerie
> on a stand next to the table. Publish it as `breakfast-robot`.

Behind each prompt the agent runs the loop from the
[technical guide](/scene-generation.md): source and verify assets, measure,
derive placements, compose, validate physics, render, push, and report the
version it published.

## What a finished run leaves you

Ask the agent to keep the **reusable deliverables** with your project, and
treat everything else as disposable scratch:

**Keep — this is what makes the scene editable and auditable later:**

- **The editable source** — the layer stack (`dreamlake.layers.json`) for
  composed scenes, or the authored MJCF directory for raw scenes. This is
  what edits are made to; the pushed env embeds a pinned copy.
- **Per-model provenance** — for every third-party model: the exact source
  URL, version or commit, and its license (Menagerie models each carry their
  own `LICENSE` file — record each one, not one blanket note).
- **Component envs** — base room and props published as their own pinned
  versions, when the composed route was used.
- **Initial state** — prop poses live in the stack (`Attach` `pos`/`quat`);
  an articulated opening pose is a keyframe block kept in a file beside the
  stack and re-applied after every recompose.
- **The published env itself** — the compiled entry XML plus all assets, at
  an exact version from the push receipt.
- **Renders and the validation report** — the images you approved and the
  physics evidence behind the version.

**Disposable** — scratch pull directories, intermediate compose attempts,
validation JSON from rejected layouts, probe scenes: safe to delete once the
version is published and verified.

## Preview in the browser

Every pushed env gets an interactive viewer page — open the link the push
prints, look at the framing and materials, and play the simulation
([Envs guide](/envs.md)).

### Generate from the env page

Scenes can also be created and edited *in the browser*, from a chat panel
next to the 3D viewer. This flow ships with the web app: it needs an app
deployment that includes env chat, so if your env page does not offer the
chat panel yet, that deployment hasn't reached your server — prompt your
local agent and use the browser to inspect the result instead. How it
works:

1. Open your namespace's **Envs** catalog (`/<namespace>/envs`) and click
   **+ new env** (members only) — it sits in the page header next to the
   Environments/Libraries switch, and an empty catalog offers the same
   button in its placeholder.
2. One click opens the env page as a *draft* under an auto-minted name
   (`env_xxxxxx`) — there is no name dialog, and nothing is created on
   the server yet.
3. **Describe the scene** in the intro composer the draft opens into ("a
   breakfast table with two mugs and a bowl…"). The prompt goes to the
   embedded agent, which runs the same skill workflow — source, measure,
   compose, validate — and publishes with `dreamlake env push`. The chat
   opens in **Auto** permission mode so this runs end-to-end without
   per-command approval; switching the composer to Ask/Plan makes it a
   read-only conversation (no generation, no push) until you switch back.
4. When the first push succeeds, the page swaps the draft placeholder for
   the **saved preview**: the interactive viewer on the version that was
   just pushed, with the chat still open beside it.
5. **Keep prompting to edit** — each successful push adds a version. The
   viewer follows the latest version; picking an older version from the
   header dropdown pins it (a "vN available" button jumps back to
   latest).
6. **Edit an existing env** the same way: open its env page (as a member)
   and use the chat panel beside the viewer.
7. **Reuse starts from the catalog, not from the source env's page.** The
   chat edits the env whose page it sits on — a "start from
   `breakfast-table` and add…" prompt *on `breakfast-table`'s own page*
   pushes new versions of `breakfast-table` itself. To grow a new scene
   out of it, go back to the Envs catalog, click **+ new env**, and
   prompt in the fresh draft: "Start from `breakfast-table` v3 and add a
   robot arm…". The new env references the source at that pinned version;
   `breakfast-table` keeps its own versions, untouched.

## Next steps

    Sourcing, measuring, placement math, validation, publish/iterate.

    Push, version, drive, thumbnails, and pull round-trips.

    The full v3 stack grammar and compose semantics.

---

Source: https://docs.dreamlake.ai/scene-generation

# Scene Generation

  How to go from *"I want a breakfast table with two mugs"* to a pushed, previewable, **physically
  valid** MuJoCo env: source assets from wherever serves the request — the internet, files you
  already have, procedural MJCF, or a [library](/libraries.md) — measure them, derive placements
  instead of guessing, compose the scene, validate the physics, and publish it as a versioned
  [env](/envs.md) you can keep editing. New here? Start with the
  [Quickstart](/scene-generation/quickstart.md).

The loop this guide teaches:

1. **Source** ingredients — from any origin: download internet models,
   take user-supplied files, author props procedurally, or search a
   DreamLake library — then verify whatever you got actually compiles and
   collides.
2. **Measure** — read each model's real dimensions and bounding boxes; never
   eyeball a mesh's size or where its bottom is.
3. **Design** the base scene — supporting fixtures, materials, lights, and a
   hero camera, all derived from the measurements.
4. **Compose** — either author one self-contained MJCF directory directly,
   or build a v3 layer stack that places components as `Attach` entries
   with stable keys and pinned versions (the modular, reusable route).
5. **Validate** — simulate briefly; check penetration, support, and that
   props rest where you put them. Shape/physics validity and visual quality
   are different questions — check both, separately.
6. **Publish and preview** — push, open the env page in a browser, iterate
   by editing the stack and re-pushing.

## Requirements

- The `dreamlake` CLI, logged in (`dreamlake login`) — env and library
  commands are in CLI ≥ 0.35.
- Python with `pip install "dreamlake[compose]"` for `dreamlake env compose`
  (installs the layer engine and `mujoco`; dreamlake-py ≥ 0.23). The engine
  needs **MuJoCo ≥ 3.8** — use 3.14, the version this workflow is validated
  with; dreamlake 0.23.0 still _declares_ `>=3.2.0` but composition fails on
  3.2, and 0.23.1 declares the real `>=3.8` floor (see
  [layers § requirements](/envs/layers.md#requirements)). A plain
  unpinned install does not ensure 3.14 — pin it:
  `pip install "dreamlake[compose]==0.23.1" "mujoco==3.14.0"` in a fresh
  venv, and verify with
  `python -c "import dreamlake, mujoco; print(dreamlake.__version__, mujoco.__version__)"`
  (a step-by-step venv setup is in the
  [Quickstart § Prerequisites](/scene-generation/quickstart.md#prerequisites)).
  If the CLI should use a specific interpreter or venv, set
  `DREAMLAKE_PYTHON` to that python — there is no `--python` flag.
- **When `DREAMLAKE_PYTHON` is set, run the scene tools with it too** —
  `"$DREAMLAKE_PYTHON" tools/scene_report.py …`. Hosted agent runtimes
  provide their Python this way on purpose: the shared venv is *not* on
  `PATH`, so an unqualified `python` there is a different interpreter
  without the tools' dependencies. The commands below write `python` for
  brevity.
- The scene tools below need only `pip install mujoco numpy` (mujoco ≥ 3.2;
  the tools' test suite passes on 3.2.0, 3.8.1 and 3.14.0) and run on any
  MJCF file or pulled env directory — no DreamLake account or workspace
  checkout involved. The 3.2 floor is for these tools only — composition
  needs 3.8+ as above.

## Source assets that will actually work

Assets can come from **any source** — pick whatever serves the request best,
in any mix:

- **The internet.** For robots, the curated first stop is the
  [MuJoCo Menagerie](https://github.com/google-deepmind/mujoco_menagerie) —
  ready-made, maintained MJCF models. Any other MJCF/OBJ/STL you can
  legitimately download works too.
- **Files the user already has** — a repo checkout, an export from a
  scanning pipeline, meshes from a CAD tool.
- **Procedural authoring** — writing MJCF primitives yourself (boxes,
  cylinders, capsules with materials) is a first-class source, not a
  fallback. Tables, shelves, walls and many props are *better* authored
  than downloaded: exact dimensions, clean collision, tiny files.
- **A [DreamLake asset library](/libraries.md)** — an optional convenience
  when one is available: per-asset search, manifest-hash-verified pulls,
  versioned reuse. There is no required survey-the-libraries step, and an
  empty search result never means "stop" — switch source.

Two distinctions to keep straight while sourcing:

- **A visual reference is not a usable model.** Product photos, renders and
  images are excellent for choosing dimensions, materials and layout — but
  only a downloaded MJCF (or a mesh you wrap yourself, below) can actually
  enter the scene. Don't report an image search as having "found an asset".
- **A model you saw is not a model you have.** Until the files are on disk,
  complete, and compiling, treat a candidate as a lead, not an ingredient.

### Record provenance per model

For every third-party model, record at sourcing time — it is much harder to
reconstruct later:

- the **exact source URL** and the **version or commit** you took it from;
- its **license, per model** — Menagerie is not one license: each model
  directory carries its own `LICENSE` file (BSD, Apache, others). Copy the
  license alongside the model and note it in the scene's provenance record.

### The acceptance checklist — any source

Whatever the origin, an asset is usable when:

- **The dependency closure is complete.** Every mesh, texture, and
  `<include>` the XML references is present and resolves (check
  `<compiler meshdir= texturedir=>`). A model that compiles only inside its
  original repo layout is not yet yours.
- **It compiles** — load it with the tools below (`scene_report` compiles
  the model to measure it); a broken asset fails here, not mid-composition.
- **Units and up-axis are right.** MuJoCo is meters and Z-up. Meshes
  exported in millimeters need `scale="0.001 0.001 0.001"` on the
  `<mesh>`; measure after loading — a 1.8 mm-tall "chair" is a units bug,
  not a small chair.
- **Collision geometry is present.** A visual-only mesh (every geom
  `contype="0" conaffinity="0"`) falls through the table no matter where
  you place it.
- **Mass is plausible.** Check the tool report's mass column — a 0.2 g
  table or a 400 kg mug will simulate legally and behave absurdly.
- **The right entry file.** Robot models often ship both a bare robot file
  and a `scene*.xml`; compose with the _robot_ file (the scene drags its
  own floor and lights into yours).
- For layer composition specifically: **exactly one root body** under
  `<worldbody>` — `Attach` grafts one subtree. Scanned-object exports (one
  `<body name="model">` holding visual group-2 and collision group-3 mesh
  geoms) are ideal.

The authoritative reference for every MJCF element and attribute is the
[MuJoCo XML reference](https://mujoco.readthedocs.io/en/latest/XMLreference.html).

### Raw meshes: wrap OBJ/STL in MJCF yourself

MuJoCo loads **OBJ and STL** meshes as `<mesh>` assets — a bare mesh becomes
a scene object by wrapping it in a body you author: the mesh as a visual
geom, plus **simple collision primitives** (a box, cylinder or capsule
approximating the shape) rather than trusting an arbitrary mesh's convex
hull:

```xml
<asset>
  <mesh name="jug_visual" file="jug.obj"/>  <!-- scale="0.001 …" if mm -->
</asset>
<worldbody>
  <body name="jug" pos="0 0 0">
    <geom type="mesh" mesh="jug_visual" group="2"
          contype="0" conaffinity="0" mass="0"/>         <!-- visual only -->
    <geom type="cylinder" size="0.06 0.09" pos="0 0 0.09"
          group="3" mass="0.4"/>                          <!-- collision -->
  </body>
</worldbody>
```

Give the visual geom `mass="0"` explicitly: `contype="0" conaffinity="0"`
only disables collision — the geom still contributes density-derived mass
and inertia to the body, silently doubling it on top of the collision
primitive's explicit mass. Then measure the wrapped body with
`scene_report` and fix the collision sizes against the printed mesh AABB
(and confirm the reported body mass equals the collision mass you set). **GLB/FBX (and other formats MuJoCo
does not read) are not directly loadable** — there is no magic conversion
step; if you convert with an external tool, verify the result the same way
as any downloaded mesh (compile, measure, check collision), and don't
present a conversion pipeline you haven't run as if it works.

### Searching a DreamLake library

When you do use a library: `dreamlake library list --all` prints every
library you can see _with its description_ — pick where to search, then
search there.

```bash
dreamlake library list --all
dreamlake library search "coffee mug" --library acme/props --kind mjcf
```

Read search results skeptically:

- **A ranked hit is not a relevant hit.** Semantic search ranks by
  closeness, so even a query the library cannot serve can come back as a
  page of confident-looking rows (observed with nonsense queries against
  indexed libraries). Judge the titles, then inspect the top candidate
  before building on it.
- **`--kind mjcf` filters out meshes, splats and glTF** — for scene
  composition you almost always want `mjcf` assets (they carry collision
  geometry and compile as-is). A `mesh` asset is still usable via the
  wrapping pattern above.
- **No results has several causes**: a `--category`/`--tag`/`--kind` filter
  that nothing carries, a library that simply lacks matching assets, or one
  you cannot access. Drop the filters and requery; then try another library
  — or leave the library route entirely and download or author the asset
  instead. No-results is a reason to switch source, never to give up on the
  request.
- If a library was pushed without embeddings, search silently runs
  keyword-only (`semantic: false` in the API response) — shorter, literal
  queries work better there.

Inspect a candidate before committing to it — pull just that asset and
measure it (tools below):

```bash
dreamlake library pull acme/props --asset blue_mug -o ./assets
python tools/scene_report.py ./assets/blue_mug --body model
```

Pulls verify every file against its manifest sha256; a partially transferred
or corrupted asset fails the pull rather than landing silently broken. Pulls
are incremental and never delete: pulling several assets into one directory
just works, and re-running a pull you already have transfers nothing.

## Derive placements — never guess

The single most common failure is placing an object by eye: it spawns
intersecting the table (launches on load) or floating (drops and topples).
The tools in the scene-generation skill (also usable standalone) print the
numbers to derive placements from. Abridged real output for a scanned
grocery-object mug (values rounded; keys are exactly what the tool emits):

```bash
python tools/scene_report.py ./assets/blue_mug --body model --json
#   "pos":      [0.0, 0.0, 0.0],            ← body origin, world frame
#   "aabb_min": [-0.063, -0.047, -0.0],     ← this mug's base sits AT its origin
#   "aabb_max": [0.063, 0.044, 0.135],
```

These bounds are **tight**: mesh geoms report the exact bounds of their
compiled vertices (what you see rendered), primitives exact analytic
support bounds. That matters — a conservative rotated-box bound looks
harmless but pads the bottom by 1–2 cm on typical scanned meshes, and a
placement derived from it _floats visibly_ at t=0. Never assume where the
bottom is, in either direction: scanned objects often sit exactly at
their origin (this one), centroid-origin assets have it well below.

Both `pos` and the AABB are **world-frame at the current state**, so the
placement rule is a _move_, not an absolute coordinate:

```
delta_z     = (h + clearance) − aabb_min.z      # clearance ≈ 1 mm
new body z  = pos.z + delta_z
```

For the mug above (origin at `z = 0`, base at `z = −0.0`) on a table
whose top is at `z = 0.74`: `delta_z = 0.74 + 0.001 − (−0.0) = 0.741`, so
the new origin z is `0.741`. Only when the measured origin sits at zero
does the shortcut "new z = h − aabb_min.z + clearance" hold. The same
delta logic applies per horizontal axis — keep `aabb` footprints clear of
neighbors and inside the supporting surface. Real-world dimension anchors
help the scene read believably: dining table top ≈ 0.74 m, kitchen
counter ≈ 0.9 m, seat ≈ 0.45 m, door ≈ 2.0 m.

## Design the base scene

The base layer is an ordinary env you author directly (see the MJCF patterns
in the [Envs guide](/envs.md)). What separates an attractive scene from a gray
void:

- **Name everything you may later address**: layer `Update`/`Remove` ops and
  scene edits address elements _by MJCF name_ (`obj/mug`, `fixture/table`,
  `light:key`). Unnamed elements cannot be targeted, recolored, or removed.
- **Lights**: one warm key light (spot or point, positioned like a window or
  lamp), one dim directional fill; soften the headlight via
  `<visual><headlight …>`. A gradient `skybox` texture kills the black void.
- **Cameras**: author a hero `<camera name="thumbnail">` — the env page's
  cover and opening shot use it. Compute the aim, don't guess quaternions:
  MuJoCo cameras look along local `−z`, and `xyaxes` are the camera's +x and
  +y axes in the parent frame. From position **p** aiming at target **t**:
  `z = normalize(p − t)`, `x = normalize(up × z)`, `y = z × x`, then
  `xyaxes="x y"`. Add `<statistic center extent>` + `<visual><global
azimuth elevation>` so free-camera fallbacks frame the scene too.
- **Materials**: checker floor textures give scale cues; wood/ceramic tones
  with modest `specular`/`shininess` read better than saturated primaries.
  This is visual quality — the physics validator will not judge it, and a
  physically perfect scene can still look wrong; always render and look.

## Compose the scene — raw MJCF or layers

Two equally valid routes to a pushed scene:

- **Raw MJCF**: author (or assemble) one self-contained scene directory —
  entry XML plus every mesh/texture it references — validate and render it
  with the tools, and `dreamlake env push` it directly. This is a complete,
  supported workflow, and the right one for a scene you authored as a
  whole.
- **A layer stack**: publish components as their own envs and compose them.
  What the extra structure buys is **modular editing and reuse** — each
  prop is a pinned, versioned layer you can move with a one-line `Attach`
  edit, swap, or reuse in the next scene. Optional, not required.

The rest of this section is the layered route. Full grammar and semantics:
[Env Layers Reference](/envs/layers.md). The scene-generation specifics:

- **Push reusable components as their own envs** (base room, each prop) so
  the stack can pin them (`you/room@1`). Assets pulled from a library are
  ingredients — pushing one as an env is what makes it a _versioned layer_.
- **`Attach` keys are the instance identity** — `mug1`, `mug2` — and every
  name inside becomes `mug1:…`. Keep keys stable across edits: change an
  `Attach`'s `pos`, not its `key`. Renaming a key orphans every `Update`
  targeting the old prefix and re-identifies the instance in every diff.
- The **`Attach` `pos`/`quat` are your persistent initial state** for
  free-jointed props: they live in the stack, survive recompose, and become
  the composed model's default pose (qpos0).
- **`Attach.pos` is a frame translation, not an override.** The engine
  mounts the source subtree under a new frame and keeps the source root
  body's own `pos`, so the composed world position is
  `source root pos + Attach.pos` (identity rotation, `at: "world"`;
  verified with the published engine: source root at z = 0.5 attached with
  `pos` z = 1 lands at z = 1.5). For a source whose root sits at the origin
  — typical standalone assets — `Attach.pos` reads as the absolute mount
  pose; otherwise compute the delta as in
  [derive placements](#derive-placements--never-guess), i.e.
  `Attach z = (h + clearance) − source aabb_min.z`. With a rotation or a
  `body:`/`site:` mount, don't hand-derive: compose, then remeasure the
  composed artifact with `scene_report` and adjust.
- Compose floats, artifacts pin: author `you/room`, and the stack embedded
  in the output is pinned `you/room@N` with the builder versions — that
  pinned copy is what makes the scene re-openable and editable later.
- **Reuse a materialized scene**: a pushed composed env is an ordinary env —
  `Merge` it as the base of a new stack and add layers on top. It enters as
  one layer (its own stack is not re-walked).

Always pass the stack and output directory explicitly — without `-o` the
output directory is derived from the stack's `name` (else the stack
directory's basename), so the next commands may point at nothing:

```bash
dreamlake env compose ./dreamlake.layers.json -o ./composed
python tools/scene_validate.py ./composed --settle mug1:model --support mug1:model
python tools/scene_render.py ./composed -o ./shots --camera thumbnail
```

## Initial state and keyframes

What "the scene opens like this" means, precisely:

- The scene tools open a model at keyframe 0 when it has one, else qpos0.
  The browser viewer's t=0 contract — and crucially, **which viewer
  versions actually honor keyframe 0** (the prior source baseline does
  not) — is in [Envs § Drive it](/envs.md#drive-it); don't assume the
  deployed viewer shows your keyframe until you've seen it there.
- Env push/pull transfer files verbatim — a `<keyframe>` in your entry XML
  survives the round trip.
- **Merge-only stacks keep keyframes** (they resurrect correctly remapped).
  **Any `Attach` strips all keyframes** — attaching changes the dof layout,
  which invalidates them, so the composed artifact has none.
- Therefore, in an attach-bearing composition: put prop poses in `Attach`
  `pos`/`quat` (they persist in the stack). If you additionally need an
  _articulated_ opening pose — a robot holding a pose via `ctrl` — add a
  `<keyframe><key …></keyframe>` block to the **materialized entry XML**
  after compose and before push. This is a post-compose step on the
  artifact: recomposing regenerates the entry, so re-apply it after every
  recompose (keep the block in a file next to your stack). Validate the
  result with the scene tools — they read keyframe 0 — before pushing.

## Validate physics — and know what a pass means

```bash
python tools/scene_validate.py ./composed \
  --settle mug1:model --settle bowl:model=0.02 --support mug1:model
```

The validator loads keyframe 0 (else qpos0), holds the authored `ctrl`
(`--passive` zeroes it instead), simulates a few seconds, and fails only on
objective evidence: initial/peak/final penetration beyond tolerance,
non-finite state, MuJoCo warnings, bodies falling below `--floor-z`, and —
for bodies you _name explicitly_ — drift, residual speed/spin, net attitude
change, and contact-force support (real newtons opposing gravity, not
proximity). There is deliberately no scene-wide "stable" verdict: an
uncontrolled robot arm is _supposed_ to move, so a universal claim would be
noise for one scene and false comfort for another. Name the bodies that must
hold still; everything else is reported for you to read.

One subtlety a settle-and-support pass **cannot** certify: the authored
initial pose. A prop placed 2 cm above the table falls, lands, and passes
every end-of-run check — but the model still opens (and renders its
cover) at the floating authored pose; simulation never writes back into
the artifact. So validate _and_ look at t=0: render the initial state
(`scene_render` draws it), and if a named body's settle row shows a
straight drop (`start_pos` vs `end_pos`), fold that correction into the
persistent pose — the `Attach.pos` in the stack (or your keyframe) — and
recompose. The converse holds too: a good-looking t=0 screenshot is not
physical validity — run the checks.

## Publish, preview in the browser, iterate

```bash
dreamlake env push ./composed --name my-scene --title "My scene"
# ✓ pushed <ns>/my-scene v3 — …    ← save this exact version
dreamlake env pull my-scene@3 -o ./readback   # empty dir; hash-verified
```

Push privately by default (`--visibility public` is opt-in) and **save the
version number from the receipt**. Pull that exact `name@N` into a fresh,
empty directory — a bare `env pull <name>` fetches whatever is latest,
which can race a concurrent push. Then compare what matters: the embedded
`dreamlake.layers.json` pins, the entry XML (including any keyframe you
appended), and a validation run on the readback.

If a push fails mid-flight or times out, **check before retrying**: run
`dreamlake env list` and compare against your last receipt to learn what
actually landed. Retrying an _unchanged_ directory is normally safe — the
CLI compares the entry and every file hash against the latest version and
reuses or re-registers an identical version (even adopting an identical
concurrent push) instead of minting a new one. But those are content
checks, not a transaction guarantee: if the directory changed between
attempts, or someone pushed different content in the meantime, the retry
mints a legitimate new version — blob dedup alone says nothing about
version rows. Retry at most 2–3 times, confirm the version on the final
receipt, and report ambiguity rather than assuming.

Open the printed link and actually look: hero framing, materials under the
viewer's lighting, props resting where placed, play/pause behaves. On the
staging deployment, CLIs ≤ 0.37.0 print the API host in that
link — set `DREAMLAKE_WEB_URL=https://staging.dreamlake.ai` (an override
those CLIs already honor) or upgrade to CLI ≥ 0.37.1, whose receipts
target the web app directly.
The env page renders `mujoco`-type envs in the interactive viewer; `urdf`
gets the kinematic poser; other types list files only. The first member
visit captures the gallery thumbnail from your `thumbnail` camera.

Iterate by editing the **editable source**, and push the same env name for
a new version. For a raw-MJCF scene that is the authored directory itself —
edit the XML, re-validate, re-render, push. For a composed scene it is the
**pinned stack**, not the materialized XML: pull the env (the embedded
`dreamlake.layers.json` rides along), edit the op — move a mug's
`Attach.pos`, retune a light `Update` — recompose, re-validate, re-render,
push. One-line diff in the stack.
To re-aim a camera through an `Update` on SDK 0.23.0, state a
`quat` opinion — an `xyaxes` opinion is not accepted there (it _is_ fine
in a layer's own MJCF, and SDK ≥ 0.23.1 accepts the alternate
orientation specifiers in opinions too) — see
[layers § orientations](/envs/layers.md#tag-update--the-meta-component).

## When it goes wrong

| Symptom                                                | Likely cause → fix                                                                                                                                    |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| search returns plausible-looking but wrong assets      | semantic ranking can return close-but-wrong rows — inspect before use; add `--kind mjcf`; try another library, or source the asset elsewhere          |
| search returns nothing                                 | drop `--category`/`--tag`/`--kind` filters and requery; then another library — or switch source: download it (e.g. Menagerie), or author it as MJCF  |
| downloaded model won't compile outside its repo        | incomplete dependency closure — copy every mesh/texture/include it references and fix `meshdir`/`texturedir`; re-check with `scene_report`            |
| downloaded mesh is comically large or tiny             | units mismatch — the export is mm (or cm); set `<mesh scale="0.001 …">` and re-measure; MuJoCo is meters, Z-up                                        |
| `library pull` fails mid-way                           | reruns are safe and incremental (hash-verified); already-correct files are skipped, extra local files are never touched                               |
| asset falls through the floor/table                    | no collision geometry (`contype/conaffinity` 0) or a scene-entry attach — check with `scene_report`, attach the robot/object file instead             |
| props explode or launch at load                        | initial penetration — recompute the placement delta from `pos.z` and `aabb_min.z`, keep ≥ 1 mm clearance; `scene_validate` reports the offending pair |
| compose: "merge name collision"                        | two layers define the same name — rename in one, or make the change an `Update` (see [layers errors](/envs/layers.md#common-errors))                     |
| compose: "strict-match miss"                           | an op targets a pre-attach name — after `Attach key="mug1"`, address `mug1:body`, not `body`                                                          |
| compose: engine missing                                | `pip install "dreamlake[compose]"`; point `DREAMLAKE_PYTHON` at that interpreter                                                                      |
| push rejected: unpinned local layers                   | push each local layer as its own env first (`--push-layers`), then pin and recompose                                                                  |
| upload/readback network errors                         | check `dreamlake env list` against your last receipt first (an ambiguous failure may have finalized a version), then retry at most 2–3 times          |
| scene passes validation but looks wrong                | that is expected — the validator checks physics only; render and fix lights/cameras/materials                                                         |

## Next steps

    Discovery conventions, search scopes, manifests, pulls.

    The full v3 stack grammar, semantics, and compose errors.

    Push, version, drive, thumbnails, and pull round-trips.

---

Source: https://docs.dreamlake.ai/cli

# CLI Reference

  The complete `dreamlake` command surface. If you're new, start with the
  worked examples in <a href="/#your-first-episode">Your First Episode</a> — this page
  is the reference you come back to.

> **Note:** The canonical, per-command reference lives at
> [cli.dreamlake.ai](https://cli.dreamlake.ai) — it versions with each CLI
> release (the version switcher pins any past release), covers the newer
> command groups (agents, skills, sources, snapshots, lakeshore resources),
> and documents both install channels: the native installer and
> `npm install @dreamlake/dreamlake-cli`. The summary below covers the core
> commands; for anything not listed here, go there.

All commands use the `dreamlake` entry point. Add `--debug` before any command
to target local dev servers instead of production.

## Auth

```bash
dreamlake login --url <server>    # OAuth device auth flow (--no-browser for QR code)
dreamlake logout                  # Remove stored credentials
dreamlake profile                 # Show current user
```

## Files

```bash
dreamlake upload <file> --episode <target> --to <path>   # Upload file (type auto-detected)
dreamlake upload <dir>  --episode <target> --to <path>   # Upload folder (--yes to skip prompt)
dreamlake download --episode <target> --from <path> -o <out>
dreamlake list --episode <target>                        # List assets (--type video to filter)
```

Upload flags: `--type <override>`, `--bindr <names>` (comma-separated,
auto-created). `<target>` uses the
[episode syntax](/index.md#episode-syntax) `[namespace@]project[:episode]`.

## Collections

```bash
# Bindrs — curated file collections matched by glob
dreamlake create bindr <name> --project <target>             # --episode <glob> to match episodes
dreamlake update bindr <name> --project <target> --add <glob>
dreamlake delete bindr <name> --project <target>
dreamlake list bindr --project <target>

# Datasets — groups of bindrs
dreamlake create dataset <name> --project <target>
dreamlake update dataset <name> --project <target> --add <glob>
dreamlake delete dataset <name> --project <target>
dreamlake list dataset --project <target>

# Episodes
dreamlake list episode --project <target>
```

## Search

```bash
dreamlake vectorize --episode <target>                           # CLIP + LLaVA on video chunks
dreamlake vectorize --bindr <name> --project <target>            # Vectorize bindr scope
dreamlake vectorize --dataset <name> --project <target>          # Vectorize dataset scope
```

Add `--zaku-url <url>` for distributed processing. See
[Semantic Search](/search.md) for the pipeline this feeds.

## Artifacts

Renderable documents — HTML, React, Markdown, SVG, Mermaid, or code — rendered
live in the dashboard at `/<namespace>/artifacts`. New here? The
[Artifacts guide](/artifacts.md) is the two-minute picture-book version. Each artifact is its own
versioned dataset; the DreamLake server keeps the catalog (title, kind,
visibility) that powers the gallery and `list`.

```bash
dreamlake artifact push <file>                                       # kind auto-detected from extension
dreamlake artifact push <file> --title <t> --kind <k> --id <id>      # --namespace <ns> to target another namespace
dreamlake artifact push <file> --visibility public                   # readable without login (default: private)
dreamlake artifact push <file> --share                               # mint a ?share= link (signed-in users only)
dreamlake artifact list                                              # list a namespace's artifacts (from the catalog)
dreamlake artifact delete <id>                                       # soft delete → Trash (-y to skip the confirm)
dreamlake artifact restore <id>                                      # bring a soft-deleted artifact back
dreamlake artifact delete <id> --permanent                           # purge storage + catalog — IRREVERSIBLE
```

Kinds: `html` · `react` (must define an `App` component) · `markdown` · `svg` ·
`mermaid` · `code`. Re-push with the same `--id` to append a new version — the
viewer keeps every version. After a successful push the CLI prints an **open
link** to the artifact, so you can click straight through to view what you just
uploaded.

**Visibility & sharing.** Artifacts are **private** by default (visible only to
namespace members). `--visibility public` makes one readable by anyone;
`--share` mints a `?share=<token>` link that any **signed-in** DreamLake user
can open (anonymous visitors are sent to log in first). Members can also toggle
visibility and copy a share link from the artifact's page in the dashboard.

**Delete, Trash & restore.** `delete` is a **soft delete**: the artifact moves
to your gallery's **trash** tab (share links stop working immediately), and you
can bring it back with `restore`, the Restore button in the Trash, or simply by
re-pushing the same `--id`. `delete --permanent` (v0.4.14+) **permanently
erases** the artifact — every version, its stored content, and its catalog
entry. There is no undo; the dashboard's equivalent is **Delete forever** in
the Trash.

### Add the artifacts skills (Claude)

DreamLake publishes a [Claude](https://claude.ai/code) **skill** that teaches
your agent to publish, version, and share artifacts for you. Add it from the
public [`dreamlake-skills`](https://github.com/dreamlake-ai/dreamlake-skills)
repo:

```bash
git clone https://github.com/dreamlake-ai/dreamlake-skills.git ~/dreamlake-skills
mkdir -p ~/.claude/skills
ln -s ~/dreamlake-skills/dreamlake-artifacts ~/.claude/skills/
ln -s ~/dreamlake-skills/dreamlake-artifact-authoring ~/.claude/skills/
```

Install both skills: one publishes, the other prepares content for the offline
rendering frame. To update both, run `git -C ~/dreamlake-skills pull --ff-only`.
Use a project's `.claude/skills/` directory for project scope. If a skill already
exists, inspect and preserve local edits before replacing it with a symlink.

Then ask Claude something like *"push this dashboard as a dreamlake artifact
and make it public"* — it will invoke the skill and run the right
`dreamlake artifact` commands.

## Envs

Simulation environments — a directory holding one MJCF scene or one URDF
robot plus its assets, viewed as a live, interactive 3D page at
`/<namespace>/envs`. New here? The
[Envs guide](/envs.md) is the picture-book version. Each env stores its files
content-addressed, so re-pushing uploads only what changed, and `pull` returns
a byte-identical directory (every file is hash-verified).

```bash
dreamlake env push <dir>                              # entry auto-detected (MJCF, else *.urdf); prints an open link
dreamlake env push <dir> --entry scene.mjcf           # pick the entry when several qualify
dreamlake env push <dir> --type isaaclab              # simulator family (auto-detected: mujoco | urdf — both have viewers)
dreamlake env push <dir> --visibility public          # viewer opens without login (default: private)
dreamlake env push <dir> --thumbnail cover.png        # set the gallery cover (PNG ≤ 512 KiB) — see the Envs guide's Thumbnails section
dreamlake env create <dir>                            # push that FAILS if the name already exists
dreamlake env list                                    # a namespace's envs (name, type, files, entry)
dreamlake env pull <name>                             # latest version → ./<name>/, hash-verified
dreamlake env pull <name>@2 -o <dir> --force          # a specific version; --force writes into a non-empty dir
dreamlake env delete <name>                           # soft delete (restorable; -y to skip the confirm)
dreamlake env restore <name>                          # bring it back
dreamlake env delete <name> --permanent               # purge storage + catalog — IRREVERSIBLE
```

Names are `namespace/env-name` with immutable integer versions — re-push the
same name to append the next version, and the viewer keeps a version picker.
Limits per version: ≤ 1000 files, ≤ 100 MiB per file, ≤ 1 GiB total; dot-files,
`node_modules` and symlinks are skipped.

> **Renamed:** before envs existed, `dreamlake env` switched login
> environments. That command is now `dreamlake auth env list|use|remove` — see
> [Environments](https://cli.dreamlake.ai/environments/).

## The CLI itself

```bash
dreamlake --version                          # print the version
dreamlake doctor                             # install + auto-update diagnostics
dreamlake self-update                        # update now (background checks are automatic)
dreamlake self-update <version>              # pin to an exact version (pauses auto-update)
dreamlake self-update channel stable         # switch release channel: latest | stable (unpins)
dreamlake self-update --status               # version, channel, pin, last check
dreamlake install [latest|stable|<version>]  # re-install the native binary
```

Note the name: `update` edits bindrs and datasets, `self-update` updates the
CLI. See the [install reference](/index.md#install-reference) for the install layout, release channels,
and the variables that switch auto-update off.

## Legacy

```bash
dreamlake video upload <file> --user <owner> --project <proj>   # Direct BSS upload (bypasses server)
dreamlake video download <id> --output <path>                    # Download by BSS video ID
dreamlake video list --user <owner> --project <proj>             # List BSS videos
```

## Next steps

    The REST endpoints behind every command on this page.

    Work with the uploaded video from Python — slicing, frames, tensors.

---

Source: https://docs.dreamlake.ai/api

# API Reference

  The REST surface behind the CLI and dashboard. Endpoints are grouped by
  resource; every path below is relative to your server's base URL.

Base URL: `https://api.dreamlake.ai` in production, `http://localhost:3001`
in local dev. All endpoints require `Authorization: Bearer <token>` unless
noted — see [Architecture § Auth](/architecture.md#auth) for how tokens are
issued.

## Auth

| Method | Path | Description |
|--------|------|-------------|
| POST | `/auth/exchange` | Exchange vuer-auth token for dreamlake JWT (no auth required) |
| GET | `/auth/me` | Current user profile |
| PATCH | `/auth/me` | Update profile |

## Namespaces & Projects

| Method | Path | Description |
|--------|------|-------------|
| GET | `/auth/namespaces` | List public namespaces (no auth) |
| GET | `/namespaces/:slug` | Namespace overview with asset counts |
| PATCH | `/namespaces/:slug` | Update namespace (owner only) |
| GET | `/namespaces/:slug/projects` | List projects |
| POST | `/namespaces/:slug/projects` | Create project |
| PATCH | `/namespaces/:slug/projects/:proj` | Update project |

For GraphQL project/Note reads and equivalent REST association and choice views,
see [Project and Note queries](/api/project-queries.md).

## Episodes

| Method | Path | Description |
|--------|------|-------------|
| POST | `/namespaces/:slug/projects/:proj/episodes` | Create/upsert episode |
| GET | `/namespaces/:slug/projects/:proj/episodes` | List episodes (paginated) |
| PATCH | `/namespaces/:slug/projects/:proj/episodes/:name` | Update episode |

## Nodes (File Tree)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/nodes` | Create node (auto-creates hierarchy) |
| GET | `/nodes` | List nodes by namespace/project/kind |
| GET | `/nodes/children` | List 1-level children |
| GET | `/nodes/lookup` | Resolve node by materialized path |
| GET | `/nodes/:id/descendants` | All descendants (recursive) |
| GET | `/nodes/:id/contents` | Episodes + files (paginated) |
| GET | `/nodes/:id/download` | Presigned S3 download URL |
| PATCH | `/nodes/:id` | Update node (name, move, tags) |
| DELETE | `/nodes/:id` | Hard-delete node + descendants |

## Files

| Method | Path | Description |
|--------|------|-------------|
| POST | `/episodes/:id/files` | Upload file (multipart) |
| GET | `/episodes/:id/files` | List files |
| GET | `/episodes/:id/files/:fid/download` | Download file |
| DELETE | `/episodes/:id/files/:fid` | Delete file |

## Tracks & Logs

| Method | Path | Description |
|--------|------|-------------|
| POST | `/episodes/:id/tracks/:name/append` | Append data point |
| POST | `/episodes/:id/tracks/:name/append-batch` | Append batch |
| GET | `/episodes/:id/tracks/:name/data` | Read track data |
| GET | `/episodes/:id/tracks` | List tracks |
| POST | `/episodes/:id/logs` | Create log entries |
| GET | `/episodes/:id/logs` | Query logs (level, time, search) |

## Parameters

| Method | Path | Description |
|--------|------|-------------|
| POST | `/episodes/:id/parameters` | Set/merge parameters |
| GET | `/episodes/:id/parameters` | Get parameters |
| DELETE | `/episodes/:id/parameters` | Soft-delete |

## Bindrs & Datasets

| Method | Path | Description |
|--------|------|-------------|
| POST | `…/bindrs` | Create bindr |
| GET | `…/bindrs` | List bindrs |
| GET | `…/bindrs/:name` | Get bindr |
| PATCH | `…/bindrs/:name` | Update bindr |
| DELETE | `…/bindrs/:name` | Soft-delete |
| POST | `…/bindrs/:name/members` | Add members |
| DELETE | `…/bindrs/:name/members` | Remove members |
| POST | `…/datasets` | Create dataset |
| GET | `…/datasets` | List datasets |
| GET | `…/datasets/:name` | Get dataset with bindrs |
| PATCH | `…/datasets/:name` | Update dataset |
| DELETE | `…/datasets/:name` | Soft-delete |

All bindr/dataset paths are under `/namespaces/:slug/projects/:proj/`.

## Artifacts

Renderable, versioned documents with per-artifact visibility — the surface
behind [`dreamlake artifact`](/cli.md#artifacts). Public/list/read routes apply
per-artifact policy themselves (member / public / valid share).

| Method | Path | Description |
|--------|------|-------------|
| GET | `/namespaces/:slug/artifacts` | Catalog list (members: all; others: public only). `?deleted=true` lists the Trash (members) |
| GET | `/namespaces/:slug/artifacts/:id` | One catalog row + `viewerCanManage` (`?share=` for share links) |
| POST | `/namespaces/:slug/artifacts/upload-credentials` | Mint scoped STS creds for a push (member) |
| POST | `/namespaces/:slug/artifacts/:id` | Upsert catalog entry — metadata / visibility / share token (member) |
| POST | `/namespaces/:slug/artifacts/read-token` | Mint a short-lived per-artifact read token |
| GET | `/namespaces/:slug/artifacts/read/:token/*` | Read-proxy: stream artifact objects (Range-aware) |
| DELETE | `/namespaces/:slug/artifacts/:id` | Soft delete → Trash (member) |
| POST | `/namespaces/:slug/artifacts/:id/restore` | Restore from Trash (member) |
| DELETE | `/namespaces/:slug/artifacts/:id/purge` | Permanent purge — storage + catalog, irreversible (member) |
| GET | `/me/artifacts` | Signed-in user's artifacts: yours + shared-with-you, tagged by group |

## Envs

Versioned simulation environments (MJCF + assets) — the surface behind
[`dreamlake env`](/cli.md#envs). Env file bytes never transit the API: uploads go
straight to storage with brokered STS credentials, and reads hand back one
presigned URL per file. Public routes apply per-env policy themselves; a
hidden env answers **404**, never 403.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/namespaces/:slug/envs` | Catalog list (members: all; others: public only). `?deleted=true` lists the Trash (members) |
| GET | `/namespaces/:slug/envs/:name` | One catalog row + `viewerCanManage` + `thumbVersion` |
| GET | `/namespaces/:slug/envs/:name/versions` | All pushed versions, newest first |
| GET | `/namespaces/:slug/envs/:name/versions/:version` | One version's manifest — `entry` + per-file `{path, size, hash, url}` with presigned GETs (`:version` int or `latest`) |
| POST | `/namespaces/:slug/envs/upload-credentials` | Mint STS creds scoped to `envs/<ns>/<name>/` for a push (member) |
| POST | `/namespaces/:slug/envs/:name` | Register a pushed version (create-or-revive, `latestVersion = max`), or patch title/description/envType/visibility (member) |
| POST | `/namespaces/:slug/envs/:name/thumbnail` | Store the browser-captured PNG thumbnail, ≤ 512 KB (member) |
| DELETE | `/namespaces/:slug/envs/:name` | Soft delete → Trash (member) |
| POST | `/namespaces/:slug/envs/:name/restore` | Restore from Trash (member) |
| DELETE | `/namespaces/:slug/envs/:name/purge` | Permanent purge — whole storage prefix + catalog, irreversible (member) |

## Libraries

Asset collections stored verbatim under one storage prefix, searchable per
asset — the surface behind [`dreamlake library`](/libraries.md). Payload bytes
never transit the API: uploads and downloads run on presigned batches straight
to storage. Public routes apply per-library policy themselves (member /
`public` visibility / valid `?share=<token>`); a hidden library answers
**404**, never 403.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/namespaces/:slug/libraries` | Catalog list (members: all; others: public only). `?deleted=true` lists the Trash (members) |
| GET | `/namespaces/:slug/libraries/:name` | One catalog row (`LibraryDetail`) + `viewerCanManage` |
| GET | `/namespaces/:slug/libraries/:name/manifest` | The full parsed wire manifest (`dreamlake.assets/v1`), served verbatim |
| GET | `/namespaces/:slug/libraries/:name/assets/:assetId` | One asset with presigned per-file URLs — the preview payload (`?ttlSeconds`) |
| POST | `/namespaces/:slug/libraries/:name/files-presign` | Presigned GETs for manifest paths, ≤ 1,000 per batch — the pull payload (`ttlSeconds`) |
| GET | `/namespaces/:slug/libraries/:name/search` | Search inside one library (`q`, `category`, `kind`, `license`, `tag`, `limit` ≤ 200, `offset`) |
| GET | `/libraries` | Visible libraries across namespaces, newest first (`limit` ≤ 500) |
| GET | `/library-search` | Cross-library search over `libraries=ns/a,ns/b` (≤ 50); inaccessible targets land in `skipped[]` |
| POST | `/namespaces/:slug/libraries/:name/upload-authorizations` | Presigned upload batch for a push (member) |
| POST | `/namespaces/:slug/libraries/:name/register` | Validate the uploaded manifest, bump `revision` (CAS — stale `expectedRevision` → 409), reconcile storage (member) |
| POST | `/namespaces/:slug/libraries/:name` | Patch `visibility` / share token — content metadata is manifest-derived (member) |
| DELETE | `/namespaces/:slug/libraries/:name` | Soft delete → Trash (member) |
| POST | `/namespaces/:slug/libraries/:name/restore` | Restore from Trash (member) |
| DELETE | `/namespaces/:slug/libraries/:name/purge` | Permanent purge — storage prefix + catalog, irreversible (member) |

Full request/response schemas, the manifest contract, and agent read patterns
live in [Libraries Reference](/libraries/reference.md).

## LLM Relay

Pass-through to a chat-model API using your DreamLake token instead of a
provider key — the surface behind [LLM Relay](/relay.md). The path under
`/relay/:provider/` is forwarded to the provider verbatim, so its whole API is
reachable. Authenticate with `Authorization: Bearer` **or** `x-api-key`.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/relay/providers` | Which providers this deployment can relay to, and the base URL for each |
| POST | `/relay/:provider/v1/messages` | Relay a chat completion (`stream: true` streams SSE straight back) |
| POST | `/relay/:provider/v1/messages/count_tokens` | Relay a token count |
| GET | `/relay/:provider/v1/models` | Relay the provider's live model list |

## Search

| Method | Path | Description |
|--------|------|-------------|
| POST | `/projects/:id/search` | Project-wide vector search |
| POST | `/projects/:id/episodes/:eid/search` | Episode-scoped search |
| POST | `…/assets/search` | Semantic search (CLIP text/image) |

## Health

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Server status (no auth) |

## Next steps

    The command-line wrapper over these endpoints.

    The data model and auth flow behind the paths on this page.

---

Source: https://docs.dreamlake.ai/annotations/reference

# Annotations Reference

  The complete API of `dreamlake.annotation`: the generic `Annotation` for
  custom-schema data (with `Schema` and `Track`), the
  `VideoAnnotation` preset (`video.annotation/v2`) with its
  `Episode` handle, and the storage rules that explain the constraints.

New here? Start with the step-by-step [Annotations guide](/annotations.md).

## The annotation family

Every DreamLake annotation is a **catalog row** (name, `schemaType`,
visibility) plus a **dreamdb space** (the data). `schemaType` is the one
dispatch key, applied the same way everywhere:

| consumer | known schemaType | unknown schemaType |
| --- | --- | --- |
| `Annotation.open` | returns the preset subclass (`video.annotation/v2` → `VideoAnnotation`) | returns the generic `Annotation` |
| web app | rich view | catalog entry (generic track browser: roadmap) |
| `Annotation.list(schema_type=…)` | server-side filter | same |

Unknown never refuses — data written by newer tools stays readable
generically.

**Names.** Every name-taking classmethod accepts `"name"` (your own
namespace) or `"namespace/name"` (an organisation you belong to; the server
authorizes per request). A leading `@` on the namespace is tolerated. At
most one `/`.

## Annotation (custom schemas)

```python
from dreamlake.annotation import Annotation, Schema, Track, sequence_anchors
```

### Lifecycle (classmethods)

| method | meaning |
| --- | --- |
| `Annotation.create(name, *, schema=None, schema_type=None, visibility="private")` | create. `schema=None` starts empty — declare tracks as you go (embeddings excepted: create-time only). `schema_type` is your own dispatch label, default `"custom/v1"`; a registered preset type errors and points at the preset's own `create` |
| `Annotation.ensure(name, *, schema=None, schema_type=None, visibility="private")` | open-or-create, rerun-safe. Existing annotations are **verified, never widened**: an explicitly expected `schema_type` errors on mismatch, and every field of `schema=` must already be declared |
| `Annotation.open(name)` | open; dispatches by the catalog's schemaType (see table above) |
| `Annotation.list(namespace=None, schema_type=None)` | `list[AnnotationInfo]` — `name`, `namespace`, `schema_type`, `visibility` |
| `Annotation.delete(name, *, purge=False)` | remove the catalog row; `purge=True` also deletes storage. A classmethod on purpose: no open, no credentials — and a safe distance from row-level `ann.db.delete(anchors)` tombstones |

### Tracks — the schema, in its live form

There is no `ann.schema`: `ann.tracks()` IS the schema — each `Track` handle
carries `name` / `kind` / `mime` / `dim`.

| method | meaning |
| --- | --- |
| `ann.add_track(name, kind, *, mime=None) -> Track` | declare a track (evolution is by addition only). Idempotent for a matching re-declaration; a kind change errors. `"embedding"` refused post-create |
| `ann.track(name) -> Track` | the handle; an unknown name errors here, eagerly |
| `ann.tracks() -> list[Track]` | every declared track |

`kind` is the dreamdb vocabulary, verbatim: `"video"` / `"image"` (with
`mime=`; JSON documents are `kind="image", mime="json"`) / `"scalar_float"`
/ `"scalar_int"` / `"scalar_bool"` / `"scalar_string"` /
`"scalar_categorical"` / `"scalar_timestamp"`. Track names:
`^[a-z0-9][a-z0-9_]*$`, max 64 chars; `anchor`, `_anchor`,
`_time_anchors` are reserved.

Tracks added through the bare `ann.db` handle are invisible to `tracks()`
(the SDK keeps a fields mirror in the space meta, key
`dreamdb.dataset.fields`); another process's `add_track` becomes visible
after `ann.reload()`.

### Row-wise write / read

| method | meaning |
| --- | --- |
| `ann.append_rows(rows) -> {"rows": n}` | one commit for the batch. Each row: `{"anchor": ns, track: value, ...}`. Sparse rows are the norm — **omit a field rather than passing None** |
| `ann.rows(start=None, end=None, tracks=None)` | rows in `[start, end)`, sorted, sparse (absent field = absent key). Video tracks are excluded by default; naming one in `tracks=` errors |

**Round-trip contract:** `rows()` returns exactly the shape `append_rows()`
accepts, and `t.read()` exactly what `t.append_range()` accepts —
`ann2.append_rows(ann1.rows(…))` needs no conversion.

### Introspection and recovery

| method | meaning |
| --- | --- |
| `ann.anchors(start=None, end=None) -> list[int]` | every item anchor, ascending — count (`len`), span (ends), upload verification |
| `ann.reload() -> ann` | refresh in place: catalog row, fields mirror, credential lease. Track handles survive. The fix for both documented stalenesses (cross-process `add_track`; the 12 h lease) |
| `ann.schema_type` / `ann.namespace` / `ann.name` | identity |
| `ann.visibility` / `ann.set_visibility("public")` | public annotations get anonymous presigned reads |
| `ann.db` | the live `dreamdb.Dataset` — the escape hatch. The meta keys `dreamdb.schema_type` / `dreamdb.dataset.*` are the SDK's; overwriting them breaks the handle |

### Anchors

Absolute int nanoseconds. Everywhere an anchor or range bound is taken,
a **tz-aware** `datetime` also works (naive datetimes are refused, not
guessed). Sequential data with no clock of its own uses row indices:
`sequence_anchors(n, start=0, step=1)`; continue an existing annotation from
`ann.anchors()[-1] + 1`.

### Write semantics (read this before scripting)

- **Append-only, write-once.** Re-writing the same (anchor, track) is
  undefined — the engine resolves same-anchor duplicates by content order,
  not write order. The SDK rejects duplicates within one batch; across
  calls it is on you. There is no update verb in v1.
- **Every `append*` / `ingest` call is one commit** (a new manifest, the
  ref advances). Batch with `append_rows` / `append_range`; a loop of
  single-point appends is slow and churns the ref history.
- **One writer per annotation at a time.** Concurrent writers lose updates.
  Readers are unrestricted.
- **Credentials are a 12 h lease** brokered at open. A stale handle raises
  `AnnotationError("credentials expired — call ann.reload()")`. One active
  platform annotation per process (the lease rides process-level AWS env
  vars).

## Schema

Mirrors `dreamdb.Schema` one-to-one — same method names, same parameters,
chainable — with two twists: every declaration is **recorded** (dreamdb's
own Schema cannot be introspected once built), and `required` is pinned
`False` (a required field could never be added later; all-optional is what
keeps `add_track` available).

```python
sch = Schema()
sch.add_video("cam", mime="h264")
sch.add_image("thumb", mime="jpeg")
sch.add_image("meta", mime="json")              # JSON documents, the dreamdb way
sch.add_embedding("clip", dim=512, lsh_bits=14) # create-time only
sch.add_scalar_float("temp")                    # ... _int/_bool/_string/_categorical/_timestamp

sch = Schema.from_fields([{"name": "cam", "type": "video", "mime": "h264"}, ...])
sch.to_fields()                                 # round-trip; the wire format
```

`to_fields()` / `from_fields()` carry the `fields` wire format (also
stamped into the catalog's `schemaJson` and the space meta). Validation is
eager and actionable: bad/reserved/duplicate names, `video` without
`mime`, `embedding` without an int `dim`, `required=True`, and `add_audio`
(unsupported — the engine cannot ingest it yet) all error at declaration.

## Track

Column-wise reads and writes. One verb, `append`, with the shape in the
name: no suffix = one point at a specific anchor, `_range` = a stretch of
timeline (and `ann.append_rows` = the row-wise member of the same family).

| method | meaning |
| --- | --- |
| `t.append(anchor, value) -> {"items": 1}` | one data point at one anchor |
| `t.append_range(items) -> {"items": n}` | `(anchor, value)` pairs — sorted by the SDK, one commit; a duplicate anchor within the batch errors (write-once) |
| `t.get(anchor)` | the value at exactly `anchor`, else `None` |
| `t.read(start=None, end=None)` | `[(anchor, value)]` in `[start, end)`, sorted. A declared-but-never-written track reads `[]` |
| `t.ingest(src, *, anchor, frag_seconds=2.0, height=None)` | video tracks only — see below |
| `t.name` / `t.kind` / `t.mime` / `t.dim` | metadata (`dim` on embeddings) |

**Values.** dreamdb's native representations pass through untouched:
`bytes` for blobs, int ns for timestamps, native scalars, float vectors.
On top, one-way input conveniences: file paths (`image`), tz-aware
`datetime` (`scalar_timestamp` and every anchor), `dict`/`list` on
`mime="json"` tracks, `.npy` paths and ndarrays (`embedding`,
dim-checked). Scalars are strict — `bool` into `scalar_float` errors
rather than coercing. `None` is always refused: absence is an omitted
field, not a null. Reads return the stored representation as-is, with one
exception: `mime="json"` tracks decode back to the `dict`/`list` that
went in.

**Video.** `t.ingest` is the only write path for video tracks
(`append` on one errors and says so). `height=None` is a lossless remux —
fast, but a CMAF track accepts exactly one codec configuration, so every
clip on the track must be identically encoded. `height=N` re-encodes to a
uniform h264 profile so mixed sources can share a track. Each clip
occupies `[anchor, anchor + duration)`; overlapping an existing span is
refused up front. Ranged video *reads* are not in v1 — playback goes
through the platform, raw bytes via `ann.db`.

## VideoAnnotation (the `video.annotation/v2` preset)

```python
from dreamlake.annotation import VideoAnnotation
```

An annotation of **episodes**: one recording each — one or more **camera**
videos on a shared clock, plus per-frame joint annotations and action
segments. Each episode owns a one-hour timeline slot; every camera,
annotation and search vector of the episode lives inside that slot, which
is why multi-camera playback is time-aligned with zero bookkeeping.
Per-episode operations live on the `Episode` handle.

The preset subclasses the generic `Annotation` and registers its schemaType:
`Annotation.open` on one of these returns this class.

### `VideoAnnotation.create(name=None, *, backend=None, visibility=None, preview_height=720, preview_fps=30.0, frag_seconds=2.0)`

| param | meaning |
| --- | --- |
| `name` | platform mode: catalog entry + managed bucket (needs `dreamlake login` / `DREAMLAKE_API_KEY`). Accepts `namespace/name` |
| `backend` | self-hosted mode: `file:///abs/path` or `https://…` S3 URL — no platform involved |
| `visibility` | `"private"` (default) / `"public"`; public annotations omit absolute source paths from metadata |
| `preview_height` / `preview_fps` / `frag_seconds` | the **encoding profile** — playback resolution, frame rate, and fragment length. Chosen once, for the annotation's lifetime, stored in the space meta. Per-episode calls never pass encoding |

Creation is never idempotent: an existing name/path errors instead of
silently forking a second history. (`VideoAnnotation.ensure(name)`
is the open-or-create form; it takes no schema arguments — the preset owns
its schema.)

### `VideoAnnotation.open(name=None, *, backend=None, preview_height=None, preview_fps=None, frag_seconds=None)`

Open by platform name or backend URI, strictly — a space stamped with a
different schemaType is refused (use `Annotation.open` or `dreamlake.db` for
those). The optional encoding kwargs **verify, never set**: pass the
values your script assumes and `open()` errors on mismatch — so the
`try open / except create` idiom cannot silently eat a config edit.

### `ann.add_episode(videos, *, episode_id=None, joints_pose=None, subtasks=None, recon_mesh=None, recon_pose=None, recon_camera=None, recon_hands=None, recon_gravity=None, meta=None, gid=None, raw=False) -> Episode`

The upload. One call transcodes every camera for browser playback and
commits annotations + metadata atomically. Returns the `Episode` handle;
the ingest report (per-camera fragment counts, annotation counts) is on
`epo.report`.

| param | meaning |
| --- | --- |
| `videos` | one path (single camera, stored as `main`) or `{camera: path}`. Camera names: `[a-z0-9_-]`, no `__` |
| `joints_pose` | a doc (binds to the **primary** camera — `main` if present, else the first) or `{camera: doc}` to annotate several views. Docs may also be JSON file paths |
| `subtasks` | episode-level action segments (doc or path) |
| `recon_mesh` | 3D-reconstruction: object meshes `{object: obj_text}` (episode-level, no camera) |
| `recon_pose` `recon_camera` `recon_hands` `recon_gravity` | 3D-reconstruction, per camera: object 6-DoF poses / pinhole intrinsics / MANO hands / gravity up-vector. Bare doc → primary camera, or `{camera: doc}`. All optional — see [Annotation formats](#annotation-formats) |
| `meta` | labels: `{"task": ..., "scene": ...}` — whitelist-only, **nothing is inferred** |
| `gid` | pin a specific slot (rarely needed) |
| `raw` | `True` additionally archives a lossless remux (roughly doubles the upload; best-effort on mixed sources) |

Fails fast, before any transcoding: any camera ≥ 3600 s, duplicate
`episode_id`, unknown meta key, joints naming a camera not in `videos`,
annotation fps disagreeing with its camera by >10 accumulated frames, or an
aspect ratio differing from that **camera's** existing track (aspect is per
camera — head 4:3 and wrist 16:9 coexist).

### `ann.episode(episode_id)` / `ann.episodes(after_gid=None, limit=None)` / `ann.episode_count()`

Lookup, listing, and count — all scale-safe: id lookups and counts go
through a slim per-episode index track (a `scalar_string` of bare ids —
one cacheable fetch yields the whole id→slot map; the fat `episode_meta`
column is only ranged-read for the slots actually needed).
Bare `episodes()` is the full listing (fine up to a few thousand); past
that, page: `episodes(limit=100)` then
`episodes(after_gid=page[-1].gid, limit=100)` — each page is one
slot-window read. `[e.meta for e in ann.episodes()]` recovers plain dicts.

### `ann.cameras() -> list[str]` / `ann.tracks() -> list[Track]`

What is in this annotation. `cameras()` is the union over episodes, `main`
first. `tracks()` returns the same `Track` handles as the generic layer
(name/kind/mime/dim) plus the preset extras `role` (`video_preview`,
`joints_pose`, `subtasks`, `recon_mesh`, `recon_pose`, `recon_camera`,
`recon_hands`, `recon_gravity`, `episode_meta`, `search`, `user`), `camera`,
and the derived `preset` flag. Preset reads still go through the named
APIs (`read_joints_pose`, `epo.read_track`, …).

### `ann.add_track(name, kind, *, mime=None) -> Track`

Declare a custom column. Same kind vocabulary as the generic layer, with
one extra rule: names must match `^x_[a-z0-9_]+$` — the user namespace the
preset promises never to claim, so your columns can never collide with a
future SDK release. Re-declaring the same name+kind is idempotent; changing
a track's kind is refused; embeddings cannot be added after creation. The
web viewer does not render `x_*` tracks; they are first-class data for
training loaders. Write and read through the Episode handle.

### `ann.embed_episodes(*, camera=None, fps=1.0, source_dir=None, batch_size=32) -> dict`

The search sweep: for **every** episode, sample frames at `fps` from one
camera's source file (primary unless `camera=`), encode with CLIP, encode
subtask texts with BGE, upload. Episodes commit one at a time — interrupt
and re-run freely. `source_dir` locates moved files via each camera's
recorded `source_rel`. Needs `pip install "dreamlake[search]"`. One episode
= `epo.embed()`.

### `ann.search(query, top_k=10, kind="both") -> list[dict]`

Natural-language moments: CLIP text tower against frame vectors and/or BGE
against subtask texts, fused by reciprocal rank. Returns
`[{"episode_id", "time_sec", "score", "source", "subtask"?}]`.
`kind`: `"frames"` / `"subtasks"` / `"both"`.

### `ann.encoding` / `ann.db`

`encoding` — the stored profile, read-only: the create-time defaults plus
`cameras`, each camera track's **adopted playback profile**
(`{width, height, fps}`, fixed by the aspect ratio of that camera's first
clip; every later clip is validated against it before any transcoding).
`db` — the live dreamdb handle:
the escape hatch for anything outside the preset (absolute-anchor appends,
columnar bulk reads, branching). Layout invariants are yours to respect.

## Episode

Obtained from `add_episode` / `ann.episode(id)` / `ann.episodes()`. The
identity triple (`episode_id`, `gid`, `anchor`) is immutable — handles never
dangle. The meta snapshot is a read convenience; **every write re-reads the
stored metadata at call time**, so a stale handle can never clobber a newer
revision.

| member | meaning |
| --- | --- |
| `episode_id` / `gid` / `anchor` | identity: your stable id, the slot number, the slot's base time |
| `report` | ingest report (only on the handle `add_episode` returned) |
| `meta` / `cameras` / `task` / `scene` / `duration_s` | snapshot reads, zero IO |
| `refresh()` | re-read metadata, returns self |
| `info()` | fresh meta + annotation summaries per camera (does IO) |

### Reads

```python
epo.read_joints_pose(camera=None)   # default: primary camera; None if unannotated
epo.read_subtasks()                 # episode-level; None if absent

# 3D reconstruction — one method per piece (default: primary camera):
epo.read_recon_mesh()               # episode-level {object: {obj, scale}} | None
epo.read_recon_pose(camera=None)    # {"frames": {...}} | None
epo.read_recon_camera(camera=None)  # intrinsics {fx,fy,cx,cy,width,height} | None
epo.read_recon_hands(camera=None)   # {"faces","frames"} | None
epo.read_recon_gravity(camera=None) # {"vec3d": [...]} | None
```

### `epo.add_cameras(videos, *, joints_pose=None, raw=False) -> dict`

Late-arriving cameras — add-only (video fragments occupy their slot and
cannot be replaced; re-sending an existing camera errors). Dict form adds N
cameras with one metadata write.

### `epo.revise(*, joints_pose=None, subtasks=None, recon_mesh=None, recon_pose=None, recon_camera=None, recon_hands=None, recon_gravity=None, meta=None) -> dict`

The one revision verb: everything passed lands in **one committed row**.
Storage is append-only — a revision is a new version, readers see the
newest, history stays addressable. `meta` takes the same whitelist as
`add_episode`; there is no inference, and passing values identical to what
is stored is reported as an error rather than a silent no-op.

### Custom-track values (declare with `ann.add_track` first)

```python
epo.set_track("x_quality", {"blurry": False})        # one value per episode (t=0)
epo.set_track("x_reward", 0.75, t_sec=12.0)          # or at any in-slot time
epo.append_track("x_reward", [(1.0, 0.1), (2.0, 0.2)])   # batch, one commit
epo.get_track("x_quality")                            # -> value | None
epo.read_track("x_reward", start_sec=0, end_sec=None) # -> [(t_sec, value)]
```

Values follow the track's kind (dicts/lists round-trip as JSON on
`image/json` tracks). Timestamps are seconds on the episode's own clock and
are bounds-checked to the slot. Re-writing the same (track, time) is a
revision — the preset's episode clock has revision semantics the generic
layer's absolute anchors do not. For high-rate series and cross-episode
bulk reads, drop to the engine with `epo.anchor_at(t_sec)` +
`ann.db.append_many` / `ann.db.iter_all_batches(fields=[...])`.

### Search, single episode

```python
epo.embed(camera=None, fps=1.0, video_path=None, source_dir=None, batch_size=32)
epo.add_search_vectors(frame_vecs=[(t, vec512), ...],        # CLIP space, L2-normed
                       subtask_vecs=[(t, vec384, label), ...])  # BGE space
```

`embed` resolves the source file `video_path` → `source_dir`/`source_rel` →
recorded absolute path, and refuses a resolved file whose duration
disagrees with the ingested camera's (wrong file); an explicit `video_path`
overrides the check. Vectors are searchable the moment they land — there is
no index-build step.

## Annotation formats

Wire-compatible with the web viewer's overlays. Joint coordinates live in
the pixel space of the camera whose track holds the document.

```jsonc
// joints_pose — per camera, one doc per episode
{
  "width": 1920, "height": 1080,   // REQUIRED: annotation-time pixel space
  "src_fps": 29.987,               // REQUIRED: frame k renders at k / src_fps
  "joint_order": ["wrist", ...],   // optional: names, index-aligned
  "bones": [[0, 1], ...],          // optional: skeleton edges
  "frames": {                      // REQUIRED, sparse: only annotated frames
    "0": [{"keypoints_2d": [[x, y], ...],           // REQUIRED per detection
           "is_right": 1, "det_conf": 0.9}]          // optional
  }
}

// subtasks — episode-level, one doc per episode
{
  "task": "wash the dishes",       // optional, NOT copied to episode meta
  "labeled_subtasks": [            // REQUIRED; gaps are fine
    {"start_sec": 0.0, "end_sec": 2.5, "subtask": "pick up plate"}
  ]
}
```

### Reconstruction (3D)

An optional third modality: 3D hand–object reconstruction, as five flat
`recon_*` arguments (one per stored track). Geometry is in the camera's
**OpenCV frame** (x-right / y-down / z-forward), metres, quaternion **wxyz**,
frame `f` ↔ time `f/fps`; colour is not stored. `recon_mesh` is episode-level;
the other four are per-camera (bare doc → primary, or `{camera: doc}`).

```python
epo = ann.add_episode(
    video, subtasks=..., joints_pose=...,
    recon_mesh={name: obj_text},                          # or {name: {"obj","scale"}}
    recon_pose={frame: {name: {"t":[x,y,z], "q":[w,x,y,z]}}},
    recon_camera={"fx":.., "fy":.., "cx":.., "cy":..},    # pinhole intrinsics (→ recon_camera__<cam>)
    recon_hands={"faces": {"left":[[a,b,c]...], "right":[...]},   # optional
                 "frames": {frame: {"left": {"verts":[[x,y,z]...], "joints":[[x,y,z]...]}, "right": {...}}}},
    recon_gravity=[x, y, z],                              # optional; up direction
)
epo.revise(recon_pose={"left": ...}, recon_camera={"left": ...})   # fill a camera in later
```

Each is optional; at least one present. Re-passing a piece revises it. `recon_pose`
tells a bare per-frame doc from a `{camera: doc}` map by whether the keys are
frame indices vs camera names — so don't name a camera a bare number.

## Storage semantics worth knowing (preset)

- **Slots.** Episode `gid` occupies `[gid × 1 h, (gid+1) × 1 h)` on one
  timeline; slots are never reused; any single camera clip ≤ 3600 s.
- **Encoding is annotation-lifetime.** Every clip on one camera track shares
  one init segment, so height/fps/fragment length cannot vary per episode —
  that is why they live on `create`, not `add_episode`.
- **Aspect ratio is per camera track**, not per annotation.
- **Revisions are versioned, bounded, and never in-place.** Each
  episode-level value carries up to 1024 revisions; readers always resolve
  to the newest; history stays in the timeline.
- **Video is add-only.** Cameras can join an episode; fragments are never
  replaced.
- **`x_` is yours, everything else is the contract.** Preset track names
  and metadata keys evolve only by addition, in SDK releases; tools render
  what they recognize and skip the rest.

---

Source: https://docs.dreamlake.ai/api/project-queries

# Project and Note queries

This reference describes the implementation branch. It does not establish that
these fields are deployed to staging or production. Verify the target server's
schema before switching a client. Existing mutation routes remain REST; Note
content, CRDT synchronization, and revision-protected editing are unchanged.

## Separate associations from choices

| Question | GraphQL | REST |
|---|---|---|
| Which projects can this viewer access? | `projectCatalog` | `GET /namespaces/:namespace/projects?search=design&page=1&pageSize=50` |
| Where is this Note actually associated? | `note.nodes` | `GET /namespaces/:namespace/resources/note/:noteId/projects?view=nodes` |
| Which Bindrs can the picker offer in this project? | `bindrs` | `GET /namespaces/:namespace/projects/:projectSlug/bindrs?view=choices&search=design&first=20` |

The GraphQL resolvers and these REST views use the same underlying visibility,
project permission, resource-readability, and association services. Their wire
shapes differ: GraphQL selects fields and wraps results in `data`; REST returns
its resource response directly. The `view=nodes` REST association view permits
authorized anonymous reads of public resources; the legacy default response
requires a signed-in caller. Unreadable resources are not exposed by the shared
service.

The existing resource-project REST response without `view=nodes` remains a
compatibility response that mixes candidate projects with `bound` and `canBind`.
New clients should use the views above instead. The existing Bindr response
without `view=choices` also keeps its prior tree-list contract.

## Query a Note's locations

```graphql
query NoteLocations($namespace: String!, $noteId: ID!) {
  note(namespaceSlug: $namespace, id: $noteId) {
    id
    name
    nodes {
      id
      name
      path
      project {
        id
        slug
        displayName
      }
      bindrs {
        id
        name
        parentId
      }
    }
  }
}
```

Variables below use illustrative values. Replace them with a namespace and Note
ID that the caller can read:

```json
{
  "namespace": "example-team",
  "noteId": "000000000000000000000001"
}
```

`nodes` contains actual resource Nodes in visible projects, never candidate
projects. An empty list means no visible associations, not proof that no hidden
association exists. An unreadable or missing Note returns `note: null`.

`Node.path` is the existing comma-delimited **ancestor path**, not the full file
path or a parent ID. For example, a Node named `API design` with
`path: ",example-project,design-docs,"` sits beneath that ancestor path. Project
ownership comes from `projectNodeId` and the resolved `project`, not parsing the
path. No folder or storage migration is part of these reads.

`node.bindrs` means Bindrs **tagging that Node**, not every Bindr owned by the
project. It is resolved through membership records. Project objects retain the
GraphQL `Node` type and stable ID for Apollo normalization.

The equivalent REST view returns `{ nodes, total }`; each Node includes its
project and attached Bindrs. No `bound` or `canBind` field is needed in that view.

## Search project choices

```graphql
query ProjectChoices($namespace: String!, $search: String, $page: Int, $pageSize: Int) {
  projectCatalog(namespaceSlug: $namespace, search: $search, page: $page, pageSize: $pageSize) {
    projects {
      id
      slug
      displayName
      permissions {
        role
        project { read update delete manageGrants }
        content { read create delete }
      }
    }
    total
    page
    pageSize
    totalPages
    canCreate
  }
}
```

```json
{
  "namespace": "example-team",
  "search": "design",
  "page": 1,
  "pageSize": 50
}
```

The catalog is scoped to one namespace and returns authorized projects,
including project-specific grants. Search is performed on the server. The
default page size is 50; the maximum is 200. Fetch subsequent pages when needed
instead of treating the first page as the complete set of projects.

`canCreate` is permission to create a project in the namespace.
`permissions.content.create` is permission to add content within a particular
project. For an add-project picker, exclude projects already present in
`note.nodes` and offer projects with content creation permission. The mutation
still checks both project authorization and resource readability; a successful
read is not a grant that remains valid indefinitely.

## Search Bindr choices on demand

```graphql
query BindrChoices($projectId: ID!, $search: String, $first: Int, $after: String) {
  bindrs(projectId: $projectId, search: $search, first: $first, after: $after) {
    nodes { id name parentId projectNodeId }
    pageInfo { endCursor hasNextPage }
  }
}
```

```json
{
  "projectId": "000000000000000000000002",
  "search": "design",
  "first": 20,
  "after": null
}
```

The default page size is 20; the maximum is 100. Run this only when the picker needs choices. For another page, pass the returned
`endCursor` as `after`; reset the cursor whenever the project or search changes.
Treat cursors as opaque. REST uses the same `{ nodes, pageInfo }` response shape
and accepts the cursor as an URL-encoded `after` query parameter. The REST path
identifies the project by namespace and slug; GraphQL uses its Node ID.

These are live listings, not transactionally frozen snapshots. Concurrent edits
may change choices between requests. Mutations remain authoritative and must
revalidate permissions and membership constraints.

## Execute a GraphQL request

Save any query above to `query.graphql` and its variables to `variables.json`.
Set the API base URL and an existing DreamLake token in your shell environment:

```bash
export DREAMLAKE_API_URL='http://localhost:3001'
# Set DREAMLAKE_TOKEN securely to your existing token; do not commit it.
python3 - <<'PY'
import json
import os
import urllib.request

with open('query.graphql') as source:
    query = source.read()
with open('variables.json') as source:
    variables = json.load(source)
request = urllib.request.Request(
    os.environ['DREAMLAKE_API_URL'].rstrip('/') + '/graphql',
    data=json.dumps({'query': query, 'variables': variables}).encode(),
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + os.environ['DREAMLAKE_TOKEN'],
    },
)
with urllib.request.urlopen(request) as response:
    result = json.load(response)
if result.get('errors'):
    raise RuntimeError(result['errors'])
print(json.dumps(result['data'], indent=2))
PY
```

GraphQL errors can arrive with HTTP 200; inspect `errors` before using `data`.
For Apollo clients, select stable IDs and keep project objects as `Node`.
Refresh associations after existing REST mutations. Cancel superseded picker
requests, prevent stale identity responses from entering the cache, and isolate
explicit anonymous previews from authenticated cache entries.

---

Source: https://docs.dreamlake.ai/envs/layers

# Env Layers Reference

  The complete contract of `dreamlake.layers.json` (schema
  `dreamlake.env-layers/v3`): one component grammar, five ops, the
  composition semantics, six annotated stacks, and the errors you will
  actually hit.

New here? Start with the [Envs guide § Env layers](/envs.md#env-layers).

## The model

A layered env is an ordered **stack** of ops. Every stack entry is one
flat object — `{"tag": ..., ...props}` — in the vocabulary of vuer's
imperative session updates (`add` / `upsert` / `update` / `remove`), where
`Update` is a *meta component*: its `key` addresses an element, its props
ARE the opinions. No op has a privileged role — "scene", "embodiment",
"physics profile" are things you *do* with layers, not schema concepts.
Ops apply in order and **later wins, always**. `dreamlake env compose`
materializes the stack into an ordinary `mujoco` env directory — entry
XML, flat assets, and a fully **pinned** copy of the stack side by side —
and `dreamlake env push` publishes it as a normal env version. Consumers
(viewer, SDKs, training code) read only the materialized artifact; the
embedded stack is what makes the env permanently re-openable: edit a pin,
a pose, or an opinion, recompose, push again — content-addressed dedup
keeps re-pushes cheap.

## Requirements

Composition is a real MuJoCo build (name-aware attach renaming, URDF
import, compile validation), not file manipulation. The CLI delegates
materialization to the Python engine in **dreamlake-py**:

```bash
pip install "dreamlake[compose]"   # the engine + mujoco (optional extra, lazily imported)
```

`dreamlake env compose` requires it on the composing machine and says so
clearly when it is absent. Push / pull / list need no Python. Registry
layers are resolved through the immutable, hash-verified cache at
`~/.dreamlake/cache/envs/<ns>/<name>/<version>/`.

The engine needs **MuJoCo ≥ 3.8** (validated on 3.8.1 and 3.14.0): it
drives the modern `MjSpec` class API, which MuJoCo 3.2's early spec
bindings do not provide. dreamlake 0.23.0 still *declares*
`mujoco>=3.2.0`, so a 3.2 environment installs cleanly and then fails at
the first layer with a `from_file(): incompatible function arguments`
error — upgrade mujoco. From **dreamlake 0.23.1** the package declares
the real `mujoco>=3.8` floor and the engine refuses an older MuJoCo up
front with an explicit version error. (The standalone scene-inspection
tools are separate and do run on 3.2.)

## The file: `dreamlake.layers.json`

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "name": "kitchen-g1",
  "layers": [
    { "tag": "Merge",  "src": "you/kitchen@3" },

    { "tag": "Attach", "src": "you/sharpa-right", "key": "right",
      "at": "world", "pos": [0.45, -0.12, 0.30], "quat": [1, 0, 0, 0],
      "joint": "free-anchored" },

    { "tag": "Update", "key": "obj/mug", "pos": [0.30, 0.10, 0.02] },
    { "tag": "Update", "key": "light:key", "diffuse": [0.3, 0.3, 0.4] },
    { "tag": "Update", "key": "option", "impratio": 10 },
    { "tag": "Remove", "key": "body:fixture/plant" },

    { "tag": "Patch",  "src": "./patches/night.xml" }
  ]
}
```

### Top-level fields

| field | type | required | meaning |
| --- | --- | --- | --- |
| `schema` | string | yes | `"dreamlake.env-layers/v3"`, verbatim |
| `layers` | array | yes | ordered ops, applied first → last |
| `substrate` | string | no — default `"mujoco"` | the format the stack composes in. `"mujoco"` is the only substrate today; a layer whose envType differs is admitted only if an importer into the substrate exists (`urdf` — see below), otherwise compose rejects it |
| `entry` | string | no — default `"scene.xml"` | entry filename of the materialized artifact |
| `name` | string | no | MJCF model name of the output |

The minimal stack is two keys: `schema` and `layers`.

### `src` — one string, two shapes

`Merge`, `Attach` and `Patch` take a source. The rule is ESM-style:

| shape | meaning |
| --- | --- |
| `"ns/name"` or `"ns/name@3"` | a pushed env version. An unversioned ref **floats** — resolved to the latest version at compose time; the copy of the stack embedded in the artifact is always pinned `@v` |
| `"./dir"`, `"../dir"`, `"/abs"` | a local path — a directory in the standard env shape, or a single MJCF file (a sparse patch, say), distinguished automatically. Dev-only: composing and previewing are unrestricted, pushing is gated — see [push discipline](#push-discipline) |

A local path **must** start with `./`, `../` or `/` — a bare string is
always a registry ref, so `you/kitchen` (registry) and `./you/kitchen`
(a local directory that happens to have that name) never collide.

### Element addresses — one syntax everywhere

`Attach.at`, `Update.key` and `Remove.key` share one address syntax:

- `kind:name` — explicit: `body:fixture/plant`, `geom:floor`,
  `site:right:palm-mount` (everything after the first colon is the name,
  so attach-manufactured names like `right:palm` address naturally);
- bare `name` — allowed when the name is unambiguous across kinds;
  a name shared by, say, a body and a geom is a compose-time error that
  lists the candidates and asks you to qualify;
- `option` — the singleton (no name); `visual:<sub>` — a visual
  sub-block (`visual:headlight`).

### `tag: "Merge"`

```json
{ "tag": "Merge", "src": "you/kitchen@3" }
```

Section-wise union of the env's MJCF into the stack: worldbody children,
assets, `<default>` classes, tendons / actuators / sensors / contacts. A
name collision between merged layers is an **error**, never silent
last-wins — changing existing elements is exclusively the opinion ops'
job. Exception by design: `<option>` / `<visual>` / `<compiler>`-class
settings merge **field-wise, later layer wins per field** — which is what
makes an option-only "physics profile" layer work with no extra
machinery. Each layer is parsed in its own compiler context (angle units,
`meshdir`, autolimits) and resolved before union, so per-layer authoring
conventions never leak.

### `tag: "Attach"`

Grafts the env's subtree at a target, under the identity root `key`:

| field | type | required | meaning |
| --- | --- | --- | --- |
| `src` | string | yes | the env (or local path) to graft |
| `key` | string | yes | the identity root — prepended (with `:`) to **every** name in the layer and every internal name reference: `"right"` makes `palm` → `right:palm`. No colon, no whitespace — the separator is the composer's. Duplicate keys across the stack are an error |
| `at` | string | no — default `"world"` | mount target: `"world"`, `"body:<name>"`, or `"site:<name>"`. A site's own pose wins over `pos`/`quat` (the mount-point hook); the target may come from any lower layer |
| `pos` | `[x, y, z]` | no — default `[0, 0, 0]` | mount position |
| `quat` | `[w, x, y, z]` | no — default `[1, 0, 0, 0]` | mount orientation (MuJoCo order) |
| `joint` | string | yes | `"rigid"` — welded by construction (arms, sensor rigs, fixtures). `"free"` — freejoint, subject to gravity (props). `"free-anchored"` — freejoint plus a mocap-anchor weld: hangs posed, draggable in the viewer (hands, grippers) |

Placing one source several times is several `Attach` entries — each its
own identity root, so an `Update` above can recolor `mug2:handle` and
leave `mug1:*` alone.

For a **urdf** source whose root already declares a freejoint (common in
`.mjcf.urdf` files with MuJoCo extension tags), the composer reconciles
the `joint` mode instead of double-adding one; `free-anchored` welds to
whichever freejoint results.

### `tag: "Update"` — the meta component

```json
{ "tag": "Update", "key": "obj/mug", "pos": [0.30, 0.10, 0.02] }
```

`key` addresses one element; **every other prop is an MJCF attribute
opinion** — the attributes present are the opinions, nothing else is
touched. JSON values serialize to MuJoCo's XML conventions:

| JSON | MJCF |
| --- | --- |
| `10`, `2.5` | `"10"`, `"2.5"` |
| `[0.3, 0.1, 0.02]` | `"0.3 0.1 0.02"` |
| `true` / `false` | `"true"` / `"false"` |
| `"elliptic"` | verbatim (enums coerce through MuJoCo's own parser) |

Matching is **strict**: an opinion naming an element the stack doesn't
have is a compose-time error (with the layer index), not a no-op — it
catches typos and stale stacks immediately. `name` / `class` /
`childclass` are identity plumbing, not opinions — an `Update` cannot set
them. Singletons work the same way: `{"key": "option", "impratio": 10}`,
`{"key": "visual:headlight", "ambient": [0.1, 0.2, 0.3]}`.

**Orientations.** In dreamlake 0.23.0 an `Update`/`Patch` opinion
can re-orient an element through `quat` only — an `xyaxes` opinion fails
with *"has no attribute settable through MjSpec"* (authoring `xyaxes` in
a layer's own MJCF is unaffected; that resolves inside MuJoCo). <em>From
0.23.1:</em> orientation opinions also accept MuJoCo's
alternative specifiers — `xyaxes` (6 numbers), `euler` (3), `axisangle`
(4), `zaxis` (3) — on elements that support them (body, geom, site,
camera), resolved by MuJoCo's own compiler exactly as raw-MJCF authoring
would be. State **exactly one** orientation prop per op (two, e.g. `quat`
+ `xyaxes`, is a compose error); a later op's `quat` replaces an earlier
alternate, and vice versa. Wrong-length or non-finite vectors are
compose errors with the expected shape.

**Boolean flags.** MJCF boolean attributes (`active`, `castshadow`,
body `mocap`) take `true`/`false`. On MuJoCo 3.14 this works in
0.23.0; on MuJoCo 3.8, where MjSpec stores these flags as ints,
0.23.0 fails to coerce `false` (`invalid literal for int()`). <em>Fixed
in 0.23.1:</em> the flag names above coerce `true`/`false` on
both representations; genuinely numeric fields (`contype`, bitmasks,
enums) still reject `true`/`false` rather than guessing.

### `tag: "Remove"`

```json
{ "tag": "Remove", "key": "body:fixture/plant" }
```

Removes the addressed element **and its subtree** from the stack below.
The layer beneath is untouched, so deletion is non-destructive at the
*stack* level: drop the line and the element is back. Destructive intent
stays visible in the stack file. Removable kinds: body, geom, joint,
site, camera, light, material, mesh, texture, actuator, sensor, tendon,
equality, key (keyframe — `key:home`).

### `tag: "Patch"`

```json
{ "tag": "Patch", "src": "./patches/night.xml" }
```

The same opinion semantics as `Update`, sourced from **sparse MJCF** — a
file inside the stack's own directory, or a pushed env (a versioned,
reviewable opinion layer). Elements are matched by (kind, name), the
attributes present are the opinions, matching is strict. Use it when the
opinion set is big enough to be its own artifact; a patch of a few
one-liners reads better as inline `Update`s.

## Semantics rules

- **Later wins, linearly.** The stack is applied first → last; there is no
  strength lattice, no priorities — position in the list is the priority.
- **Identity is the MJCF name.** The only stable cross-layer identity.
  Layers that expect to be overridden should name what they expose
  (`obj/*`, `fixture/*` are the house convention). `Attach` manufactures
  new identities under its `key`; **after an attach, ops above target the
  prefixed names** (`right:palm`, `mug2:handle`).
- **Mutation is explicit.** `Merge` never changes an existing element
  (collision = error); changing things is exclusively `Update`/`Patch`'s
  job, deletion `Remove`'s. Every stack reads as: what was added, where,
  and what was changed.
- **Keyframes**: stacks containing any `Attach` strip `<keyframe>`
  entries (attach changes the model's dof count, invalidating them).
- **Intent vs pinned.** The authored file may float (`you/kitchen`, no
  version). Materialization resolves every ref; the stack copy embedded
  in the artifact is always fully pinned and carries
  `"builder": {"engine": "dreamlake-py/<v>", "mujoco": "<v>"}` — the
  importer/serializer is MuJoCo itself, so the engine version is part of
  determinism. Local srcs embed with `"unpinned": true`.
- **Nested stacks.** A source env that is itself layered is consumed via
  its **materialized artifact**, never by re-walking its stack — it
  behaves as one ordinary layer. Pins compose transitively (recorded for
  provenance); the builder caps nesting depth and rejects cycles.
- **One substrate per stack.** A layer whose envType differs from
  `substrate` composes only through an importer. Today's matrix:
  `urdf` → `mujoco` is supported natively, **Attach-only** (URDF cannot
  express a world — no multi-robot, no lights, no options — so it can
  never be a base, Merge, or Patch layer). Anything else (`isaaclab`,
  arbitrary types) is not stackable.

## Push discipline

Composing and previewing locally is unrestricted. **Pushing** a directory
whose `dreamlake.layers.json` contains unpinned local srcs is refused
with guidance, because the composed env would no longer be re-openable
from the registry:

| flag | effect |
| --- | --- |
| `--push-layers` | push the local layers first (as their own envs), then the composed env — provenance stays fully resolvable |
| `--allow-local` | push anyway; the provenance is permanently marked non-resolvable |

## Examples

### 1. Scene + embodiment (and how to swap it)

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "name": "kitchen-sharpa",
  "layers": [
    { "tag": "Merge",  "src": "you/kitchen@3" },
    { "tag": "Attach", "src": "you/sharpa-right@1", "key": "right",
      "at": "world", "pos": [0.45, -0.12, 0.30], "joint": "free-anchored" }
  ]
}
```

Swapping the embodiment is editing one line — change the `Attach`'s `src`
to `you/claw@2`, recompose, push: a new version, same env page, one-line
diff in the stack.

### 2. Inline opinions: Update + Remove

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "layers": [
    { "tag": "Merge",  "src": "you/kitchen@3" },
    { "tag": "Update", "key": "obj/mug", "pos": [0.30, 0.10, 0.02] },
    { "tag": "Update", "key": "light:key", "diffuse": [0.3, 0.3, 0.4] },
    { "tag": "Update", "key": "option", "impratio": 10 },
    { "tag": "Remove", "key": "body:fixture/plant" }
  ]
}
```

Move a mug (only `pos` — every other attribute of the body is
untouched), dim one light, set one `option` field, delete the plant —
four one-line ops, no patch file. Drop any line and that change reverts.

### 3. The same opinions as a Patch file

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "layers": [
    { "tag": "Merge", "src": "you/kitchen@3" },
    { "tag": "Patch", "src": "./patches/night.xml" },
    { "tag": "Remove", "key": "body:fixture/plant" }
  ]
}
```

```xml file="patches/night.xml"
<mujoco model="night">
  <worldbody>
    <body name="obj/mug" pos="0.30 0.10 0.02"/>
    <light name="key" diffuse="0.3 0.3 0.4"/>
  </worldbody>
  <option impratio="10"/>
</mujoco>
```

Same semantics as example 2 — sparse MJCF, attributes present are the
opinions. Worth the separate file when the opinion set is big; deletion
stays in the stack (`Remove`), so the destructive part is visible where
the ordering is.

### 4. Repeated Attach — two mugs

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "layers": [
    { "tag": "Merge",  "src": "you/kitchen@3" },
    { "tag": "Attach", "src": "you/mug@2", "key": "mug1",
      "at": "world", "pos": [0.30, 0.10, 0.05], "joint": "free" },
    { "tag": "Attach", "src": "you/mug@2", "key": "mug2",
      "at": "world", "pos": [0.42, -0.08, 0.05], "joint": "free" },
    { "tag": "Update", "key": "mug2:handle", "rgba": [1, 0, 0, 1] }
  ]
}
```

Each `Attach` is its own identity root — the `Update` recolors
`mug2:handle` and leaves `mug1:*` alone.

### 5. URDF robot layer

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "name": "berry-g1",
  "layers": [
    { "tag": "Merge",  "src": "you/scene-berry@1" },
    { "tag": "Attach", "src": "you/g1@1", "key": "g1",
      "at": "world", "pos": [0, 0, 0.8], "joint": "free" }
  ]
}
```

`you/g1` is a `urdf` env; the composer imports it natively into the
`mujoco` substrate. URDF sources are **Attach-only**, and the composer
reconciles a root freejoint the URDF may already declare (no double-add).

> **Warning:** URDF `<transmission>` has no MuJoCo mapping — a urdf layer imports
>   with **zero actuators** (`nu = 0`) and goes limp under gravity in a
>   physics stack. The compose report carries an "unactuated import"
>   warning. The stack model is the remedy: add `Update` ops (or a `Patch`
>   layer) contributing damping / actuators (versioned like everything
>   else), or treat the layer as visualization-grade and say so in the env
>   description.

### 6. Nested stack — compose atop a composed env

```json file="dreamlake.layers.json"
{
  "schema": "dreamlake.env-layers/v3",
  "layers": [
    { "tag": "Merge",  "src": "you/kitchen-sharpa@2" },
    { "tag": "Attach", "src": "you/wrist-cam-rig@1", "key": "cam",
      "at": "site:right:palm-mount", "joint": "rigid" },
    { "tag": "Patch",  "src": "you/kitchen-nightshift@1" }
  ]
}
```

`you/kitchen-sharpa@2` is itself a composed env (example 1, pushed) — it
enters this stack as **one layer**, consumed via its materialized
artifact, never unpacked. The camera rig mounts on a site the inner
composition created (`right:palm-mount` — note the key from example 1's
attach), and the last layer is a Patch **env**: a pushed, versioned
opinion layer (compare example 3's in-directory file — same semantics,
different lifecycle).

## Migrating a v2 stack

The v2 schema (`{source, compose}` objects) is superseded; the engine and
CLI read v3 only, and a v2 file gets an error carrying this table:

| v2 | v3 |
| --- | --- |
| `{"source": {...}, "compose": {"mode": "merge"}}` | `{"tag": "Merge", "src": ...}` |
| `mode: "attach"` + `"prefix": "right:"` | `{"tag": "Attach", "key": "right", ...}` — no trailing colon, props flat |
| `"instances": [...]` | one `Attach` entry per instance |
| `mode: "override"` with an env/file source | `{"tag": "Patch", "src": ...}` — or inline `Update`s for small sets |
| `compose.delete: [{"elem", "name"}]` | `{"tag": "Remove", "key": "kind:name"}` |
| `{"env": ...}` / `{"path": ...}` / `{"file": ...}` | one `src` string; local paths start with `./` |

## Common errors

| error | when | remedy |
| --- | --- | --- |
| merge name collision | two Merge layers define an element with the same name — merge never silently last-wins | rename the element in one layer; if the upper layer is *meant to change* the element, that should be an `Update`/`Patch`, not a `Merge` |
| strict-match miss | an `Update`, `Remove`, or `Patch` opinion names an element the stack below doesn't have; the error reports the layer index | fix the typo — and after an `Attach`, target the **keyed** name (`right:palm`, `mug2:handle`), not the source env's original name |
| ambiguous address | a bare `key` matches more than one kind (a body and a geom named alike) | qualify it: `body:thing` |
| env src not resolved ("resolve refs first") | the Python engine was invoked directly on a stack that still contains registry srcs — the engine only takes resolved local paths | run through `dreamlake env compose`, which resolves refs into `~/.dreamlake/cache/envs/…` first; for private layers, check you are logged in to the right remote |
| missing Python engine | `dreamlake env compose` delegates materialization to dreamlake-py, and it (or its mujoco extra) is not installed | `pip install "dreamlake[compose]"` on the composing machine. Machines that only push / pull / list don't need it |
| `from_file(): incompatible function arguments` at layer 0 | MuJoCo 3.2 is installed — dreamlake 0.23.0 declares `>=3.2.0` but the engine needs the modern MjSpec API (0.23.1 declares `>=3.8` and guards this up front) | upgrade: `pip install -U "mujoco>=3.8"` (validated 3.8.1 / 3.14.0) |
| Update `xyaxes`: "has no attribute … settable through MjSpec" | dreamlake 0.23.0 supports orientation opinions via `quat` only | upgrade to dreamlake ≥ 0.23.1, which accepts the alternate orientation specifiers — or state a `quat` opinion (compute it from your look-at axes), or put the `xyaxes` in the layer's own MJCF |

## Under the hood: the engine boundary

The CLI owns stack parsing, ref resolution, the cache, and push
discipline; materialization runs in the dreamlake-py engine:

```bash
python3 -m dreamlake.envlayer compose <resolved-stack.json> --out <dir>
```

The resolved stack is the same schema with every registry `src` replaced
by the cache's absolute path plus `"pin": "ns/name@N"`; registry srcs are
rejected. `Update`/`Remove` ops pass through verbatim. On success the
engine writes `<dir>/{entry, meshes/, dreamlake.layers.json}` and prints,
as its last stdout line,
`{"ok": true, "entry": …, "stats": {"nbody": …, "njnt": …, "nu": …}, "warnings": […]}`;
on failure it exits 1 with `{"ok": false, "error": "…", "layer": <i>}`.
The engine is network-free and deterministic: stack + pins fully
determine the artifact.

## Next steps

    Push, version, drive, and pull plain envs — layers build on all of it.

    Every env command and flag.

---

Source: https://docs.dreamlake.ai/libraries/reference

# Libraries Reference

  The machine contract behind [Libraries](/libraries.md). The guide explains the
  feature to a person; this page specifies it for a program — exact request
  and response shapes, the wire manifest, and how the calls compose into
  survey → search → inspect → verify → pull.

Base URL: `https://api.dreamlake.ai` in production, `http://localhost:3001`
in local dev.

**Auth model.** The read surface takes an *optional* bearer token: a request
resolves a library when the caller is a namespace member, **or** the library
is `public`, **or** the request carries a valid `?share=<token>`. A library
that is hidden and one that does not exist both answer **404** — private
names are not probeable. The write surface (`upload-authorizations`,
`register`, metadata patch, restore, delete, purge) requires a member JWT.
`GET /library-search` deliberately does **not** honor share tokens.

**Conventions.** Sizes are bytes (integers). Hashes are 64-char lowercase hex
sha256. Times are ISO-8601 UTC. Presigned URLs are short-lived; where a route
accepts `ttlSeconds`, the response echoes the value actually granted.

## The read path

An agent's loop over libraries is four cheap metadata calls and one byte
transfer, in this order.

### 1. Survey — which libraries exist, what is in each

```bash
curl "$API/libraries?limit=100"                      # everything you can see
curl "$API/namespaces/acme/libraries"                # one namespace
```

`GET /libraries` returns `{ libraries: [...] }`, newest-updated first,
`limit` 1–500 (default 100). Each row is the library summary plus its
`namespace`:

| Field | Meaning |
|---|---|
| `namespace`, `name`, `type` | Identity. `type` defaults `3d`. |
| `title`, `description`, `provider`, `license`, `tags[]` | Catalog card metadata, from the manifest's `library` block. |
| `revision` | Register counter — a cache-buster, not user-facing versioning. |
| `assetCount`, `fileCount`, `totalBytes` | Aggregates computed at register. `fileCount` counts distinct paths. |
| `categories[]`, `kinds[]`, `licenses[]` | Distinct values present (filter chips) — values only, no counts. |
| `visibility` | `private` \| `public`. |
| `semantic` | Would a search here run vector fusion *today*: `true`, `false` (no sidecar, or one the active encoder rejects), `null` (registered before the flag existed). Evaluated at read time against the active encoder, so it tracks an encoder switch without a re-register. |
| `vectorsDim` | Embedding dimension mirrored from the sidecar at register; `null` = no sidecar. Non-null does **not** imply `semantic` — the sidecar may be in another embedding space. Present on list rows as well as detail, so sizing a query vector costs no extra call. |
| `coverThumbUrl` | Presigned representative thumbnail, 900 s TTL, `null` when none. |
| `createdAt`, `updatedAt` | Timestamps. |

`GET /namespaces/:slug/libraries` returns `{ viewerIsMember, libraries }`
(members also see private rows; `?deleted=true` lists the Trash). It is not
paginated. `GET /namespaces/:slug/libraries/:name` returns the same row plus
`homepage`, `upstreamRepo`, `upstreamCommit`, `indexRevision` (reserved;
always `null` today), `viewerCanManage`, and (for managers) `shareToken`.

### 2. Search — which assets match

```bash
# across chosen libraries
curl "$API/library-search?q=blue+ceramic+mug&libraries=acme/gso,acme/menagerie&kind=mjcf"

# inside one library
curl "$API/namespaces/acme/libraries/gso/search?q=mug&category=household&limit=20"
```

Query parameters (both routes): `q` (≤ 500 chars; empty = browse mode —
filters still apply, results ordered by `id`, `score: 0`), `category`,
`kind`, `license`, `tag` (exact-match filters; `license` matches the
*effective* license, asset value falling back to the library default),
`limit` 1–200 (default 50), `offset`. `/library-search` additionally
requires `libraries` — comma-separated `ns/name`, at most 50.

Response envelope:

```jsonc
{
  "semantic": true,       // vector fusion ran (false = keyword-only fallback)
  "total": 3,             // pre-pagination count
  "skipped": [            // /library-search only: targets that resolved to
    { "library": "acme/private-lib", "reason": "not_found" }
  ],                      // nothing — private and missing are indistinguishable
  "hits": [ ... ]
}
```

Each hit carries exactly these fields (`/library-search` prepends
`namespace` and `library`):

| Field | Meaning |
|---|---|
| `assetId` | Unique within the library; what `pull --asset` takes. |
| `title`, `description`, `category`, `tags[]` | Author metadata from the manifest. |
| `kind`, `format` | Viewer dispatch tokens (`mjcf`, `urdf`, `mesh`, `splat`, …). |
| `license` | **Effective** license — the asset's own, else the library default. |
| `entry` | The file a viewer opens, when declared. |
| `thumbnailUrl` | Presigned GET, 900 s TTL; `null` when the asset has no thumbnail. |
| `score` | Keyword relevance, or the fused score when `semantic: true`. |
| `files` | `{count, bytes}` over the asset's own entries — the pull cost. |
| `digest` | `sha256:<hex>` over the asset's sorted `path\nsha256\n` lines. Byte-identical to the CLI's digest, so equal digests mean a pull transfers nothing. |

Keyword scoring matches query tokens against `title` (×3), `tags` (×2),
`id` (×2), `description` (×1) — exact token = full weight, prefix = half.
Tokenization is ASCII-only, so a non-Latin query yields no keyword tokens
and ranks by vector alone when the semantic path is available.

Semantic ranking uses SigLIP2 image vectors of the thumbnails (text vectors
substitute only for a sidecar that has no image rows at all), min-max
normalized and fused with the keyword score — weights 1.0 vector, 0.3 text,
over the top 100 vector candidates. This is weighted score fusion, not RRF.
Vectors are used only when the sidecar's `model` matches the server's active
query encoder. Any failure on the semantic path — no embeddings pushed,
model mismatch, encoder unavailable — degrades to keyword-only with
`semantic: false`; search never 5xxes for it.
Cross-library results merge as `score desc → namespace → library → assetId`,
then paginate.

### 3. Inspect — everything about one asset

```bash
curl "$API/namespaces/acme/libraries/gso/assets/Cole_Hardware_Mug_Classic_Blue?ttlSeconds=3600"
```

Returns the asset's full manifest entry — `id, title, description, category,
tags, kind, format, license, attribution, upstream, entry, entryPoints,
meta` — plus `ttlSeconds`, `thumbnailUrl`, and `files:
[{path, size, sha256, url}]` with a presigned GET **per file**. Two caveats:

- This is the preview payload: it presigns every file of the asset. For
  metadata-only reads over many assets, read the manifest instead (next
  section) — one call, no presigning.
- `license` here is the asset's **raw** value (may be `null`); search hits
  return the effective license.

Unknown asset → 404 `{ "error": "asset_not_found" }`.

### 4. Verify — is my local copy current?

The manifest is the freshness primitive. It lists every file's `path`,
`size`, and `sha256`, and it is served from a revision-keyed cache — one GET
answers any diff question without touching payload bytes:

```bash
curl "$API/namespaces/acme/libraries/gso/manifest" \
  | jq -r '.assets[] | select(.id == "Cole_Hardware_Mug_Classic_Blue")
           | .files[] | "\(.sha256)  \(.path)"' > want.txt
(cd ./scene/assets && sha256sum --check --quiet want.txt) \
  && echo "up to date — skip the pull"
```

`revision` on the catalog row is the cache key: re-read the manifest only
when it changed. From the CLI this whole check is one command —
`dreamlake library stat acme/gso --asset <id> -o ./scene/assets` — exit 0
means the pull can be skipped. (`push --dry-run` remains the
authoring-direction diff: local tree as truth, member token required.)

### 5. Pull — materialize exactly these files

```bash
curl -X POST "$API/namespaces/acme/libraries/gso/files-presign" \
  -H 'content-type: application/json' \
  -d '{"paths": ["Cole_Hardware_Mug_Classic_Blue/model.xml"], "ttlSeconds": 3600}'
```

Body: `paths` (1–1,000 manifest paths per batch), optional `ttlSeconds`.
Response: `{ ttlSeconds, files: [{path, size, sha256, url}] }` — GET each
`url`, verify each `sha256`. Paths must come from the manifest; anything
else answers 400 `{ "error": "unknown_path", "path": "…" }` (platform
artifacts under `.dreamlake/` are existence-probed, so a missing sidecar
also answers `unknown_path` rather than a URL that would 404).

## The write path

Three calls, member JWT required. The CLI (`dreamlake library push`) is the
reference client.

1. **`POST …/libraries/:name/upload-authorizations`** — body
   `{ files: [{relativePath, size, mediaType?}] }` (≤ 1,000 files / 10 GiB
   per batch, loop for more). Response: per-file `transfer` — either
   `{kind: "single-put", put: {url, headers}}` or
   `{kind: "s3-multipart", uploadId, partSize, parts[], complete, abort}`.
   Bytes go straight to storage, never through the API server.
2. **`POST …/libraries/:name/register`** — body
   `{ expectedRevision?, visibility?, share? }`. Validates the uploaded
   manifest, bumps `revision` (compare-and-swap: a stale `expectedRevision`
   answers 409 `{ "error": "revision_conflict", "revision": <current> }` —
   re-diff and retry). Returns the library detail (201 on create).
3. **Reconcile** (server-side, automatic) — after register, any stored file
   outside the manifest closure is deleted. Clients never hold delete
   permission; storage always equals exactly what the manifest declares.

Metadata is manifest-derived by design: the only patchable fields on
`POST …/libraries/:name` are `visibility` and `share`. Soft delete
(`DELETE …/:name`) hides and is restorable (`POST …/:name/restore`); purge
(`DELETE …/:name/purge`) permanently removes storage and catalog.

## The wire manifest — `dreamlake.assets/v1`

Stored at `files/.dreamlake/manifest.json`, served verbatim by
`GET …/libraries/:name/manifest`. Validation rejects the **whole document**
on any unknown key at any level — a client can trust that every field it
writes was seen and acted on.

```jsonc
{
  "schema": "dreamlake.assets/v1",
  "library": {
    "name": "gso", "type": "3d",
    "title": "Google Scanned Objects",
    "description": "…", "provider": "…", "homepage": "https://…",
    "license": "CC-BY-4.0", "tags": ["household"],
    "upstream": { "repo": "https://…", "commit": "abc123" }
  },
  "assets": [
    {
      "id": "Cole_Hardware_Mug_Classic_Blue",
      "title": "Cole Hardware Mug, Classic Blue",
      "description": "…", "category": "household", "tags": ["mug"],
      "kind": "mjcf", "license": null, "attribution": null,
      "entry": "Cole_Hardware_Mug_Classic_Blue/model.xml",
      "entryPoints": { "scene": { "kind": "scene", "file": "…/scene.xml" } },
      "files": [
        { "path": "Cole_Hardware_Mug_Classic_Blue/model.xml",
          "size": 4231, "sha256": "9f…" }
      ],
      "thumbnail": ".dreamlake/thumbnails/Cole_Hardware_Mug_Classic_Blue.webp",
      "meta": { "triCount": 12000 }
    }
  ],
  "generated": [".dreamlake/thumbnails/Cole_Hardware_Mug_Classic_Blue.webp",
                ".dreamlake/vectors.json", ".dreamlake/vectors.f32"]
}
```

### Field constraints

**Root** — exactly `schema | library | assets | generated`.

**`library`** — `name` ≤ 64 · `type` (vocab, default `3d`) · `title` ≤ 200 ·
`description` ≤ 10,000 · `provider` ≤ 200 · `homepage` ≤ 500 ·
`license` ≤ 120 · `tags` ≤ 32 × 64 chars · `upstream { repo ≤ 500,
commit ≤ 128 }`. All optional.

**`assets[]`** — per entry:

| Field | Constraint |
|---|---|
| `id` | required; `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$`; unique across the library |
| `title` / `description` | ≤ 200 / ≤ 2,000 |
| `category`, `kind`, `format` | vocab tokens: `^[a-z0-9][a-z0-9._-]{0,31}$`; `kind` defaults `file`. `format` sub-types the viewer — the CLI emits `sog` / `lod` for detected splat containers |
| `tags[]` | ≤ 32, each ≤ 64 |
| `license` / `attribution` | ≤ 120 / ≤ 1,000; effective license = asset ?? library |
| `upstream` | `{ id?, url? }` |
| `entry` | canonical path; must be one of the asset's own `files[]` |
| `entryPoints` | ≤ 32 named `{ kind (default "scene"), file }`; `file` must be in own `files[]` |
| `files[]` | **required, non-empty**; each `{path, size: int ≥ 0, sha256: 64 hex}`; no duplicate paths within an asset; assets may share files, but one path must carry one hash library-wide |
| `thumbnail` | one of the asset's own `files[]` **or** a `generated[]` path |
| `meta` | free-form object, ≤ 8,192 bytes as JSON |

**`generated[]`** — platform artifacts. Every entry must live under
`.dreamlake/` and must not be the manifest itself. The reserved area is a
two-way invariant: user file paths may never enter `.dreamlake/`, generated
paths may never leave it.

`generated[]` is also the *declaration*, not just an inventory: the manifest
is the single gate for platform artifacts, so an artifact you uploaded but
did not list does not exist — the post-register reconcile deletes it, and
until then nothing reads it. For the embeddings sidecar that means both
`.dreamlake/vectors.json` and `.dreamlake/vectors.f32` must appear here, or
register answers `semantic: false` and search stays keyword-only. Half a
pair counts as neither.

**Limits** — manifest ≤ 100 MiB · assets ≤ 50,000 · file entries ≤ 1,000,000
(total across all assets) · generated ≤ 60,000.

**Validation error codes** — `manifest_too_large`, `manifest_invalid_json`,
`manifest_bad_schema`, `manifest_invalid`, `manifest_invalid_path`,
`manifest_duplicate_id`, `manifest_too_many_assets`,
`manifest_too_many_files`, `manifest_too_many_generated`,
`manifest_file_conflict`.

Libraries pushed under the legacy layout (`assets.json` at the files root,
with `assets.vectors.{json,f32}` siblings) are still read as a fallback; the
first push from the current CLI migrates them.

### Embeddings sidecar — `dreamlake.assets.vectors/v1`

`push --embed` uploads `.dreamlake/vectors.json` + `.dreamlake/vectors.f32`
**and lists both in `generated[]`** (see above — undeclared is
indistinguishable from absent): `{ schema, model, dim, items: [{id, image,
text}] }` where `image`/`text` are row indices into the little-endian f32
matrix, L2-normalized, 768-d.

`model` is the gate. It is an `open_clip/<model>/<pretrained>` string, and
the server uses the sidecar only when it equals the active query encoder's
id. There is exactly one query encoder — `open_clip/ViT-B-16-SigLIP2/webli`
— so that is the only value that fuses. A sidecar with no `model` field is
treated as the historical `open_clip/ViT-L-14-quickgelu/openai`; that tower
no longer exists server-side, so such a library is keyword-only. Both models
are 768-d, so the dimension check cannot catch a mismatch; without the model
gate a foreign sidecar would return confident nonsense. Libraries without a
usable sidecar are keyword-only — the search envelope says so via
`semantic: false`.

`dreamlake` ≥ 0.25.0 writes the SigLIP2 id by default, and
`dreamlake library push --embed --model <name>` selects the encoder
explicitly (`siglip2` · `clip` · a raw `open_clip` name).

## CLI equivalents

| Task | Command | Machine output |
|---|---|---|
| Survey | `dreamlake library list --all` | `--json` — the HTTP body, verbatim |
| Search | `dreamlake library search "mug" --library acme/gso [--license …] [--offset …]` | `--json` — the raw search response; scope notes go to stderr |
| Summarize / inspect | `dreamlake library info acme/gso [--asset <id>]` | `--json` — client-computed library summary, or one asset's card incl. its closure digest |
| Verify freshness | `dreamlake library stat acme/gso [--asset <id>] -o <dir>` | `--json`; exit 0 = up-to-date, 1 = stale/absent |
| Pull | `dreamlake library pull acme/gso [--asset <id>] -o <dir>` — incremental: byte-identical local files are skipped | `--json` |
| Remote edit | `dreamlake library add acme/gso ./asset-dir [--replace]` · `dreamlake library rm acme/gso <id…>` | `--json` |
| Authoring diff | `dreamlake library push <dir> --dry-run` (local tree as truth; member token) | `--json` |

The pull verifies every file against its manifest sha256 and materializes
original relative paths; `--all` adds platform artifacts. See the
[guide](/libraries.md#pull-it-back) for authoring-side commands.

## Next steps

- [Libraries](/libraries.md) — the human guide: conventions, `dreamlake.yml`,
  push workflow.
- [API Reference § Libraries](/api.md#libraries) — the endpoint table in the
  platform-wide API index.
- [Scene Generation](/scene-generation.md) — the main consumer of this
  contract.

---

Source: https://docs.dreamlake.ai/lakeshore

# Lakeshore

  Lakeshore runs your Python functions on machines that are not your laptop. You
  decorate a function with `@udf` and call it; Lakeshore queues the invocation,
  ships it to a worker, runs it, and hands the result back. You write Python — it
  handles the scheduling, the transport, and the worker side.

You reach for Lakeshore when the work does not fit on the machine in front of
you: a GPU job, a long sweep, or a fan-out of identical calls you want to run
all at once. Nothing about the function has to change to move it off your
laptop — the decorator is the only difference between a local call and a remote
one.

## The three layers

Lakeshore ships as three pieces, each deployed and upgraded on its own:

| Layer         | What it is                                       | What it does                                                    |
| ------------- | ------------------------------------------------ | --------------------------------------------------------------- |
| Client        | Python SDK (`dreamlake-lakeshore`) and the `lakeshore` CLI (`@dreamlake/lakeshore`) | Where you write `@udf`, and where an operator manages queues, providers, and daemons |
| Control plane | A single service that owns the authoritative state | Holds queues, workers, providers, and pending invocations; dispatches work |
| Runtime       | The `nymph` daemon on each compute host          | Long-polls the control plane and executes invocations next to your data |

The daemon connects outbound only, so a worker can sit behind a firewall, in a
cluster, or on a machine you already own, and still take work. What it does
between starting and taking that work — coming up, running its setup, declaring
itself ready, and saying so on the way out — is the [worker
lifecycle](/lakeshore/lifecycle.md).

## Start here

    Run a Python function through a local queue, then point the SDK at a service.

    Host the control-plane server and create its first namespace and client login.

    Add an existing service and inspect its queues, workers, and jobs.

    Enroll an SSH-accessible machine, prepare credentials, and test tracked runs.

    The first UDF type — sync, async, generator and async-generator bodies,
    scopes, key-based returns, and the registry payload each one produces.

    The whole stack on one laptop — no cloud account, no release download, and a
    daemon you built yourself.

    A queue is one model carrying both a scheduling surface and a launch policy,
    because queue depth is the autoscaling signal.

    The provider types compute can be launched through, and which of them are
    finished.

## Deep reference

This tab is orientation. The canonical, complete documentation for the SDK, the
CLI, the daemon, and the control plane lives on its own site.

    The full SDK reference — `@udf`, queues, invocations, dispatch, and payloads.

    The `lakeshore` command — auth, queues and jobs, providers, daemons, and the
    `tui` dashboard.

    How a call becomes a queued invocation and lands on a remote worker.

    The worker daemon — lifecycle, wire protocol, identity and key rotation,
    telemetry.

## How it connects to DreamLake

| Piece         | Where                        | Role                                                |
| ------------- | ---------------------------- | --------------------------------------------------- |
| Control plane | `api.lakeshore.dreamlake.ai` | Queues invocations, tracks workers, brokers results |
| nymph daemon  | Compute hosts, outbound-only | Executes invocations next to your data              |
| Python SDK    | `dreamlake-lakeshore` (PyPI) | `@udf` decorator, queues, invocation handles        |
| CLI           | `@dreamlake/lakeshore` (npm) | `lakeshore tui`, jobs, daemons, queue management    |

---

Source: https://docs.dreamlake.ai/lakeshore/quickstart

# Quick start

  Submit a Python function, run a worker, and read the result. Start with a local
  queue so your first run needs only Python; then connect the SDK to a service.

Choose the guide for what you want to do:

- **Run a function:** continue below.
- **Host a server:** [Setting Up Lakeshore Service](/lakeshore/setting-up-lakeshore-service.md).
- **Add an existing service to DreamLake:** [Connect Lakeshore to DreamLake](/lakeshore/connect-to-dreamlake.md).

## 1. Install the SDK

Use Python 3.11 or newer:

```bash
pip install dreamlake-lakeshore
```

This example uses the SDK's local SQLite queue. In the shell where you will run it, unset any remote server setting:

```bash
unset LAKESHORE_URL
```

No server, access token, or CLI is needed for this first run. Queue state is stored under `~/.lakeshore` by default.

## 2. Submit, execute, and read the result

Save this complete example as `hello_udf.py`:

```python file="hello_udf.py"
import dreamlake.lakeshore as dls

@dls.udf(queue="quickstart-hello")
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    q = dls.SyncQueue("quickstart-hello")
    inv = add.submit(2, 3)
    print("invocation:", inv)

    dls.run_worker(q, once=True)
    print("result:", q.result(inv, timeout=30.0))
```

```bash
python hello_udf.py
```

Expect an invocation ID followed by `result: 5`.

The worker runs in the same process for this first example. The order matters: submit the work, let a worker execute it, then read the result. Waiting for a result with no worker running will time out.

While developing the function itself, `add.local(2, 3)` calls it directly without a queue or worker.

## 3. Use an existing Lakeshore service

Get the HTTPS URL, namespace, and client token from the service administrator. If you are the administrator, [set up the service](/lakeshore/setting-up-lakeshore-service.md) first.

Set these values before starting your Python process:

```bash
export LAKESHORE_URL="https://lakeshore.example.com"
export LAKESHORE_NAMESPACE="lab"
export LAKESHORE_CLIENT_TOKEN="your-client-token"
```

Submissions now go to that service. Arrange for a Python worker to drain the same queue, using the same server, namespace, and token. Worker machines also need the function's code and dependencies. See [Simple functions](/lakeshore/patterns.md) for function transport and execution patterns.

The example above runs its worker in the submitting process; changing the URL alone does not move execution to another machine.

The SDK reads these environment variables for dispatch, independently of the Lakeshore CLI's saved login. [Connecting the service to DreamLake](/lakeshore/connect-to-dreamlake.md) is a separate step for viewing the service through DreamLake.

## Next steps

- [Simple functions](/lakeshore/patterns.md): function bodies, submission, and results.
- [Queues](/lakeshore/queues.md): scheduling and workers.
- [Local dev loop](/lakeshore/local-dev.md): run the full stack for development.

---

Source: https://docs.dreamlake.ai/lakeshore/setting-up-lakeshore-service

# Setting Up Lakeshore Service

Host your own Lakeshore control plane and create its first namespace. Run the server steps on the machine that will host the service, then use the Lakeshore CLI from your admin machine.

Already have a server URL and access token? Skip to [Connect Lakeshore to DreamLake](/lakeshore/connect-to-dreamlake.md). To try the Python SDK first, use [Quick start](/lakeshore/quickstart.md).

The examples use `lab` as the Lakeshore namespace. Replace `lakeshore.example.com` with your server's hostname.

## 1. Start the control-plane server

On your server, install Node.js 20+, pnpm, Git, and Docker with Compose. You need access to the workspace repository and its submodules.

```bash
git clone --recurse-submodules https://github.com/dreamlake-ai/lakeshore-workspace.git
cd lakeshore-workspace
docker compose up -d --wait mongo redis
cd lakeshore-controlplane
pnpm install
cp .env.example .env
chmod 600 .env
```

Edit `.env` with these values. Generate the two secrets with the commands below and paste their output into the corresponding fields.

```dotenv
DATABASE_URL="mongodb://localhost:27017/lakeshore?replicaSet=rs0&directConnection=true"
MONGODB_URI="mongodb://localhost:27017/lakeshore?replicaSet=rs0&directConnection=true"
REDIS_URL="redis://localhost:6379"
PORT=8080
SECRETS_KEY="paste-generated-encryption-key"
LAKESHORE_ADMIN_TOKEN="paste-generated-admin-token"
```

```bash
openssl rand -base64 32
openssl rand -hex 32
```

Initialize the database and start the server:

```bash
pnpm prisma:push
pnpm build
NODE_ENV=production node --env-file=.env dist/server.js
```

In another terminal on the server:

```bash
curl --fail http://localhost:8080/healthz
```

Expect `{"ok":true}`. This checks that the HTTP server is running.

For an ongoing service, run the start command under your process manager with this directory as its working directory. Point an HTTPS reverse proxy at port 8080 and configure DNS for `lakeshore.example.com`. Keep MongoDB, Redis, and the backend port private; the workspace Compose file publishes its database ports on all interfaces by default. Keep the encryption key stable across restarts.

## 2. Create a namespace and access token

On your admin machine, install the Lakeshore CLI:

```bash
npm install -g @dreamlake/lakeshore
```

Set the admin token to the same value you put in the server's `.env`. Then create the namespace:

```bash
export LAKESHORE_ADMIN_TOKEN='your-server-admin-token'
export LAKESHORE_URL='https://lakeshore.example.com'
lakeshore admin namespace create lab
unset LAKESHORE_URL
```

Log in as the administrator to mint and save a regular client token:

```bash
lakeshore auth login --server https://lakeshore.example.com --namespace lab --name admin-cli
lakeshore auth status
```

Remove the admin credential from your shell after setup:

```bash
unset LAKESHORE_ADMIN_TOKEN
```

Keep `LAKESHORE_URL` unset after login: setting it makes ordinary Lakeshore commands bypass the saved login token.

## Next: connect or run work

The server is ready when its health check succeeds and `lakeshore auth status` validates your client login.

- [Connect Lakeshore to DreamLake](/lakeshore/connect-to-dreamlake.md) to view its queues, workers, and jobs from DreamLake.
- [Quick start](/lakeshore/quickstart.md) to try a Python function and learn how to point the SDK at your service.

## Documentation

- [Server startup: Hello, local stack](https://lakeshore.dreamlake.ai/admin/happy-paths/03-hello-local-stack)
- [Namespace tokens and login](https://lakeshore.dreamlake.ai/cli/happy-paths/15-token-lifecycle)
- [CLI installation](https://lakeshore.dreamlake.ai/cli/installation)

For large job payloads and durable log storage, also configure [payload storage](https://lakeshore.dreamlake.ai/dev/payload-store) and [log storage](https://lakeshore.dreamlake.ai/dev/log-storage).

---

Source: https://docs.dreamlake.ai/lakeshore/connect-to-dreamlake

# Connect Lakeshore to DreamLake

Use this guide when a Lakeshore server is already running. You need its HTTPS URL, a Lakeshore namespace, an access token for that namespace, and the DreamLake CLI.

If you are hosting the server yourself, first follow [Setting Up Lakeshore Service](/lakeshore/setting-up-lakeshore-service.md). If someone else operates it, ask them for the URL, namespace, and token.

Connecting saves a server connection in DreamLake. It does not start the server or enroll workers. The [Python SDK quick start](/lakeshore/quickstart.md) can use the service directly without this connection.

## 1. Get an access token

Already have a token? Continue to step 2.

For server administrators: after logging the Lakeshore CLI into the intended server and namespace, mint a separate token for DreamLake:

```bash
lakeshore auth status
export LAKESHORE_ADMIN_TOKEN='your-server-admin-token'
lakeshore admin tokens create dreamlake-mount
unset LAKESHORE_ADMIN_TOKEN
```

Use the same admin token configured on the server. Save the printed client token; it is shown once. Keep `LAKESHORE_URL` unset so the CLI uses the server and namespace from your saved login.

## 2. Connect the server

With the DreamLake CLI installed:

```bash
dreamlake login
dreamlake queues mount --uri https://lakeshore.example.com --prefix lab --lakeshore-namespace lab
```

Replace the URL and Lakeshore namespace with the values from your administrator. Paste the access token at the hidden prompt. DreamLake verifies the connection and saves the credential in Vault.

`--prefix lab` is the connection's name in DreamLake. `--lakeshore-namespace lab` is the namespace on the server; the two names can differ.

The connection belongs to your active DreamLake namespace. To use an organization, add `--namespace your-org` to the mount command and every check below.

## 3. Check the connection

```bash
dreamlake queues mounts
dreamlake queues inspect lab
dreamlake queues list lab
dreamlake queues workers lab
dreamlake queues jobs lab
```

`inspect` should report a healthy connection. Empty queues, workers, and jobs are normal before you enroll workers or submit work.

## Disconnect later

```bash
dreamlake queues unmount lab
```

This removes the DreamLake connection. It retains Vault entries and leaves the server running.

---

Source: https://docs.dreamlake.ai/lakeshore/local-dev

# Local dev loop

  Everything on this page runs on one machine with **no AWS account, no cloud
  credential, and no download from the release bucket**. If you can run Docker,
  Node, Rust and Python, you can bring up a control plane, install a daemon you
  compiled yourself, submit a job to it, and watch the result land — start to
  finish, offline.

That constraint is the point, not a convenience. A bring-up that needs somebody
else's cloud account is a bring-up only that person can run, which means it is a
bring-up nobody reviews.

## What you need, and what you deliberately do not

| Needed | Why |
| --- | --- |
| Docker | One container, Mongo, with a single-node replica set. The control plane needs transactions. |
| Node 20+ and `pnpm` | The control plane and the `lakeshore` CLI. |
| A Rust toolchain | You build the `nymph` binary rather than downloading one. |
| Python 3.11+ | The SDK, to submit and to read the result back. |

| **Not** needed | Why not |
| --- | --- |
| An AWS account | Nothing here launches an instance. The daemon is a process on your laptop. |
| A Heroku token, or any deploy credential | The control plane runs from source, on loopback. |
| An admin token | The control plane runs in open mode locally. |
| Any download from the release bucket | `dist-local.sh` produces the exact layout the bucket serves, and the installer reads it over `file://`. |

## The loop

Six steps. Every URL below is loopback.

### 1. Start Mongo

```bash file="terminal"
cd lakeshore-workspace
docker compose up -d mongo
```

The compose healthcheck initiates the `rs0` replica set on first start, so there
is no separate `rs.initiate()` step.

### 2. Start the control plane in open mode

```bash file="terminal"
cd lakeshore-controlplane
pnpm dev            # listens on http://localhost:8080
```

Open mode means no client token is required. It is a local-development posture
and nothing else — do not run a plane this way on an address anything else can
reach.

### 3. Build a local nymph dist

```bash file="terminal"
cd nymph
bash scripts/dist-local.sh          # → ./dist/latest/…
```

This lays out the same five files the release bucket serves under
`dreamlake/nymph/<version>/`: the tarball, the raw binary, a `.sha256` beside
each, and a `VERSION` file. It is the local half of the release workflow, and it
exists so the install path is testable without the internet.

### 4. Install it from a `file://` URL

```bash file="terminal"
bash nymph/scripts/install.sh \
    --base-url "file://$(cd nymph/dist && pwd)" \
    --version latest \
    --dest ~/.local/bin
```

The installer detects your platform, fetches the matching tarball, verifies the
checksum, and drops the binary at `--dest`. It is the same script the published
one-liner runs; only `--base-url` differs.

> **Note:** The installer builds its URL as `${BASE_URL}/${VERSION}/nymph-<arch>-<os>.tar.gz`
>   and fetches it with `curl`. A bare absolute path is rejected outright — curl
>   answers `URL rejected: No host part in the URL` and exits, which `set -e` turns
>   into an aborted install. Noisy, and intentionally so.
>
>   The matching detail on the producing side: the `.sha256` sidecar must record
>   the **bare** archive filename. The installer downloads both files into a fresh
>   temp directory under exactly those basenames, changes into it, and runs
>   `sha256sum -c` there. A checksum file recording `./nymph-….tar.gz`, or an
>   absolute path, fails to verify.

### 5. Run the daemon

```bash file="terminal"
~/.local/bin/nymph --config dev/local-udf-daemon.toml \
    --server http://localhost:8080 --queue '*'
```

Watch it move through the phases on the [worker
lifecycle](/lakeshore/lifecycle.md) page: hello, then setup while it drains any
pending setup commands, then ready.

> **Warning:** `runtime.workdir` defaults to `/var/lib/dreamlake/udf`, which only root can
>   create. The daemon probes that directory for writability before it asserts
>   `ready`, so without a config that points somewhere you own, the daemon
>   heartbeats forever at `setting_up` and never claims anything —
>   `lakeshore daemon list` shows it alive and step 6 hangs. The committed
>   `dev/local-udf-daemon.toml` sets a writable workdir (and a 2 s poll window).
>   There is no `--workdir` flag — `runtime.workdir` is settable only from a
>   config file, so pass one.

### 6. Submit, and read the result back

Point the SDK at the same loopback plane — [Quick start §2. Point at a control
plane](/lakeshore/quickstart.md#2-point-at-a-control-plane) owns that environment,
and `http://localhost:8080` is a perfectly good value for it. Nothing else about
the code changes; you submit and collect exactly as you would against a hosted
plane.

The fastest confirmation that the daemon is really attached does not involve the
SDK at all — ask the control plane what it can see, then run a command on it:

```bash file="terminal"
lakeshore daemon list                       # the worker you just started
lakeshore daemon exec <daemon-id> 'echo hello from a locally built nymph'
```

That is the whole loop closed: a job you submitted, claimed by a daemon you
compiled, on a plane you started, with nothing fetched from anywhere.

> **Note:** This page is the minimum sequence. The `run-lakeshore` skill in
>   `lakeshore-workspace` drives the same bring-up through `mprocs` — one pane per
>   process, with the ordering, the ports and the wait conditions already encoded.
>   Use it for day-to-day work and use this page to understand what it is doing.

## Uploading results to your DreamLake scope

A run that produces a file should put it somewhere durable, and the somewhere is
your DreamLake scope. The `dreamlake` module resolves three things from the
worker's environment:

| Variable | What it resolves | Default |
| --- | --- | --- |
| `DREAMLAKE_REMOTE` | Which DreamLake to talk to | `https://api.dreamlake.ai` |
| `DREAMLAKE_PROJECT` | Which project to write into, as `slug@namespace` | **Required.** No default |
| `DREAMLAKE_API_KEY` | The identity doing the writing | Falls back to the local token store |

You do not set the first two by hand on the worker. `RunConfig.dreamlake =
{remote, project}` is declared next to the function, travels in the run config,
and the SDK expands it into those two variables in the child environment.
`DREAMLAKE_API_KEY` is the one the daemon supplies for itself — from its own
environment, its systemd unit, or its `host_setup`.

Then the body publishes:

```python file="lifecycle_upload.py"
import dreamlake.lakeshore as dls

@dls.udf(queue="local")
def train(steps: int = 100) -> str:
    out = "./checkpoint.pt"
    ...                                    # write the file
    return dls.run.publish(out, name="checkpoint", type="model")
```

`publish` reads those variables, imports `dreamlake` lazily, and uploads. If the
declaration is missing, the error names the missing piece rather than failing
inside the HTTP client.

> **Warning:** `RunConfig.dreamlake`, `RunConfig.env` (applied to the child environment by the
>   process runner) and `dls.run.publish` all ship. The limit is who the upload is
>   attributed to.
>
>   It is worth stating before it surprises anyone: **the upload
>   happens as the daemon's own DreamLake identity, not as the submitting user's.**
>   On a personal worker those are the same person, which is exactly why the loop
>   on this page is a faithful test of it. On a shared fleet they are not — the
>   artifact lands under whoever's key is in the daemon's environment.
>
>   Closing that gap needs the control plane to mint a short-lived DreamLake token
>   scoped to the submitter, which neither side has today.
>
>   **A token is never carried in the invocation envelope**, and that is a decision
>   rather than an omission. Putting one there would write a live user credential
>   into a database document and onto the daemon wire once per invocation, readable
>   by anything that can read the invocation. The narrower blast radius of a
>   per-worker identity is worth the loss of attribution until the exchange exists.

## Connecting the DreamLake dashboard

The dashboard can be pointed at a control plane by link, which is how you
configure a locally running plane without typing a URL into a form:

```
http://localhost:3000/<your-namespace>/lakeshore?connect=http%3A%2F%2Flocalhost%3A8080&connect_ns=default
```

`connect` is the control plane's base URL, percent-encoded. `connect_ns` is the
Lakeshore namespace to bind to and defaults to `default` —
[namespace-as-prefix](/lakeshore/queues.md#naming-and-the-prefix) is the same idea
it names here. `connect_name` optionally suggests a display name.

The safety posture is the interesting half, because **a query parameter is
attacker-supplied by construction**:

- **The link pre-fills and asks you to confirm. It never creates a connection on
  its own.** You land on the create form, populated, with the host shown in
  isolation so you can read it before agreeing to it.
- **It pre-checks *Skip connection test*.** Creating a connection normally has
  the server probe the supplied URL, which means a link that auto-applied would
  be a one-click server-side request forgery primitive — an attacker choosing
  which address DreamLake's own network reaches. No outbound fetch happens until
  you ask for one.
- **It will never accept a token as a query parameter.** There is no
  `connect_token` and there will not be one. Query strings land in history,
  referrers and server logs; the bearer token is write-only end to end today and
  this is not the feature that changes that.
- **Anything else is rejected at parse time** and simply not pre-filled: a scheme
  other than `http:` or `https:`, or a URL carrying `user:pass@` credentials.
  Plain `http:` on a non-loopback host is pre-filled but escalates the banner to
  a warning — `http:` on `localhost` is the whole point of this page, so it
  passes quietly.
- **The parameters are read once and stripped** from the address bar before the
  dialog opens, so a reload does not re-prompt.

## The hosts registry

Once you have more than one machine, the list of machines you can install onto
lives in a static TOML file in the repo — `dev/hosts.toml` — which
`scripts/hosts.sh` iterates.

```toml file="dev/hosts.toml"
# EVERY ADDRESS IN THIS FILE IS A PLACEHOLDER — loopback or RFC1918 only.
# Replace them before use. Credentials live in ~/.ssh/config; this file
# names an alias, never a key.

[[host]]
name    = "local"
address = "127.0.0.1"          # loopback — your own laptop
arch    = "aarch64-apple-darwin"
role    = "dev"
queues  = ["*"]
install = "local-dist"         # build here, install over file://

[[host]]
name    = "bench-1"
address = "192.168.10.24"      # RFC1918 placeholder — not a real machine
ssh     = "bench-1"            # an alias in ~/.ssh/config, never a key path
arch    = "x86_64-unknown-linux-gnu"
role    = "cpu"
queues  = ["cpu-lane", "default"]
install = "ssh"                # the remote fetches the published tarball itself
```

`arch` is a Rust target triple because that is what picks the tarball name in
step 4. `install` is how the binary gets onto the box: `local-dist` is the
no-network path this page walks, `ssh` lets the remote fetch a published
tarball, and `none` means something else already manages it — an AMI, a systemd
unit, a container image. `hosts.sh list` reads the file; `install` is a dry run
until you pass `--yes`, because a file full of placeholders is a file you must
not act on by reflex.

It is a file rather than a control-plane table for one reason that outweighs the
rest: **it has to work before any host has enrolled.** The worker table is an
*output* of provisioning, empty at exactly the moment you are bootstrapping a
machine that has never run the daemon — and it empties again every time an
elastic queue scales to zero. A git-diffable file is also the right shape for a
list whose main failure mode is somebody adding a wrong address.

    The shortest path from an empty environment to a remote result, and where the
    client environment is documented.

    What the daemon you just started is doing, phase by phase.

    When you outgrow the laptop — launching workers on EC2, GCE or Kube.

---

Source: https://docs.dreamlake.ai/lakeshore/patterns

# Simple functions

One decorator, four body kinds. The SDK inspects your function once at
decoration time and the call convention follows the body you wrote. Everything
on this page runs in-process, so you can paste any of it into a REPL.

## Sync body

A plain `def` returns a plain value.

```python file="patterns.py"
import dreamlake.lakeshore as dls

@dls.udf
def stats(xs: list[float]) -> dict[str, float]:
    return {"mean": sum(xs) / len(xs), "n": len(xs)}

print(stats([1.0, 2.0, 3.0]))
# {'mean': 2.0, 'n': 3}
```

## Async body

An `async def` returns a coroutine. Await it.

```python file="patterns.py"
import asyncio
import dreamlake.lakeshore as dls

@dls.udf
async def embed(x: float) -> float:
    await asyncio.sleep(0.01)
    return x * 2.0

async def main():
    print(await embed(21.0))
    # 42.0

asyncio.run(main())
```

## Generator body

A generator returns an iterator. Nothing runs until the consumer pulls, so a
long sequence costs only what you actually consume.

```python file="patterns.py"
import dreamlake.lakeshore as dls

@dls.udf
def frames(n: int):
    for i in range(n):
        yield {"frame": i, "px": i * i}

it = frames(1000)          # nothing has executed yet
print(next(it))            # runs the body up to the first yield
# {'frame': 0, 'px': 0}

for f in frames(3):
    print(f)
# {'frame': 0, 'px': 0}
# {'frame': 1, 'px': 1}
# {'frame': 2, 'px': 4}
```

## Async-generator body

An `async def` with `yield` returns an async iterator. Pull it with `async for`.

```python file="patterns.py"
import asyncio
import dreamlake.lakeshore as dls

@dls.udf
async def ego_views(traj: str, n: int):
    for i in range(n):
        await asyncio.sleep(0)
        yield {"traj": traj, "frame": i}

async def main():
    views = [v async for v in ego_views("scenes/0007", 3)]
    print(views)

asyncio.run(main())
```

## Chaining

A UDF's output feeds the next one. With plain values, chain by awaiting in
sequence.

```python file="patterns.py"
import asyncio
import dreamlake.lakeshore as dls

@dls.udf
async def decode(path: str) -> list[int]:
    return [ord(c) for c in path]

@dls.udf
async def embed(codes: list[int]) -> float:
    return sum(codes) / len(codes)

async def main():
    print(await embed(await decode("scenes/0007")))

asyncio.run(main())
```

With streaming bodies, chain by passing the iterator itself into the next stage.
Each stage stays lazy, so the whole pipeline pulls one item at a time.

```python file="patterns.py"
import dreamlake.lakeshore as dls

@dls.udf
def decode(path: str):
    for i, c in enumerate(path):
        yield {"i": i, "code": ord(c)}

@dls.udf
def embed(rows):
    for row in rows:
        yield {**row, "vec": row["code"] * 0.5}

@dls.udf
def dedupe(rows):
    seen = set()
    for row in rows:
        if row["code"] in seen:
            continue
        seen.add(row["code"])
        yield row

for row in dedupe(embed(decode("scenes/0007"))):
    print(row)
```

## Fan-out over async bodies

Async UDF calls are ordinary awaitables, so `asyncio.gather` fans them out with
no extra machinery.

```python file="patterns.py"
import asyncio
import dreamlake.lakeshore as dls

@dls.udf
async def score(seed: int) -> float:
    await asyncio.sleep(0.05)
    return seed * 1.5

async def main():
    results = await asyncio.gather(*(score(i) for i in range(8)))
    print(results)
    # [0.0, 1.5, 3.0, 4.5, 6.0, 7.5, 9.0, 10.5]

asyncio.run(main())
```

## Scopes and key-based returns

`dls.scope(prefix)` sets the ambient prefix that `dls.run.read` and
`dls.run.write` resolve against. The body names prefix-relative string keys and
returns the keys it wrote — never the bytes.

```python file="patterns.py"
from pathlib import Path
import dreamlake.lakeshore as dls

@dls.udf
def normalize(raw: str) -> str:
    text = dls.run.read(raw).read_text()
    out = dls.run.write("process/clean.txt")
    out.write_text(text.strip().lower())
    return "process/clean.txt"

root = Path("/tmp/lakeshore-demo")
with dls.scope("scenes/0007", root=root):
    key = normalize("source/raw.txt")
    print(key)
    # process/clean.txt
```

Every call runs in its own forked context, and the contract is checked on the way
out: every key you wrote must appear in what you return. Return a single string,
a list or tuple of strings, or a dict whose values are the keys.

```python file="patterns.py"
@dls.udf
def split(raw: str) -> dict[str, str]:
    for name in ("train", "val"):
        dls.run.write(f"process/{name}.txt").write_text(name)
    return {"train": "process/train.txt", "val": "process/val.txt"}
```

Scopes nest, so a parent prefix composes with a child one:

```python file="patterns.py"
with dls.scope("scenes/0007", root=root):
    with dls.scope("cameras/front"):
        print(dls.run.write("rgb/0000.png"))
        # /tmp/lakeshore-demo/scenes/0007/cameras/front/rgb/0000.png
```

Generator bodies may yield partial manifests; they are concatenated and checked
once the generator is exhausted.

```python file="patterns.py"
@dls.udf
def shard(n: int):
    for i in range(n):
        dls.run.write(f"process/shard-{i}.txt").write_text(str(i))
        yield f"process/shard-{i}.txt"

with dls.scope("scenes/0007", root=root):
    print(list(shard(3)))
    # ['process/shard-0.txt', 'process/shard-1.txt', 'process/shard-2.txt']
```

## Declaring what it may touch

A scope sets *where* keys resolve. It does not say *what* the body is allowed to
reach. Declaring the readable source, the writable target, and S3 mounts on the
decorator — or once for the whole repo — is its own page:
[Declaring access](/lakeshore/access.md).

## The registry payload

A simple function does not travel as source. It is **registered** — the control
plane keeps its identity and signature, and the invocation carries only a
reference to that record plus the arguments.

```python file="registered.py"
import dreamlake.lakeshore as dls

@dls.udf(queue="gpu")
def encode(
    src: str,                    # Input video key, resolved against the run scope
    dest: str = "frames/",       # Output key prefix for the extracted frames
    fps: int = 4,                # Frames sampled per second of source video
    overwrite: bool = False,     # Re-encode even when dest already holds frames
) -> dict[str, str]:
    """Sample frames from a video and write them into the run scope.

    Returns the written keys so the caller does not have to re-list the prefix.
    """
    ...

inv = encode.submit(src="raw/run01.mp4", fps=8)
```

The **inline comment on each parameter is its description** — the same
convention a [command line program](/lakeshore/command-programs.md) uses to
generate `--help`. One rule covers both UDF types.

That decoration produces one `Function` row, keyed by
`(namespaceId, module, qualname, version)`:

```json file="Function"
{
  "namespaceId": "ns_7Yc…",
  "module":      "pipelines.video",
  "qualname":    "encode",
  "version":     "9f2c1e…",
  "source":      "@dls.udf(queue=\"gpu\")\ndef encode(src: str, fps: int = 4, …",
  "signature": {
    "params": [
      { "name": "src",       "annotation": "str",  "default": null,
        "doc": "Input video key, resolved against the run scope" },
      { "name": "dest",      "annotation": "str",  "default": "frames/",
        "doc": "Output key prefix for the extracted frames" },
      { "name": "fps",       "annotation": "int",  "default": 4,
        "doc": "Frames sampled per second of source video" },
      { "name": "overwrite", "annotation": "bool", "default": false,
        "doc": "Re-encode even when dest already holds frames" }
    ],
    "returns": "dict[str, str]",
    "doc": "Sample frames from a video and write them into the run scope. …"
  },
  "createdAt": "2026-08-06T17:02:11.480Z"
}
```

Three things about that record are worth knowing:

> **Note:** A Google- or NumPy-style `Args:` block is a second copy of the signature.
>   Rename a parameter and the docstring keeps the old name, silently — nothing
>   checks them against each other. An inline comment sits on the line it
>   describes, so it moves with the parameter or disappears with it.
>
>   Extraction costs nothing new: the SDK **already captures `source` at
>   decoration time** for the `source` column, so the comments are in hand
>   before anything is parsed. `typing.Annotated[str, "…"]` is the runtime-visible
>   alternative and stays available for cases that need it — it is just noisier
>   for the common one.

- **`version` is the sha256 of the source**, not a number you bump. Edit the
  body and you get a new row; the old one stays, so an invocation recorded last
  week still names the code that actually ran.
- **`source` is captured at decoration time** and is what the dashboard shows
  when you click into an invocation.
- **`signature` is where the prose lands.** `signature.doc` is `__doc__`, and
  each entry in `signature.params` carries its own `doc` taken from the
  parameter's inline comment. That is what makes the registry self-describing —
  a reader asking "what is `dest`?" gets an answer without opening the source.

> **Warning:** Comments are discarded by the interpreter, so this is a source parse. Where
>   source cannot be retrieved — a function defined in a REPL, built by `exec`,
>   or shipped by value because it was not importable — the parameters still
>   register with names, annotations and defaults, and simply carry no `doc`.
>   Missing prose is never an error, and it is the same condition that already
>   pushes `transport` from `ref` to `pickle`.

The envelope on the wire is much smaller — it names the function rather than
carrying it:

```json file="envelope (abridged)"
{
  "kind":     "ref",
  "module":   "pipelines.video",
  "qualname": "encode",
  "queue":    "gpu",
  "args":     { "src": "raw/run01.mp4", "fps": 8 }
}
```

`kind: "ref"` is the importable case — the worker imports `module:qualname`,
fetching and extracting the [code snapshot](/lakeshore/code-snapshots.md) only on
`ImportError`, cached by commit. `kind: "pickle"` is the fallback for lambdas,
closures, and functions defined in `__main__`, where there is nothing importable
to name.

> **Warning:** The `Function` model above is real and the dashboard reads it, but the native
>   HTTP dispatch currently sends a fixed stub — `{"module": "_native_wire",
>   "qualname": "_native_wire.envelope", "version": "v1"}` — rather than the
>   function's own identity. So a registry keyed by real module and qualname is
>   the design, not yet the behaviour on that path. Worker-side resolution already
>   works from `module:qualname` or an explicit `registry={qualname: fn}`.

---

Source: https://docs.dreamlake.ai/lakeshore/preloaded

# Preloaded functions

  Some functions are cheap to call and expensive to prepare. A generative model
  needs its weights in GPU memory before it can produce a single sample — and
  once they are there, every later call is fast. A **preloaded function** is a
  UDF written so that the expensive half happens once per worker rather than
  once per invocation.

Nothing about the decorator changes. This is a
[simple function](/lakeshore/patterns.md) whose body is written to reuse state that
outlives the call.

## What makes it work

`run_worker` is a **claim-and-execute loop in one long-lived process**. It
claims a job, runs the body, and comes back for the next one without restarting.
So anything held at module scope — or memoized behind a cache — survives from
one invocation to the next on that worker.

That is the whole mechanism. There is no preload hook to register:

```python file="generate.py"
import functools
import dreamlake.lakeshore as dls


@functools.lru_cache(maxsize=1)
def _model():
    """Load once per worker process. Every later call returns the same object."""
    import torch
    from diffusers import StableDiffusionPipeline

    pipe = StableDiffusionPipeline.from_pretrained(
        "stabilityai/sd-turbo", torch_dtype=torch.float16
    )
    return pipe.to("cuda")


@dls.udf(queue="gpu")
def generate(prompt: str, steps: int = 4) -> dict[str, str]:
    """Sample one image. The first call on a worker pays the model load."""
    image = _model()(prompt, num_inference_steps=steps).images[0]
    out = dls.run.write("samples/0000.png")
    image.save(out)
    return {"image": "samples/0000.png"}
```

The first invocation on a given worker pays the load. The second through
thousandth do not.

> **Warning:** Putting `_model()` at module scope rather than behind a cached accessor moves
>   the load into **import**, which happens while the worker is resolving the
>   function — before it has claimed anything. A slow import can look like a hung
>   worker, and it runs even for an invocation that would not have touched the
>   model. Load lazily, on first use.

## What resets it

The cache lives and dies with the worker process. Four things end it:

| Event | Effect |
| --- | --- |
| Scale to zero | The worker is terminated; the next invocation reloads from cold |
| Scale up | Each **new** worker starts cold, even while others are warm |
| A new code commit | The worker imports a different tree; the old module is gone |
| Worker replacement | Spot reclaim, host failure, drain |

The first two are the ones that bite, and they are queue settings rather than
code. See [Elastic queues](/lakeshore/queues/elastic.md).

## Keeping workers warm

Preloading trades idle cost against latency, and the queue is where you set the
exchange rate:

- **`fully_elastic` with `min: 0`** throws the weights away every time the
  backlog clears. Correct for a nightly batch; wrong for anything interactive.
- **`pool_with_threshold` with a non-zero `min`** keeps some workers resident,
  so a request arriving after an idle period hits a warm process. This is the
  setting preloaded functions usually want.
- **A dedicated queue.** Routing is caller-side — `@udf(queue="sd-turbo")` — so
  a model-serving queue can hold a warm floor while other work stays elastic.
  Mixing both on one queue means the autoscaler cannot tell the two apart.

## Getting the weights onto the host

The load is only fast if the bytes are local. Three places to put them, in
descending order of how well they work:

1. **Bake them into the image.** `daemonTemplate.image_id` — paid once at build
   time, zero per worker. Best for weights that change rarely.
2. **Fetch them in [host setup](/lakeshore/host-setup.md).** A setup script pulls
   them before the worker takes work. Paid per worker, but off the critical path
   of the first invocation.
3. **Fetch them in the body, behind the cache.** Simplest, and the first caller
   waits.

The fourth option — a shared filesystem holding the weights — is what
[Mounting Storage](/lakeshore/mounts.md) is for, and it is not wired yet.

> **Note:** Worth being explicit: `@udf` takes `fn`, `queue`, `transport`, and `config` —
>   a [`RunConfig`](/lakeshore/registry.md) run declaration whose derived host key
>   decides which worker may claim the run. None of the four is a preload hook.
>   There is no `preload=`, no init callback, and no way to tell the control plane
>   that a worker is warm. Warmth is a property of the process that the platform
>   cannot currently see — which is why the levers above are all indirect.

> **Warning:** `dreamlake.lakeshore.lifecycle` is a real module, exported as `dls.lifecycle`.
>   It ships `@on_host_setup` (once per worker process, before the first body),
>   `@on_run_setup` (before every body), `@on_shutdown` (best effort, on the way
>   out), plus `phase()` and `host_key()` for introspection, and three driver
>   functions — `run_host_setup_hooks()`, `run_run_setup_hooks()`,
>   `run_shutdown_hooks()` — that a worker loop is meant to call.
>
>   **No worker loop calls them.** Grepping for `lifecycle` across the SDK outside
>   that one file hits only its own tests: neither `run_worker()` nor the daemon
>   entrypoint invokes a driver. The module's own docstring admits it — wiring them
>   into `worker.py` and `daemon/entry.py` *"is a follow-up — those files belong to
>   another workstream in this slice, so today an author drives them explicitly."*
>
>   So a `@lifecycle.on_host_setup` hook in your code will simply never run unless
>   you call `run_host_setup_hooks()` yourself. The working preload idiom today is
>   still the lazy memoised accessor above.

## Preload does not work at all on the nymph path

This is the correction that matters most in practice, and it undoes everything
on this page for one of the two execution paths.

Preloading depends on the worker being **one long-lived process**. The nymph
daemon is not that. Its `process` runner spawns a **fresh**
`python3 -m dreamlake.lakeshore.daemon.entry` child per invocation, and its
`docker` runner is `docker run --rm` — a brand-new container every time.

| | The queue-native Python worker | The nymph daemon |
| --- | --- | --- |
| Process model | One process, claim-and-execute loop | One fresh process (or container) per invocation |
| Module-level global survives? | **Yes** | **No** — reloaded every single invocation |
| `lru_cache` accessor survives? | **Yes** | **No** |

On the nymph path the only thing that survives between invocations is **bytes on
the host filesystem**, and under the `docker` runner only if a bind mount is
declared for them. A cached model object is reconstructed from scratch on every
call, so the "first call pays, the rest are free" property does not hold — every
call is the first call.

The practical consequence: bake weights into the image or fetch them in host
setup so that each fresh process is at least reading from local disk, and do not
expect the in-memory cache to buy you anything. The fourth option named above —
a shared filesystem holding the weights — is not available as a fallback either:
it is not wired yet, and nothing in the stack reads a `Mount` today.

## Concurrency

One process, one cached model, several in-flight invocations. A daemon reports a
maximum invocation count and can run more than one at a time, so a cached object
may be shared concurrently. Most inference pipelines are not safe to call
re-entrantly on the same device.

If the body is not concurrency-safe, cap the worker rather than the queue —
guard the shared object with a lock, or run one invocation per worker. The queue
has no per-function concurrency setting.

    The base type — body shapes, scopes, and key-based returns.

    The scaling policies that decide whether a warm worker survives.

    Fetching weights before the worker takes its first job.

---

Source: https://docs.dreamlake.ai/lakeshore/command-programs

# Command line programs

  The second UDF type is a program you run rather than a function you import.
  The unit of work is an argv line, not a callable — which makes it the right
  shape for anything already written as a script, a binary, or a tool you did
  not author.

The first type, a [simple function](/lakeshore/patterns.md), travels as a
reference the worker imports. A command line program travels as a **string the
worker executes**. Everything else — the queue it lands in, the workers that
claim it, the provider that supplied them — is identical.

## Declaring the interface with params-proto

A bare script has no declared interface: the flags it accepts exist only inside
its argument parser. [params-proto](https://github.com/geyang/params-proto)
turns the signature itself into the interface, so the flags, types, defaults and
help text all come from one place.

```python file="encode.py"
from params_proto import proto


@proto.cli
def encode(
    source: str,                 # Input video key, relative to the workdir
    target: str = "frames/",     # Output key prefix, relative to the workdir
    fps: int = 4,                # Frames sampled per second of source video
    width: int = 854,            # Output frame width in pixels; height follows aspect
    overwrite: bool = False,     # Re-encode even when target already holds frames
):
    """Sample frames from a video and write them into the run scope.

    Reads the video at `source`, samples one frame every `1 / fps` seconds,
    resizes each to `width`, and writes them as JPEGs under `target`. Existing
    frames are left alone unless `--overwrite` is passed.

    Prints one written key per line on stdout so the caller can collect the
    result without re-listing the prefix.
    """
    ...


if __name__ == "__main__":
    encode()
```

Two things carry over into the CLI automatically. The **docstring becomes the
program description**, and each **inline comment becomes that flag's help
text** — so `--help` is generated from the same source the function is defined
by, and cannot drift from it:

```bash file="terminal"
$ python encode.py --help
Sample frames from a video and write them into the run scope.
...
  --source      STR    Input video key, relative to the workdir
  --target      STR    Output key prefix, relative to the workdir    (frames/)
  --fps         INT    Frames sampled per second of source video     (4)
  --width       INT    Output frame width in pixels; height follows aspect  (854)
  --overwrite   BOOL   Re-encode even when target already holds frames (False)
```

Underscores in a parameter name become dashes on the command line, so
`batch_size` is `--batch-size`. Booleans are flags: `overwrite: bool = False`
gives `--overwrite`, and a parameter defaulting to `True` gives `--no-<name>`.

## Invoking it

```bash file="terminal"
lakeshore exec --queue gpu "python encode.py --source raw/run01.mp4 --fps 8"
```

The queue is the same object a Python UDF submits to — same claim discipline,
same workers, same elasticity. See [Queue model](/lakeshore/queues.md).

You can pin to a specific worker instead of routing through a queue, but not
both; `queue` and `worker_id` are mutually exclusive.

## Declaring access

A [simple function](/lakeshore/patterns.md) declares what it may reach on the
decorator — `source=` and `target=`, patterns relative to the workdir. A command
line program has no decorator, so the declaration moves to the exec body,
alongside the command:

```json file="POST /v1/namespaces/:ns/exec"
{
  "queue": "gpu",
  "command": "python encode.py --source raw/run01.mp4 --fps 8",
  "workdir": "/workspace",
  "source": ["raw/**"],
  "target": ["frames/**"],
  "mounts": ["raw-video"]
}
```

Same three fields, same meaning, same workdir-relative patterns — see
[Declaring access](/lakeshore/access.md). A repo-wide `.dreamrc` supplies defaults
for both UDF types, so a program that inherits everything it needs declares
nothing here.

> **Note:** The parameters above are *named* `source` and `target` so both UDF types read
>   the same way. Nothing in the runtime binds them.
>
>   That is deliberate. The declaration and the argument are different layers: the
>   declaration says which family of keys this program may ever touch, and the
>   argument says which one this run touches. A magic parameter would collapse
>   them — and would mean any program with a parameter incidentally called
>   `target` acquired behaviour it never asked for.
>
>   So name your primary input `source` and your primary output `target` because
>   it reads well and matches the spec. A program with three inputs should give
>   them descriptive names rather than contorting to fit one reserved word.

> **Warning:** The exec body accepts `queue`, `worker_id`, `command`, `env`, `workdir`,
>   `timeout_s`, `stdin_b64`, and the payload fields. `source`, `target` and
>   `mounts` are not among them, and nothing enforces access on either UDF type
>   today.

## The JSON representation

Two JSON objects matter here, and they are easy to confuse.

### The parsed configuration

params-proto will hand you the resolved parameters as a plain dict, which is
what you serialize when you want to record what a run was actually configured
with:

```json file="config.json"
{
  "source": "raw/run01.mp4",
  "target": "frames/",
  "fps": 8,
  "width": 854,
  "overwrite": false
}
```

Reach it with `dict(encode)` or `encode._dict`. Values are resolved by
precedence — CLI arguments beat direct assignment, which beats a bound context,
which beats environment variables, which beats the declared defaults — so the
dict reflects the run rather than the source.

### The exec wire

What actually crosses to the control plane is the exec body. `command` is the
argv line as a single string:

```json file="POST /v1/namespaces/:ns/exec"
{
  "queue": "gpu",
  "command": "python encode.py --source raw/run01.mp4 --fps 8",
  "env": { "PYTHONUNBUFFERED": "1" },
  "workdir": "/workspace",
  "timeout_s": 900,
  "payloadInline": "<base64>"
}
```

| Field | Meaning |
| --- | --- |
| `queue` | Queue name to route through. Required unless `worker_id` is given; the two are mutually exclusive. |
| `worker_id` | Pin to one worker instead of routing. |
| `command` | The command to run. Required, non-empty. |
| `env` | String-valued environment overlay. |
| `workdir` | Working directory on the worker. |
| `timeout_s` | Wall-clock budget; exceeding it is a terminal `timeout`. |
| `stdin_b64` | Base64 stdin, if the program reads any. |
| `payloadInline` / `payloadRef` | The input payload — inline base64 below the server's inline threshold, otherwise a `{ bucket, key, size }` reference. **Exactly one** may be set. |

The response is a `202` carrying the handle:

```json
{ "exec_id": "01JD2K7Q...", "worker_id": "wkr_..." }
```

Results come back by that id, the same way an invocation's do:

```
POST /v1/namespaces/:ns/jobs/:id/result     { resultInline } or { resultRef }
GET  /v1/namespaces/:ns/jobs/:id/result?wait=N
  → { state, resultInline?, resultRef?, exit_code?, error? }
```

`exit_code` is the part with no analogue on the Python side — a command line
program reports failure by exiting non-zero rather than by raising.

> **Warning:** Command line programs dispatch through `POST /v1/namespaces/:ns/exec`, not
>   through the invocation path a `@udf` submit takes. They share the queue and
>   the workers, but they are two wires: exec jobs do not appear as `Invocation`
>   rows, so they are absent from invocation listings and from anything built on
>   invocation lineage. Treating both as "UDF types" is the intended direction,
>   not a description of one unified code path.

## Large inputs

`payloadInline` is capped server-side. Above that threshold, presign a key
through the payload store and send `payloadRef` instead — the key must begin
with `payloads/`, which is what the presign route mints. The rule is the same
one the Python side follows: bytes stay out of the wire and travel by
reference.

    `source=`, `target=` and `mounts=` in full — patterns, wildcards, and how
    the workdir prefix is assembled.

    The queue both types submit to, field by field.

---

Source: https://docs.dreamlake.ai/lakeshore/agents

# Agents

  An agent is a <strong>name and a prompt</strong>. Everything else is optional
  and layered on when the agent earns it: Claude's <code>tools</code>,
  <code>model</code> and <code>permissions</code> when it should be constrained,
  an <strong>attached RunConfig</strong> when it needs a machine, and
  <strong>arguments</strong> when its prompt has holes in it.

```bash
dreamlake agents create triage --prompt 'You triage failed runs. Read the
terminal event first, classify the failure, quote the line that decided it.'
```

That is a complete agent. No tools list, no permission block, no run config, no
arguments — and it is the normal case, not a degraded one.

> **Status.** The declaration is real: DreamLake stores, validates and serves
> it. **Execution is not.** There is no agent API in the SDK and no agent route
> on the control plane. The [What is stored today](#what-is-stored-today) table
> says field-by-field which half you are in.

> **Warning:** Everything that currently *runs* is a [UDF](/lakeshore/patterns.md) — invoked,
>   runs to completion, returns. If you need remote compute now, that is the
>   surface. This page declares an agent; nothing on it drives one.

## An agent is not a UDF

They share a storage table and nothing else worth knowing, and the difference
shows up first in how they are named. A UDF is addressed as
`<module>.<qualname>` because it is *code*, and that is where code lives. An
agent has a **name**, the way a person does — `triage`, `run-triage`,
`colmap-driver` — scoped to the repository it was created in, so two repos can
each hold a `triage` without colliding.

Nothing about authoring an agent asks you to think in module paths. The CLI
derives the storage segments and prints them once; after that the name is the
name.

| | UDF | Agent |
| --- | --- | --- |
| Identity | `<module>.<qualname>` — a code path | a name, scoped to a repo |
| Body | a Python function | a markdown prompt |
| A RunConfig is | required to place it | **optional**, attached when it needs one |
| Versioned | yes — `version` is `sha256(source)` | the prompt is not; see [below](#why-arguments-and-not-string-formatting) |

## Why Claude's spec

The alternative was to invent a fifth agent format. Claude Code, the Claude
Agent SDK, and Claude Managed Agents already agree on one — `name`,
`description`, `tools`, `model`, a system prompt in the body, and an
allow/ask/deny permission block — and an agent author almost certainly already
writes it. Adopting it means an agent file is portable in both directions: the
same file drives a local `.claude/agents/` subagent and a declared platform
agent, and the fields a reader has to learn are the two that are genuinely ours.

So the rule for this page: **where Claude's spec has an answer, it is the
answer.** The Lakeshore extensions are marked as extensions everywhere they
appear, and they are additive — a plain Claude agent file is a valid
declaration.

## The agent file

The prompt can be a bare markdown file with no frontmatter at all. Add
frontmatter when you want to constrain the agent or give it a machine — this is
the fully-loaded version, and every field in it is optional:

```markdown file=agents/run-triage.md
---
# ── Claude's agent spec — unchanged ────────────────────────────────
name: run-triage
description: >-
  Triages failed invocations: reads a run's logs and events, classifies the
  failure, and proposes the smallest RunConfig change that would fix it.
tools: [Read, Grep, Glob, Bash]
model: claude-opus-5

permissions:
  allow:
    - Read(./runs/**)
    - Bash(lakeshore logs:*)
    - Bash(lakeshore events:*)
    - WebFetch(domain:docs.dreamlake.ai)
  ask:
    - Edit(./runconfigs/**)
  deny:
    - Read(./.env)
    - Read(./secrets/**)
    - Bash(curl:*)
  additionalDirectories: ["../runconfigs/"]
  defaultMode: default

# ── Lakeshore extensions ───────────────────────────────────────────
run_config: gpu-a10g
queue: gpu-a10g
channel:
  kind: http-sse
  target: /v1/agents/triage/stream
  config: { heartbeatSeconds: 15, maxIdleSeconds: 900 }

grants:
  - dreamlake.nodes.read
  - lakeshore.queues.submit:gpu-a10g

arguments:
  - name: invocation_id
    type: string
    required: true
    description: The failed invocation to triage.
  - name: max_log_lines
    type: integer
    default: 200
    description: How much of the tail to read before giving up on a quote.
---

# Run triage

You triage failed invocations on a Lakeshore control plane. You are given one
invocation id and read-only access to its logs, its events, and the RunConfig
it resolved against.

The invocation is `{{ invocation_id }}`. Read at most `{{ max_log_lines }}`
lines from the end of its log.

## Procedure

1. Read the terminal event first…
```

The body **is** the system prompt, exactly as in Claude Code. Everything above
the second `---` is configuration; everything below it is behaviour.

## Creating one

```
dreamlake agents create [name] [options]
```

Three ways in, and they compose — frontmatter supplies the defaults, flags win.

### Writing the prompt in the terminal

A prompt longer than one line wants a **quoted heredoc**. Quote the delimiter —
`<<'AGENT'`, not `<<AGENT` — or the shell expands `$VARIABLES` and backticks
inside your prose before the CLI ever sees it:

```bash
dreamlake agents create triage --file - <<'AGENT'
# Run triage

You triage failed invocations. Read the terminal event before the logs — it
says whether the worker died, the container exited, or the body raised, and
those three send you to different places.

Quote the single log line that decided your classification. One line.
AGENT
```

No frontmatter, and none needed. To open `$EDITOR` on a filled-in scaffold and
declare whatever you save:

```bash
dreamlake agents create run-triage --edit
```

To use a file you already have — the same file that works in `.claude/agents/`:

```bash
dreamlake agents create --file agents/run-triage.md
```

> **Note:** `cat agents/run-triage.md | dreamlake agents create` reads stdin without
>   `--file -`. The explicit form is worth typing anyway: it makes the command
>   read the same whether or not something is piped into it.

### Specifying properties

Every field in the frontmatter has a flag. Reach for the flags when you are
adding one property to an otherwise simple agent, and for the file when the
agent has enough configuration that a diff of it is worth reading.

| Property | Flag | Example |
| --- | --- | --- |
| Name | positional, or `--name` | `dreamlake agents create run-triage` |
| Description | `--description` | `--description 'Triages a failed invocation.'` |
| Tools | `--tools` (CSV) | `--tools Read,Grep,Glob,Bash` |
| Model | `--model` | `--model claude-opus-5` |
| Allowed | `--allow` (repeatable) | `--allow 'Read(./runs/**)'` |
| Ask first | `--ask` (repeatable) | `--ask 'Edit(./runconfigs/**)'` |
| Denied | `--deny` (repeatable) | `--deny 'Bash(rm:*)'` |
| Extra roots | `--add-dir` (repeatable) | `--add-dir ../runconfigs/` |
| Unmatched calls | `--permission-mode` | `--permission-mode acceptEdits` |
| Machine | `--run-config` | `--run-config gpu-a10g` |
| Queue | `--queue` | `--queue gpu-a10g` |
| Resource grants | `--grant` (repeatable) | `--grant dreamlake.nodes.read` |
| Prompt arguments | `--arg` (repeatable) | `--arg 'invocation_id:string!'` |
| Channel | `--channel` | `--channel http-sse:/v1/agents/triage/stream` |

Everything on one line:

```bash
dreamlake agents create run-triage \
  --description 'Triages a failed invocation and proposes the smallest fix.' \
  --tools Read,Grep,Bash \
  --model claude-opus-5 \
  --allow 'Read(./runs/**)' \
  --allow 'Bash(lakeshore logs:*)' \
  --deny  'Read(./.env)' \
  --deny  'Bash(rm:*)' \
  --run-config gpu-a10g --queue gpu-a10g \
  --arg 'invocation_id:string!' \
  --arg 'max_log_lines:integer=200' \
  --arg 'verdict_detail:enum(terse|normal|forensic)=normal' \
  --prompt 'Triage {{ invocation_id }} at {{ verdict_detail }} detail.
            Read at most {{ max_log_lines }} lines from the end of its log.'
```

> **Warning:** `Bash(npm run test:*)` contains a glob and parentheses; `enum(a|b|c)` contains
>   a pipe. Unquoted, the shell gets there first — `|` becomes a pipeline and `*`
>   becomes whatever is in the current directory. Single-quote every `--allow`,
>   `--ask`, `--deny` and `--arg`.

### The `--arg` mini-syntax

Designed so the common cases fit in one shell word:

| Written | Means |
| --- | --- |
| `invocation_id:string!` | required — `!` |
| `max_log_lines:integer=200` | defaulted — `=` |
| `verdict_detail:enum(terse\|normal\|forensic)=normal` | a fixed set, with a default |
| `dry_run:boolean=false` | a boolean default |
| `scene:string! "the scene id"` | a trailing description |

`!` and `=` are mutually exclusive: required plus a default are two statements
that contradict each other, and either reading silently disables the other.

### Naming

An agent's name is scoped to the **repository you are standing in**, so
`dreamlake agents create triage` inside `dreamlake-starter-kit` stores a `triage`
that cannot collide with the `triage` in another repo. Both the name and the
scope are printed before anything is sent:

```
agent    triage
  remote:      https://api.dreamlake.ai
  namespace:   chengdu
  scope:       dreamlake_starter_kit   (from repo /Users/…/dreamlake-starter-kit)
  prompt:      412 characters, from stdin
  tools:       (omitted — Claude reads that as inherit all)
  permissions: 0 allow / 0 ask / 0 deny   defaultMode=default
  run_config:  —   queue: —
  arguments:   0 declared, 0 substituted
```

With no name at all one is **generated** — from the description if there is one,
otherwise as `agent-<8 hex>`. The generated form is deliberately ugly so it
invites being renamed rather than being left in place forever. Override any of
it with `--name`, `--scope` or `--qualname`.

### Checking before writing

`--dry-run` resolves everything, runs every validation, prints the result and
sends nothing:

```bash
dreamlake agents create --file agents/run-triage.md --dry-run
```

That is the cheapest way to see what a placeholder typo or an unquoted rule
actually does, because the checks that matter are the ones that only fire once
the prompt and the spec are read together:

```
✗ the prompt uses {{ invocaton_id }} but declares no such argument.
✗ argument 'x' is required AND carries a default. One of those is a lie.
✗ permissions has unknown key(s) allowed — expected only allow, ask, deny, …
✗ frontmatter.auth.api_key looks like a credential.
```

## Fields taken from Claude, unchanged

| Field | Type | Meaning |
| --- | --- | --- |
| `name` | string | The agent's identifier. Kebab-case, unique in the namespace. |
| `description` | string | *When to use this agent* — written for whatever is choosing between agents, not for a human scanning a table. |
| `tools` | list \| omitted | Which tools the agent may call. **Omit to inherit everything available.** A list is exhaustive — there is no "all except". |
| `model` | string | The model to run it on. Claude Code's aliases (`opus`, `sonnet`, `haiku`, `inherit`) are accepted; so is a full model id such as `claude-opus-5`. |

`tools` names *capabilities*; it is not a permission list. `tools: [Bash]` says
the agent may call Bash at all; `permissions` says which commands. Both are
required for a Bash call to happen, and they are validated independently.

## Permissions — what it may touch

Lifted verbatim from Claude Code's `settings.json` `permissions` block, so the
rule strings are the ones you already write.

| Key | Meaning |
| --- | --- |
| `allow` | Rules that run without asking. |
| `ask` | Rules that pause for confirmation. |
| `deny` | Rules that are refused outright. |
| `additionalDirectories` | Extra roots the agent may read and write outside its workdir. |
| `defaultMode` | `default` \| `acceptEdits` \| `plan` \| `bypassPermissions` — what happens to a call no rule matches. |

**Precedence is `deny` > `ask` > `allow`**, and it is not overridable. A path in
both `deny` and `additionalDirectories` is denied; that is the point of having
`deny`.

### Rule syntax

A rule is `Tool` or `Tool(specifier)`. A bare tool name matches every use of it.

| Rule | Matches |
| --- | --- |
| `Bash(npm run test:*)` | Any Bash command whose text starts with `npm run test`. `:*` is a **prefix** wildcard, not a glob. |
| `Read(./data/**)` | Reads under `data/`, relative to the agent file. |
| `Edit(src/**/*.ts)` | Edits to TypeScript under `src/`. Gitignore-style patterns. |
| `Read(//var/log/**)` | An absolute path — note the leading `//`. |
| `Read(~/.config/**)` | A path under the invoking user's home. |
| `WebFetch(domain:docs.dreamlake.ai)` | Fetches of that host only. |
| `Read` | Every read, anywhere the agent can reach. |

Three traps worth naming, because each of them is a rule that looks like it
works and does not:

- **`Bash` rules match the command string, not the effect.** `Bash(git:*)`
  does not stop `sh -c "git push"`, and it never will. Treat Bash rules as a
  convenience over an already-trusted command set, not as a sandbox boundary.
- **A `deny` on a path does not stop a tool that reaches it another way.**
  `Read(./.env)` denies the Read tool; `Bash(cat:*)` still prints the file.
  Deny the *route*, not only the destination.
- **Relative paths resolve against the agent file**, not the invocation's
  workdir. Under a `run_config` that mounts a repo somewhere else, an
  unanchored `Read(src/**)` is not the path you pictured. Use
  `additionalDirectories` and absolute rules when the layout is set by a mount.

### Tool rules vs. resource grants

Two lists, deliberately, because they answer different questions:

| | Governs | Vocabulary |
| --- | --- | --- |
| `permissions` | Tools and files — what the *process* may do | `Tool(specifier)`, from Claude |
| `grants` | DreamLake and Lakeshore resources — what the *identity* may reach | `domain.resource.verb[:scope]`, IAM-style |

`Read(./data/**)` says nothing about whether the agent may publish a dataset
version; `dreamlake.datasets.release` says nothing about whether it may run
`rm`. The grant registry, its closed verb set, and the scope rules are on
[Agent permissions](/workflows/agent-permissions.md).

## Attaching a run configuration

The first of the two extensions, and the one Claude's spec has no opinion about
because Claude Code runs on the machine you are already sitting at.

**It is optional.** A prompt-only agent needs no machine and most do not have
one. Attach a RunConfig when the agent has to run somewhere in particular — a
GPU, a specific image, a prepared host — and leave it off otherwise.

| Field | Meaning |
| --- | --- |
| `run_config` | The name of a [RunConfig](/lakeshore/registry.md) — image, resources, `host_setup`, `run_setup`, `env`, `timeout_s`, mounts, provider. |
| `queue` | Which queue to submit on. The queue is the operator's surface; the RunConfig is the author's. |

`run_config` **names an existing RunConfig; it does not copy one.** That is the
point of the indirection: the machine can be re-tuned, or shared with a UDF that
needs the same host, without touching the agent. The RunConfig is a full
declaration and is documented on its own; the two things worth knowing here are:

- **Placement is derived, not declared.** The RunConfig's `host_key` is a hash
  of the subset that affects placement (`runner`, `image`, `resources`,
  [`host_setup`](/lakeshore/host-setup.md), `provider`, `extras`). Two agents with
  the same key can share a warm worker; two that differ in `image` never will,
  however similar they look.
- **The lifetime mismatch is the open design problem.** A RunConfig describes a
  *host for an invocation*. An agent is meant to outlive individual
  invocations, which raises questions a RunConfig does not answer — how long the
  process is kept alive, what happens to its workdir between calls, what
  restarts it. Those are tracked on the lakeshore side under
  [Agent lifecycle](/dev/agent-lifecycle), and
  none of it is built.

> **Note:** Nothing in an agent file says how many machines to keep warm or which instance
>   types are permitted. That is queue-level fleet policy and it belongs to the
>   operator. `run_config.extras.instance_type` is a *request*.

## Arguments — values substituted into the prompt

The second extension. An agent's prompt is usually a procedure with holes in it:
*which* invocation, *which* dataset, *how many* lines. Declaring those holes is
better than string-formatting the prompt at the call site, for a reason that is
about auditability rather than convenience — see
[Why arguments and not string formatting](#why-arguments-and-not-string-formatting).

### Declaring

```yaml
arguments:
  - name: invocation_id
    type: string
    required: true
    description: The failed invocation to triage.
  - name: max_log_lines
    type: integer
    default: 200
    description: How much of the tail to read before giving up on a quote.
  - name: strict
    type: boolean
    default: false
```

| Key | Required | Meaning |
| --- | --- | --- |
| `name` | yes | The placeholder's name. Must be a valid identifier. |
| `type` | yes | `string` \| `integer` \| `number` \| `boolean` \| `enum`. |
| `required` | no | Defaults to `false`. `required: true` and `default:` together is an error — one of them is a lie. |
| `default` | no | Used when the caller omits the argument. Must typecheck. |
| `values` | for `enum` | The permitted values. |
| `description` | no | Documentation. Not sent to the model. |

### Substituting

A `{{ name }}` placeholder in the body is replaced with the argument's value.
Whitespace inside the braces is ignored, so `{{name}}` and `{{ name }}` are the
same placeholder.

```markdown
The invocation is `{{ invocation_id }}`. Read at most `{{ max_log_lines }}`
lines from the end of its log.
```

dispatched with `{ "invocation_id": "01KZCCC93W…" }` renders as:

```markdown
The invocation is `01KZCCC93W…`. Read at most `200` lines from the end of its
log.
```

The rules, in the order they bite:

1. **A placeholder with no matching `arguments` entry is an error at declare
   time**, not a blank at dispatch time. A typo'd `{{ invocaton_id }}` fails the
   declaration.
2. **A declared argument that appears in no placeholder is a warning**, not an
   error — an argument may legitimately be consumed by a tool rather than the
   prompt.
3. **A missing required argument is an error at dispatch**, before the agent
   starts. It is never rendered as an empty string.
4. **Values are inserted as text, never as instructions.** Substitution happens
   once, on the literal placeholder; a value containing `{{ … }}` is not
   re-scanned. This is not a security boundary — an argument that reaches the
   prompt is still untrusted input the model reads — but it does mean an
   argument cannot manufacture *new* placeholders.
5. **Placeholders are body-only.** `{{ … }}` in frontmatter is not substituted.
   An agent does not get to pick its own `run_config` at dispatch.

### Claude compatibility

Claude Code's slash-command argument forms are accepted and lower onto the same
list:

| Written | Equivalent |
| --- | --- |
| `$1` … `$9` | Positional arguments — `arguments[0]` … `arguments[8]` by declaration order. |
| `$ARGUMENTS` | Every positional argument, joined with a single space. |

Named `{{ … }}` is preferred for anything declared, because `$3` does not
survive someone reordering the `arguments:` list. The positional forms exist so
a command file pasted from `.claude/commands/` keeps working.

### Why arguments and not string formatting

You could format the prompt yourself and send the finished text. The reason not
to is that **`markdown` lives on the mutable head and has no version history.**

Pin an agent to a 64-character version and you have pinned the *code* it runs.
Its *instructions* can be rewritten by anyone with write access, at any time,
and every pinned caller silently gets the new text. That is a deliberate storage
decision — folding prose into `sha256(source)` would fork the identity of every
function — but it means a run is not reconstructable from the declaration alone.

Declared arguments are the seam that fixes this: because the platform does the
substitution, it can **record the rendered prompt on the invocation**. The
template can drift afterwards and the run still says what it actually asked.
Hand-formatted prompts have no such record, so the audit trail is only as good
as whatever your call site happened to log.

## What is stored today

Field by field, because the gap between "specified" and "stored" is the whole
risk of reading this page.

| Field | Stored | Validated | Read by anything |
| --- | --- | --- | --- |
| `name` → `module` + `qualname` | ✅ column | ✅ identity is `(namespace, "<module>.<qualname>")` | ✅ |
| `description` | ✅ column | — | ✅ list + search |
| body → `markdown` | ✅ column | — | ✅ rendered in the dashboard |
| `channel` | ✅ column | ✅ shape `{ kind, target?, config? }` **and a full-depth credential walk** | ❌ nothing attaches |
| `kind: agent` | ✅ column | ✅ `markdown`/`channel` on a non-agent is a 400 | ✅ `?kind=agent` filter |
| `tools` | ⚠️ `metadata` only | ❌ | ❌ |
| `permissions` | ⚠️ `metadata` only | ❌ | ❌ |
| `grants` | ⚠️ `metadata` only | ✅ *in workflow `uda` nodes* — not on runnables | ❌ enforcement ships with the engine |
| `run_config` / `queue` | ⚠️ `metadata` only | ❌ as an agent field. The RunConfig **row** is real, and its `host_key` **is** enforced at claim time | partially |
| `arguments` | ⚠️ `metadata` only | ❌ | ❌ no renderer server-side |
| lifecycle | ❌ | ❌ | ❌ undesigned |

`metadata` is a free-form JSON object on the runnable — it round-trips, so a
declaration can carry the full spec today and a client can read it back and act
on it. Two consequences to be clear-eyed about:

- **`metadata` is not walked for credentials.** Only `channel` is. A token in
  `metadata` is stored in plaintext and returned to anyone with read access to
  the namespace. There are deliberately no secret columns on `Runnable`;
  credentials belong on a `Source` or a `LakeshoreProvider` and are referenced
  by name.
- **`metadata` is shallow-merged on update.** Patching `metadata.tools` replaces
  the whole `tools` key; it does not merge into it.

## Not the same as a workflow `uda` node

DreamLake workflows have their own agent concept — **`uda`** nodes: a typed
member of a static workflow graph, with `instructions`, `model`, `tools` and
`permissions` inline. That is a *node in a graph*, not a long-lived worker, and
it is documented at [Workflow node types](/workflows/node-types.md) and
[Agent permissions](/workflows/agent-permissions.md).

The two now share a vocabulary — `tools` is a tool list in both, `permissions`
means grants in the node and tool rules here — which is exactly the collision
worth flagging rather than leaving for someone to trip over. They are separate
declarations today and converging them is future work, not a shipped thing.

## Try it

The one-liner, against whatever you are logged into:

```bash
dreamlake agents create triage --prompt 'You triage failed runs.' --dry-run
dreamlake agents create triage --prompt 'You triage failed runs.'
dreamlake runnable show <the name it printed>
```

`02_agent` in the [starter kit](/lakeshore/quickstart.md) goes further — it declares
the fully-loaded agent against a real server, reads it back, renders its prompt
with real arguments, and earns a real 400 from the credential walk:

```bash
cd dreamlake-starter-kit/02_agent
make check    # offline — validates the file and the argument bindings
make render   # offline — prints the rendered prompt for a set of arguments
make live     # LIVE-REG — declares it, reads it back, renders it server-side-of-the-wire
```

## Execution overview

See [Agent execution overview](/lakeshore/agents/overview.md) for RunConfig
placement, prompt arguments, and the open lifecycle questions.

---

Source: https://docs.dreamlake.ai/lakeshore/agents/overview

# Agent execution overview

An agent is a **name and a prompt**:

```bash
dreamlake agents create triage --prompt 'You triage failed runs. Read the
terminal event first, classify the failure, quote the line that decided it.'
```

That is a complete agent. Everything else is optional and layered on when the
agent earns it — Claude's `tools`, `model` and `permissions` when it should be
constrained, an **attached RunConfig** when it needs a machine, and
**arguments** when its prompt has holes in it.

The configured form is **Claude's agent spec** — the same frontmatter file you
would otherwise drop in `.claude/agents/` — with two additions this platform
needs:

- an optional **run configuration**, because unlike Claude Code an agent here
  does not run on the machine you are sitting at, and
- **arguments**, values substituted into its prompt at dispatch so that a run is
  reconstructable from what was recorded rather than from a template that may
  have changed since.

An agent is **not a UDF**. They share a storage table and nothing else worth
knowing: a UDF is addressed as `<module>.<qualname>` because it is code, an
agent has a name the way a person does, and a UDF needs a RunConfig to be placed
where an agent usually has none.

> **Warning:** The agent *record* is real and DreamLake stores it. **Execution is not.** There
>   is no agent API in the SDK, no agent route on the control plane, and no agent
>   entry in the CP schema. `dls.lifecycle` exports `on_host_setup` /
>   `on_run_setup` / `on_shutdown` and **nothing calls them**. Everything on this
>   page that describes an agent *running* describes the intended shape.
>   [Functions](https://lakeshore.dreamlake.ai/get-started/functions) is what runs today.

## Where the pieces live

The split follows the platform's general rule — **DreamLake owns declarations,
Lakeshore owns execution**:

| | Owner | What it holds |
| --- | --- | --- |
| The agent file | DreamLake | `name`, `description`, `tools`, `model`, `permissions`, the prompt body, `arguments` |
| The RunConfig it names | DreamLake | image, resources, `host_setup`, `run_setup`, `env`, `timeout_s`, mounts, provider |
| The queue, invocations, workers, events | Lakeshore CP | everything ephemeral |

The **reference for the declaration** —
[Agent declaration reference](/lakeshore/agents.md) has the
field-by-field tables, the permission rule syntax, and the argument grammar.
This page is the execution view: what a run configuration means for something
that is supposed to outlive a single call, and where the design is still open.

## The file, in brief

```markdown file=agents/run-triage.md
---
name: run-triage
description: Triages failed invocations and proposes the smallest RunConfig fix.
tools: [Read, Grep, Glob, Bash]
model: claude-opus-5

permissions:
  allow: [Read(./runs/**), Bash(lakeshore logs:*)]
  ask:   [Edit(./runconfigs/**)]
  deny:  [Read(./.env), Bash(curl:*)]

run_config: gpu-a10g
queue: gpu-a10g

arguments:
  - { name: invocation_id, type: string, required: true }
  - { name: max_log_lines, type: integer, default: 200 }
---

You triage failed invocations. The invocation is `{{ invocation_id }}`;
read at most `{{ max_log_lines }}` lines from the end of its log.
```

`name`, `description`, `tools`, `model`, `permissions` and the markdown body are
Claude's spec verbatim. `run_config`, `queue` and `arguments` are the extensions,
and every field above the body is optional — a bare markdown file with no
frontmatter at all is a valid agent.

Declare it with the DreamLake CLI, which takes the file, a heredoc or `$EDITOR`:

```bash
dreamlake agents create --file agents/run-triage.md
dreamlake agents create run-triage --edit
dreamlake agents create triage --file - <<'AGENT'
You triage failed invocations. Read the terminal event before the logs.
AGENT
```

Every frontmatter field also has a flag — `--tools`, `--model`, `--allow`,
`--ask`, `--deny`, `--run-config`, `--queue`, `--arg` — so a one-property agent
does not need a file. The full per-property reference is on
[Agent declaration reference](/lakeshore/agents.md#creating-one).

## Attaching a run configuration

**Optional.** A prompt-only agent needs no machine and most do not have one.
Attach a RunConfig when the agent has to run somewhere in particular — a GPU, a
specific image, a prepared host:

```bash
dreamlake agents create colmap-driver --file agent.md \
  --run-config colmap-docker-gpu --queue colmap-gpu
```

`run_config` **names** an existing
[RunConfig](/lakeshore/registry.md); it does not copy one.
That is the point of the indirection — the machine can be re-tuned, or shared
with a UDF that needs the same host, without touching the agent. It is the same
declaration a queue-bound `@udf` uses, and the same one whose fields you can
read off `lakeshore runconfig get`.

| Field | Effect on the agent |
| --- | --- |
| `runtime.image`, `runtime.resources`, `runtime.host_setup`, `provider`, `extras` | **In the host key.** These decide which worker can serve it. |
| `runtime.env`, `runtime.run_setup`, `runtime.timeout_s`, `tags`, `runtime.docker` | Not in the host key. Applied at exec time. |
| `mounts` | Attached into the workdir before dispatch. Today [metadata only](/lakeshore/mounts.md) — no runner activates them yet, for any kind of job. |
| `queue` | Which queue the work is submitted on, and therefore which fleet policy applies. |

### The host key is what actually places it

There is no second field where an author says "and this needs a GPU host". The
placement requirement is **derived** from the RunConfig by hashing the subset
above:

```
subset   = { v, runner, image, resources, host_setup, provider, extras }
host_key = "hk1_" + base32(sha256(canonical_json(subset))[:10])
```

Two agents with the same key can share a warm worker. Two that differ in
`image`, `resources` or the *order* of `host_setup` steps never will, however
similar they look — and that is the mechanism working, not a bug. A worker may
claim only invocations whose `host_key` is absent or equal to the one it
advertises, so a job whose key nobody advertises **waits rather than running
somewhere wrong**.

This part is not aspirational: the key is computed on every write and the filter
is enforced at claim time today, for UDFs. An agent inherits it unchanged.

### Where the lifetime mismatch bites

A RunConfig describes a **host for one invocation**. An agent is supposed to
outlive individual invocations, and three of the RunConfig's fields stop being
obviously meaningful once it does:

| Field | The question it stops answering |
| --- | --- |
| `timeout_s` | A deadline for *what* — the agent process, or one message it handles? |
| `run_setup` | It runs before every body by definition. Before every *message*? |
| the workdir | Scratch, created at dispatch and discarded at exit — or the thing that makes a long-lived agent worth having? |

The workdir is the substantive one. An invocation's workdir is scratch; a
managed agent's workdir is what stops it re-deriving context on every call — a
checkout, a virtualenv, a cache. That changes the durability contract, and the
open questions (does it survive a restart, is it per-agent or shared, does it
count against the project's capacity grant) are tracked on
[Agent lifecycle](/dev/agent-lifecycle). None of it is built.

> **Note:** Nothing in an agent declaration says how many machines to keep warm, which
>   instance types are permitted, or what the scale-down delay is. That is
>   queue-level fleet policy and it belongs to the operator —
>   see [Scaling rules](https://lakeshore.dreamlake.ai/get-started/scaling-rules). `extras.instance_type` in a
>   RunConfig is a *request*; whether it is permitted is not the author's call.

## Arguments at dispatch

`arguments` declares the holes in the prompt; a dispatch fills them.

```yaml
arguments:
  - name: invocation_id
    type: string          # string | integer | number | boolean | enum
    required: true
    description: The failed invocation to triage.
  - name: max_log_lines
    type: integer
    default: 200
```

A `{{ name }}` placeholder in the body is replaced with the value. The rules,
in the order they bite:

1. A placeholder with **no matching `arguments` entry** fails at declare time —
   a typo is caught before anything runs, not rendered as a blank.
2. A **missing required argument** fails at dispatch, before the agent starts.
3. Values are inserted **as text**, once, on the literal placeholder. A value
   containing `{{ … }}` is not re-scanned. This is not a trust boundary — an
   argument that reaches a prompt is still untrusted input a model reads — but
   it does mean an argument cannot manufacture new placeholders.
4. Placeholders are **body-only**. `{{ … }}` in frontmatter is not substituted;
   an agent does not get to choose its own `run_config` at dispatch.

Claude Code's positional forms (`$1` … `$9`, `$ARGUMENTS`) are accepted and
lower onto the same list, so a file pasted from `.claude/commands/` keeps
working. Prefer named placeholders for anything declared — `$3` does not survive
someone reordering the list.

### Why this is a platform feature and not string formatting

You could format the prompt at the call site and send finished text. The reason
not to is that **the agent's instructions live on the mutable head and have no
version history.** Pinning an agent to a version pins the *code* it runs; the
prose can be rewritten by anyone with write access and every pinned caller
silently gets the new text.

Because the platform does the substitution, it can **record the rendered prompt
on the invocation**. The template can drift afterwards and the run still says
what it actually asked. That is the whole argument for the feature, and it is
the same reason invocation lineage is recorded rather than reconstructed.

The same logic makes a [`git` mount](/lakeshore/mounts.md) and a long-lived agent
natural partners: a `git` mount resolves `ref` → `commit` at dispatch and records
the commit on the invocation, so every action the agent takes is attributable to
an exact tree state. Rendered prompt plus pinned commit is the pair that makes an
autonomous run reconstructable.

## What is missing, by name

Two pieces, both undesigned — not partially built, not behind a flag:

| | What it would be | Where it stands |
| --- | --- | --- |
| **Lifecycle** | What starts an agent, keeps it alive, restarts it when its worker dies, and stops it | `declared → starting → ready → (draining → stopped \| failed \| lost)` is sketched on [Agent lifecycle](/dev/agent-lifecycle), reusing the run-status transport. Nothing implements it. |
| **Channel** | How a message reaches a running agent and how a reply returns | The `channel` field — `{ kind, target?, config? }` — is stored and validated for credentials. It is **read by nothing**. |

The nearest shipped thing to a channel is `Topic` (post / listen with cursor
semantics), but it is local-`Dispatch`-only in practice: over HTTP a topic append
becomes `POST /v1/daemon/result-chunk` with `invocation_id: "<topic-name>"`, and
a topic name is not an invocation row, so it 404s. Making `Topic` work over the
control plane is the cheapest real path to a bidirectional agent channel, and it
is a small, well-shaped change.

## Not the same as a workflow `uda` node

DreamLake workflows have their own agent concept — `uda` nodes: a typed member
of a static workflow graph. That is a node in a graph, not a long-lived worker.
The two now share the `tools` vocabulary, which is worth flagging rather than
leaving to be tripped over: they are separate declarations today, and converging
them is future work.

---

Source: https://docs.dreamlake.ai/lakeshore/registry

# The Registry

  The registry is where a piece of code stops being a file on your laptop and
  becomes a **name** that other people can find, pin and import. DreamLake owns
  the declaration half of that: the name, the source, the signature, and the
  environment the code expects. It owns none of the execution half.

This page is the **write** direction — declaring something and giving it a
version history. The read direction is
[Importing from the Registry](/lakeshore/registry/import.md).

## Two layers, and the split is the whole design

A registered runnable is two rows, not one.

`Runnable` is the **mutable head**. It survives every edit to the function body,
and it is what a name resolves to:

```ts file="Runnable"
interface Runnable {
  id:            string
  namespaceId:   string
  name:          string    // "<module>.<qualname>", unique within the namespace
  module:        string
  qualname:      string
  kind:          string    // "udf" | "session" | "agent"; defaults to "udf"
  description?:  string    // one-line documentation

  markdown?:     string    // agent-only — the agent's INSTRUCTIONS, not its docs
  channel?:      object    // agent-only — { kind, target?, config? }

  latestVersion?: string   // denormalised pointer to the newest version
  metadata?:     object
  createdAt:     Date
  updatedAt:     Date
}
```

`RunnableVersion` is **immutable**. One row per distinct source revision,
append-only — note the missing `updatedAt` and the missing `deletedAt`:

```ts file="RunnableVersion"
interface RunnableVersion {
  id:          string
  runnableId:  string
  namespaceId: string
  version:     string    // sha256(source), LOWERCASE HEX — the content key
  source?:     string    // full source captured at decoration time
  signature:   object    // { params, returns, doc } — shape owned by the SDK
  metadata?:   object
  createdAt:   Date
}
```

The head is keyed `(namespaceId, name, deletedAt)`. The version is keyed
`(runnableId, version)`. Everything below follows from those two keys.

### `kind` is a lifetime, not a substance

`udf`, `session` and `agent` answer one question — how long the process lives:

| `kind` | Lifetime |
| --- | --- |
| `udf` | One-shot. Invoked, runs to completion, returns. |
| `session` | Long-lived, with a bidirectional pipe held open. |
| `agent` | A session plus a policy driving it. |

That is the only axis `kind` encodes. It does **not** say whether the body is
sync, async, a generator or an async generator — see
[what the registry cannot tell you](/lakeshore/registry/import.md#the-registry-cannot-say-what-shape-a-body-is).

## What makes this version *control* and not version *display*

Four properties, and all four are load-bearing.

**1 · Registration is idempotent by content and never overwrites.** Posting a
version that already exists returns **200 with the stored row**, unchanged. A
new one returns **201**. That is safe rather than merely convenient, because
`version` **is** `sha256(source)` — a row already under that key already holds
those exact bytes, so a second caller cannot silently replace what the first one
stored. There is no PUT anywhere in this collection and no way to rewrite a
version row.

**2 · `latestVersion` is a cache, and only one endpoint may move it.** It is
deliberately not settable through `PATCH`; the version-registration endpoint is
the only writer. Re-registering an *older* version hits the 200 path and returns
early, so the pointer never moves backwards. `RunnableVersion` stays the source
of truth — if that denormalised write were ever lost, the newest row is still
findable by `createdAt desc`.

**3 · Deleting the head is soft, and leaves every version intact.** `DELETE` on
a `Runnable` stamps `deletedAt` and stops there. The version rows are untouched;
they are hidden because their parent is tombstoned, not because they were
removed.

**4 · Nothing deletes a version. Not soft, not hard.** There is no endpoint that
deletes a `RunnableVersion` or a `RepoSnapshot` anywhere in the collection.
`DELETE` exists only on the three mutable heads (`Runnable`, `RunConfig`,
`Repo`). Both children are append-only immutable history keyed by content, and
hard-deleting one would orphan every invocation on the control plane that names
it.

## The routes

Every route is namespace-scoped. `:id` resolves as a **24-hex ObjectId** or as
the **dotted name** — the SDK knows the id, a human knows
`examples.embed.embed_frames`, and both work.

| Method | Route | Notes |
| --- | --- | --- |
| `POST` | `/namespaces/:slug/runnables` | Create. 409 on a duplicate name. Needs `runnable:create`. |
| `GET` | `/namespaces/:slug/runnables` | List, paginated. `?kind=` and `?module=` filters. |
| `GET` | `/namespaces/:slug/runnables/:id` | The head, including `latestVersion`. |
| `PATCH` | `/namespaces/:slug/runnables/:id` | Partial. Omitted fields are left alone. `latestVersion` is rejected. |
| `DELETE` | `/namespaces/:slug/runnables/:id` | Soft. Versions survive. |
| `GET` | `/namespaces/:slug/runnables/:id/versions` | History, newest first. **No `source`.** |
| `POST` | `/namespaces/:slug/runnables/:id/versions` | Register. 201 new, 200 existing. Needs `runnable:update`. |
| `GET` | `/namespaces/:slug/runnables/:id/versions/:version` | One version, **with `source`**. |

List responses are enveloped under a collection key — `runnables`, `versions`,
`runConfigs`, `repos`, `snapshots` — alongside the pagination fields. Errors are
always `{ error: string }` and nothing else.

> **Note:** Not `runnable:create` — the version belongs to a runnable that already exists,
>   so pushing one is an update to that runnable. In practice: an org **ADMIN** can
>   push versions, and an org **MEMBER** (READ) can list and read them but cannot
>   push. If your SDK can create a runnable but 403s on the first
>   `POST …/versions`, this is why.

## Declaring, end to end

The `dreamlake` CLI wraps each of the routes above one for one.

```bash file="declare and version"
# 1 — create the head. Create-only; a second run is a 409.
dreamlake declare runnable.json
#   POST /namespaces/<ns>/runnables → 201

# 2 — push the first version. The hash is computed from the file bytes.
dreamlake runnable version push examples.embed.embed_frames \
  --source src/v1_embed.py
#   sha256 = 9f2c…  →  POST …/runnables/<id>/versions → 201

# 3 — edit the source, push again. latestVersion moves.
dreamlake runnable version push examples.embed.embed_frames \
  --source src/v2_embed.py
#   sha256 = 41ab…  →  201

# 4 — push v1 again, unchanged. This is the point of the whole design.
dreamlake runnable version push examples.embed.embed_frames \
  --source src/v1_embed.py
#   sha256 = 9f2c…  →  200 UNCHANGED, and latestVersion stays at 41ab…

# 5 — the history, newest first, without dragging source over the wire.
dreamlake runnable version list examples.embed.embed_frames

# 6 — one version, with its source.
dreamlake runnable version show examples.embed.embed_frames 9f2c…
```

Step 4 is the sentence worth remembering: **the version string is the hash of
the source, so a second caller pushing the same bytes cannot silently replace
what the first one stored, and pushing an old revision does not rewind the
head.**

> **Warning:** The hash is computed from the file bytes and cannot be supplied. This is not
>   ergonomics — `RunnableVersion.version` must stay **byte-identical** to the
>   control plane's `Function.version`, since that identity is what lets a row here
>   and a row there agree with no translation table. A `--version` flag would let a
>   caller mint a key that the SDK will never reproduce, and the two registries
>   would fork with no error anywhere. The CLI prints the hash it computed before
>   it writes.

## RunConfig — the environment, declared separately

A `RunConfig` is the named, reusable declaration of the environment a runnable
runs inside. It is a sibling of `Runnable`, not a field on it.

```ts file="RunConfig"
interface RunConfig {
  id:           string
  namespaceId:  string
  name:         string      // label, unique within the namespace
  description?: string

  runtime:      object      // read by the RUNTIME layer
  extras:       object      // forwarded VERBATIM to the launcher
  tags:         string[]
  provider?:    string      // a LakeshoreProvider NAME, not a foreign key
  hostKey?:     string      // derived "hk1_…"; never accepted from a client

  metadata?:    object
  createdAt:    Date
  updatedAt:    Date
}
```

### `runtime` and `extras` are two audiences, and they do not feed each other

This is the thing readers get wrong.

- **`runtime`** is read by the runtime layer:
  `{ backend?, server?, runner?, image?, resources?, env?, timeout_s?, host_setup?, run_setup? }`.
- **`extras`** is handed to the launcher untouched:
  `{ instance_type?, partition?, time_limit?, n_cpu?, n_gpu?, … }`.

Setting `runtime.resources.gpu` does not fill in `extras.n_gpu`, and setting
`extras.instance_type` does not tell the runtime anything. From the schema
comment, which is the clearest statement of why there are two columns rather
than one bag:

> Keeping them in one bag is exactly what let `_RUNTIME_FIELDS` rot into a
> hand-maintained filter with zero readers; two columns make the boundary a
> schema fact.

`tags` is a typed column rather than a key in either bag because it is the one
field forwarded to **both** halves — an EC2 instance tag and a job tag are the
same string, so it cannot honestly live on one side.

`provider` is a `LakeshoreProvider.name`, **not** a foreign key. The control
plane resolves providers by name, late, and an FK here would break the moment it
does.

### `hostKey` is derived, and its exclusions are claims

`hostKey` is recomputed on every write and **never** accepted from a client — the
create body schema simply has no such property, and `PATCH` recomputes it from
the **merged** value whenever `runtime`, `extras` or `provider` is touched.

```text file="the derivation"
subset    = { v: 1, runner, image, resources, host_setup, provider, extras }
canonical = JSON, UTF-8, no whitespace, keys sorted by code point, recursively
digest    = sha256(canonical)
hostKey   = "hk1_" + base32-lower-nopad(digest[0..10])     // 20 chars total
```

Two configs with the same `hostKey` can share a worker. What is *left out* is
where the meaning is:

| Excluded | Because |
| --- | --- |
| `env` | Applied per invocation. Hashing it would cold-start every job that differs by one variable. |
| `run_setup` | Per invocation as well — it does not change what the machine *is*. |
| `timeout_s`, `tags`, `backend` / `server` | None of them change the machine. |
| `mounts` | Nothing reads a `Mount` anywhere in the stack yet. |

And `host_setup` **is** in the key, with its **order preserved** — the array is
never sorted. Running `pip install torch` before `apt-get install ffmpeg` is a
different host preparation, and pretending otherwise would let a worker prepared
one way serve a job that declared the other. Adding anything to the subset bumps
the prefix to `hk2_`.

```bash file="reading it back"
# Which configs can share a worker?
dreamlake runconfig list --host-key hk1_4d7qz2xk6m3aynbe

# The derived key on one config — you never sent this value.
dreamlake runconfig show gpu-a10g
```

> **Warning:** Four languages implement the host key with no shared code (the Python SDK,
>   nymph, this server, and the TypeScript CLI), and **the Python SDK's copy is the
>   authoritative one** — it runs where the declaration actually exists and stamps
>   `run_config.host_key` at submit time. The server's copy exists so the dashboard
>   can show a key and so a divergence is a *diffable value* rather than a silent
>   one. `src/lib/host-key.ts` says it outright: *"Never treat the value this
>   returns as a scheduling decision."*
>
>   One sharp edge that follows: a **float** anywhere in `resources` makes the key
>   uncomputable, and the server stores `null` rather than rounding. That is a
>   deliberate hard error — IEEE-754 round-tripping through msgpack and three JSON
>   serializers is not something to bet a cache key on — but it means you can end
>   up with an accepted row that has silently lost its placement column. Keep
>   `resources` values integers or strings.

> **Warning:** There is no `RunConfigVersion` model, no history table, and no snapshot of a
>   config as it was when a run used it. The GraphQL schema states the intent
>   plainly: *"Mutable by name and NOT versioned: it is a hand-edited operator
>   record, and references to it (`Invocation.runConfigRef`) are by name on
>   purpose."*
>
>   The consequence is worth saying flatly: **editing a `RunConfig` silently
>   changes what every future run does**, and there is no diff, no history and no
>   rollback. A pinned runnable version plus a mutable config is a *half* pin. If
>   you need the environment pinned too, today the honest move is to create a new
>   config under a new name rather than editing the existing one.

## Agents: `markdown` and `channel`

An agent is a `Runnable` with `kind: "agent"` and two extra columns:

- **`markdown`** — the agent's instructions, authored as Markdown. This is
  **behaviour**. `description` is the one-line documentation, and the two are
  deliberately distinct fields.
- **`channel`** — where the agent's pipe is attached. A stored *declaration*
  only; no live connection, socket or session is modelled in DreamLake.

Both are rejected with a 400 on any `kind` other than `agent`, so a caller who
typed prose into a UDF finds out rather than watching it disappear.

### `channel` is shape-checked and credential-scanned

`channel` must be **exactly** `{ kind, target?, config? }`. Any other top-level
key is a 400. Then every key inside it is walked — to a depth of 8, through
arrays — and rejected if it looks like a credential:

```text file="the credential key pattern"
/token|secret|password|passwd|api_?key|private_?key|authorization|credential|bearer/i
```

Order matters, and it surprises people: the **shape** check runs first, so
`{ token: "x" }` comes back with the *shape* error, not the credential error —
`token` is not one of the three allowed top-level keys. `{ config: { auth: { token: "x" } } }`
is the case that gets the credential error.

> **Warning:** There is no `secretCiphertext` column anywhere in `Runnable`, `RunConfig` or
>   `Repo`. Anything you store in `channel` is stored in **plaintext**, and comes
>   straight back out of every `GET` and out of the GraphQL `Runnable.channel`
>   field to any org member holding only READ. The shape check plus the key walk is
>   the one and only enforcement point there is.
>
>   The fix a caller usually wants is to reference a `Source` (for data) or a
>   `LakeshoreProvider` (for a launcher) **by name**, and let the thing that
>   already does AES-256-GCM hold the secret.

> **Note:** Every document implies it is, including the shape above. The server does not
>   enforce it — `{ target: "#eng" }` with no `kind` is accepted. Treat `kind` as
>   required in your own tooling; just do not expect the API to catch you.

> **Warning:** `markdown` and `channel` are columns on the **mutable head**. Editing an
>   agent's instructions leaves no diff, no history and no rollback — the source
>   hash covers the code and nothing else. The GraphQL schema calls this the
>   *split tripwire*.
>
>   The fix, if it turns out to matter, is a version history **on the head row** —
>   not folding the prose into the source hash. That second option looks cheaper
>   and is much worse: `RunnableVersion.version` is byte-identical to the control
>   plane's `Function.version`, so mixing prose into it would fork the identity of
>   every function in the registry to fix a problem that affects agents only.

## One database caveat that will bite you

> **Warning:** All three head models declare `@@unique([namespaceId, name, deletedAt])`, and
>   `RunnableVersion` declares `@@unique([runnableId, version])`. On MongoDB a
>   Prisma `@@unique` is **not** enforced by the query engine — it is a real
>   database index, and that index only exists once someone has run Prisma's schema
>   push against that database, by hand and out of band. **That has not been run.**
>
>   What you actually get today is a `nameTaken()` pre-read before every create,
>   which is what makes the 409 deterministic in the normal case. The `P2002` catch
>   behind it is a backstop for the race between that read and the write — and it
>   can only fire once the index exists. So **two concurrent creates of the same
>   name can both succeed** on a database without the index, which is exactly the
>   state a fresh test run and a first deploy are both in.
>
>   If you are building anything that creates declarations concurrently, serialise
>   it yourself for now.

## Try it

The starter kit's **`04_version_history`** directory walks the six steps above
against a local control plane — declare, push, edit, push, push the old bytes
back, and watch the 200 — and finishes on the versions panel in the dashboard
with a `?v=<sha256>` deep link.

    The read direction: discover, pin, import, and what is missing.

    What a `@udf` body may look like, and what a version row is capturing.

    `host_setup` is in the host key, and its order is significant.

---

Source: https://docs.dreamlake.ai/lakeshore/registry/import

# Importing from the Registry

  Someone declared a UDF. You want to use it. This page is the read direction —
  discover, pin, pull the source, run it — and, just as importantly, the four
  places where that path stops short of what you would expect.

The write direction is [The Registry](/lakeshore/registry.md).

## The import primitive is three GETs

That is the whole of it. There is no import endpoint, no bundle format, and
nothing to install.

**1 · Discover, or resolve by name.**

```bash file="discover"
GET /namespaces/{ns}/runnables?kind=udf
GET /namespaces/{ns}/runnables/{module}.{qualname}
```

The list is paginated and filterable by `?kind=` and `?module=`. Either way you
get the **head**, which carries `latestVersion` — a sha256 hex string, or `null`
if nobody has ever pushed a version.

**2 · Read the history.**

```bash file="history"
GET /namespaces/{ns}/runnables/{name}/versions
```

Newest first, paginated, and **without `source`** — the list projection drops it
deliberately, because 200 rows of source is megabytes.

**3 · Pull one version, with its source.**

```bash file="one version"
GET /namespaces/{ns}/runnables/{name}/versions/{sha256}
```

This is the **only** route in the entire collection that ever serves `source`.
It also carries `signature` — `{ params, returns, doc }` — which is what tells
you how to call the thing.

## Three ways to do it

### With `curl`

```bash file="import with curl"
NS=my-namespace
NAME=examples.embed.embed_frames
API=https://api.dreamlake.ai
AUTH="Authorization: Bearer $DREAMLAKE_API_KEY"

# 1 — resolve the head and read the pointer.
VERSION=$(curl -sS -H "$AUTH" \
  "$API/namespaces/$NS/runnables/$NAME" | jq -r .latestVersion)
echo "pinning $NAME at $VERSION"

# 2 — pull that exact revision and write the source out.
curl -sS -H "$AUTH" \
  "$API/namespaces/$NS/runnables/$NAME/versions/$VERSION" \
  | jq -r .source > embed_frames.py
```

Two round trips, and there is no way to make it one. See
[no `latest`, no alias, no prefix](#no-latest-no-alias-no-tag-no-prefix) below.

### With the CLI

```bash file="import with the CLI"
# What is out there?
dreamlake runnable list --kind udf

# The head, including latestVersion.
dreamlake runnable show examples.embed.embed_frames

# The history, newest first.
dreamlake runnable version list examples.embed.embed_frames

# Import. Without --version this resolves latestVersion first, then pulls it.
dreamlake runnable import examples.embed.embed_frames --out ./imported

# Import a specific revision. This is what you commit.
dreamlake runnable import examples.embed.embed_frames \
  --version 9f2c1b… --out ./imported
```

`runnable import` is a composition of the GETs above, not a new capability. It
writes the source, `signature.json`, and a `PINNED.json` recording
`{ remote, namespace, name, version }` — because a pin that lives only in shell
history is not a pin.

### With GraphQL

```graphql file="read the registry"
query Imports($ns: String!) {
  runnables(namespaceSlug: $ns, kind: "udf") {
    name
    description
    latestVersion
  }
  runnableVersions(namespaceSlug: $ns, id: "examples.embed.embed_frames") {
    version
    signature
    createdAt
  }
}
```

> **Note:** Every write goes through REST, which owns the validation — the channel-secret
>   rejection, the host-key derivation, the 409 on a duplicate. GraphQL here is a
>   dashboard read surface and carries no mutations at all.
>
>   `RunnableVersion.source` is **deliberately absent** from the GraphQL type:
>   *"Full source is megabytes and GraphQL here has no per-field cost control"*, so
>   a naive `runnableVersions { source }` over a busy namespace would be an
>   unbounded response. Use the REST version-detail route for source.
>
>   One more difference, and it is intentional: GraphQL reports `NOT_FOUND` both
>   for "no such namespace" and for "you cannot read it", so existence never leaks.
>   REST 404s the first and 403s the second.

## What is missing

This is the useful part of the page. Four gaps, all real, all things a reader
will otherwise discover the hard way.

### No `latest`, no alias, no tag, no prefix

The version path parameter takes the **full 64-character lowercase hex** and
nothing else. There is no `?version=latest`, no named alias, no tag, no semver
range, and no short-hash or prefix match. `9f2c1b` is a 404; only the whole
digest resolves.

The one symbolic handle that exists is the `latestVersion` **column on the
head**, which you must read and echo back. So:

> **Pinning is: read `latestVersion` once, write the hex down, and pass it
> forever.** Import-by-name-alone is two round trips, not one, and every "latest"
> in your tooling is a value you resolved at some point in the past and are now
> responsible for.

That is not as bad as it sounds — an immutable content hash is exactly what you
want in a lockfile — but it does mean the registry cannot answer "give me the
current one" in a single call, and any tool that pretends otherwise is caching
the answer somewhere.

### No join

No route returns a `Runnable` together with its `RunConfig`. There is no
`?include=`, no `?expand=`, and no embedded object anywhere in the responses. A
`RunConfig` is referenced by **name** from elsewhere, on purpose — the control
plane resolves late, and `Invocation.runConfigRef` is a name for the same reason.

An importer that wants "the UDF and the environment it runs in" makes two or
three calls and correlates by hand:

```bash file="correlating by hand"
NS=my-namespace
NAME=examples.embed.embed_frames

# 1 — the head, for latestVersion.
HEAD=$(curl -sS -H "$AUTH" "$API/namespaces/$NS/runnables/$NAME")
VERSION=$(echo "$HEAD" | jq -r .latestVersion)

# 2 — the version, for source + signature.
curl -sS -H "$AUTH" \
  "$API/namespaces/$NS/runnables/$NAME/versions/$VERSION" > version.json

# 3 — the environment. The link is a NAME you must already know, or one the
#     publisher stashed in metadata by convention. Nothing in the API joins
#     these two rows for you.
CONFIG=$(echo "$HEAD" | jq -r '.metadata.run_config // empty')
[ -n "$CONFIG" ] && curl -sS -H "$AUTH" \
  "$API/namespaces/$NS/run-configs/$CONFIG" > run-config.json
```

Step 3 is a convention, not an API guarantee. There is no column on `Runnable`
that points at a `RunConfig`.

### DreamLake does not run anything

`declarations.ts` opens by saying so, and closes by repeating it:

> Storage + CRUD only … Nothing here schedules, claims, launches or connects to
> anything.

There is no `POST /run`, no `/invoke`, no queue and no worker in the declaration
routes. Execution reaches the control plane through exactly one door, and it is
an opaque proxy:

```text file="the one execution door"
ALL /namespaces/:slug/lakeshores/:id/proxy/*
```

It forwards the wildcard path verbatim to a registered `Lakeshore`'s base URL
with a decrypted stored bearer token injected, requires `lakeshore:read` for
`GET` and `lakeshore:use` for anything mutating, answers **502** when the
upstream is unreachable, and streams SSE straight back. It is deliberately a
dumb single-target forwarder so it cannot be pointed anywhere but that
Lakeshore's control plane.

> **Warning:** The proxy requires a registered `Lakeshore` row holding an **encrypted control
>   plane token**. If you are evaluating DreamLake with no cloud account and no
>   running control plane, that door is closed to you and no amount of registry
>   access opens it.

So the honest "…and run it" story for a reader with no infrastructure is: import
the source, then run it **locally**, through the SDK, against an in-memory
dispatch.

```python file="run the imported source locally"
import dreamlake.lakeshore as dls
from dreamlake.lakeshore.dispatch import Dispatch

# The file you just imported. Nothing about it is import-specific — a version
# row holds the source exactly as it was captured at decoration time, decorator
# included, so it is an ordinary module.
from imported.embed_frames import embed_frames  # @dls.udf(queue="gpu")

# No control plane, no queue service, no credentials — the whole plane is an
# in-memory SQLite database and the worker runs in this process.
plane = Dispatch(":memory:")
q = dls.SyncQueue("gpu", dispatch=plane)

inv = embed_frames.submit("clip-0001", _dispatch=plane)   # a durable string id
dls.run_worker(q, once=True)                              # claim + execute here
print(q.result(inv, timeout=5))
```

The queue name has to match the one the imported UDF declared — routing is
caller-side and baked into the decorator. If the UDF you imported has no
`queue=`, it is local by default and a plain call runs it directly, with no
dispatch and no worker at all.

The starter kit's **`05_import_from_registry`** directory does exactly this
end to end: resolve, pin, pull, write `PINNED.json`, and run the pulled source
locally.

### The registry cannot say what shape a body is

`Runnable.kind` is a **lifetime** discriminator — `udf`, `session`, `agent` —
and nothing more. There is no field on `Runnable` and no field on
`RunnableVersion` that records whether the body is sync, async, a generator or
an async generator.

That matters because the four shapes are not interchangeable at the call site. A
generator's results arrive as a stream of frames; a sync UDF's arrive as one
value. An importer that guesses wrong writes the wrong caller. Today the only
ways to find out are to read `signature`, if the publisher put something useful
there, or to read the source.

> **Warning:** `RunnableVersion.signature` is free JSON whose **shape is explicitly owned by
>   the SDK**, not by the server. So a key like:
>
>   ```json
>   { "params": [...], "returns": "...", "doc": "...", "form": "async-generator" }
>   ```
>
>   would let the registry answer *"is this a streaming UDF?"* with **no schema
>   change, no migration, and no new column** — the cheapest honest fix available.
>   The starter kit already stamps `signature.form` as a convention and labels it
>   as one.
>
>   The alternative — a real nullable column on `RunnableVersion`, which would let
>   the dashboard badge it and let a list query filter on it — is a genuine
>   improvement and a genuine migration. It has not been decided.

## Importing an agent

An agent imports through the same three GETs, because an agent **is** a
`Runnable` — one with `kind: "agent"` and two extra columns on the head:

| Field | What it is |
| --- | --- |
| `description` | One-line documentation. What it is for. |
| `markdown` | The agent's **instructions**. Behaviour, not documentation. |
| `channel` | `{ kind, target?, config? }` — where the pipe attaches. A stored declaration; never a live connection. |

```bash file="import an agent"
dreamlake runnable list --kind agent
dreamlake runnable show agents.triage.triage_agent
dreamlake runnable import agents.triage.triage_agent --out ./imported
```

`markdown` and `channel` come back on the head response, in plaintext — there
are no encrypted columns on these models, and no read-path stripping. That is
also why `channel` is credential-scanned on the way in; see
[the registry page](/lakeshore/registry.md#channel-is-shape-checked-and-credential-scanned).

> **Warning:** This is a genuine gap and it is worth being blunt about. `markdown` and
>   `channel` live on the **mutable head**, so they are whatever they are *right
>   now*. The version hash covers the source and only the source.
>
>   Pin `agents.triage.triage_agent` at `9f2c1b…` and you have pinned its code.
>   Someone editing the agent's instructions an hour later changes what your
>   "pinned" agent does, and nothing in your lockfile, your diff or your import
>   output will show it. There is no history to compare against either — see
>   [the split tripwire](/lakeshore/registry.md).
>
>   If that matters to you today, copy `markdown` into your own repo at import time
>   and treat drift from it as a review item.

## What you get back

The version-detail route — the only one that serves `source`:

```json file="GET …/runnables/{name}/versions/{sha256}"
{
  "id": "665f1c2a9b4e7d0012ab34cd",
  "runnableId": "665f1c2a9b4e7d0012ab34c9",
  "namespaceId": "665f1c2a9b4e7d0012ab3400",
  "version": "9f2c1b7e5a0d3c8846b1f2e9d47a05c3b8e6142f9ad0cb75e3812f4a6d9c0b17",
  "signature": {
    "params": [
      { "name": "clip_id", "annotation": "str" },
      { "name": "stride", "annotation": "int", "default": 4 }
    ],
    "returns": "dict",
    "doc": "Embed every Nth frame of a clip and return the key it was written to."
  },
  "metadata": null,
  "createdAt": "2026-08-06T11:42:07.918Z",
  "source": "import dreamlake.lakeshore as dls\n\n\n@dls.udf(queue=\"gpu\")\ndef embed_frames(clip_id: str, stride: int = 4) -> dict:\n    ...\n"
}
```

Notes on the shape, since two of them catch people:

- **`source` is nullable.** A version may be registered without one. Check before
  you write a file.
- **`signature` is always an object**, defaulting to `{}` — never `null`. Its
  contents are the SDK's business, not the server's, so treat every key inside it
  as optional.
- **`metadata` is `null` when unset**, not `{}`.
- The list projection (`GET …/versions`) returns every field above **except**
  `source`, enveloped as `{ "versions": [...], "page", "pageSize", "total", "totalPages" }`.
- Errors are always `{ "error": "…" }`.

    The write direction — declaring, versioning, and what is not versioned.

    Once you have imported it, making the expensive half happen once.

    Running against an in-memory dispatch with no infrastructure at all.

---

Source: https://docs.dreamlake.ai/notes/panels

# Panels and agent control

DreamLake views use the native UIKit panel surface: drag, dock, resize, tab and
close work the same for note editors, note lists, artifact views and explicitly
opened web previews.

The [UIKit layout controller](https://uikit.dreamlake.ai/components/layout-controller)
owns destination addressing and the forkable starting-layout → command → result
catalog. DreamLake supplies resource descriptors, view loaders and interaction
policies. The [TabbedContainer](https://uikit.dreamlake.ai/components/tabbed-container)
component presents those alternative scenarios in the docs.

## Share the current view

The address carries the panel tree and its display state. After opening, closing,
tabbing or resizing views, copy the current address to reopen that arrangement.
It restores sidebar collapse and folds, list search/filter/order and selection,
and note/list scroll positions. Folder and project location stay in the ordinary
route. Changes settle for 250 ms, then the latest snapshot is encoded during idle
time; scrolling does not compress or rerender on every event.

![Two note panels restored from one address](/figures/url-layout-restored.png)

Two exact note references, restored at 35/65 width. The route supplies the primary
note ID; auxiliary references retain full IDs. Repeated strings compress through
references to earlier sequence segments. Artifact query strings and fragments
travel with their references. Internal iframe state requires the artifact to
represent it in that address; the host does not introspect iframe memory.

Sharing a view grants no additional access. Unavailable auxiliary notes leave
empty panes or are omitted from a populated tab group, while the primary note
keeps its normal access flow. No catalogue lookup or fuzzy ID resolution is
needed. The codec caps the escaped layout value at 32,000 characters and the
decoded form at 64,000; these are application limits, not a universal browser URL
guarantee. If a layout is unsupported or exceeds the cap, the last usable URL is
retained. Existing version 5, DEFLATE and prototype layout links remain readable.

## Artifact references

Clicking an artifact tag in a note opens its artifact beside the source note.
The default request first activates an existing instance of that artifact. A
fragment such as a slide or section navigates that same mounted view.

For a different artifact, the request chooses the latest preview destination
associated with that source note tab. It replaces an eligible unpinned preview.
Pin the current tab to retain it; the next artifact then opens as another tab.
Dragging a preview out preserves its named association and role, so subsequent
requests can target the original destination, the last one, or a spatial match.
The UI default is the last destination for that source instance.

Pinned tabs can still be moved or explicitly closed. Notes that are still syncing
retain their disposal guard. A failed replacement or stale layout leaves the
existing view intact. Ordinary web links keep browser navigation.

## Note and web-preview references

Note tags and `:preview[https://example.com/#section]` open new targets as tabs
in the existing panel on the right, creating a right-hand panel only when one
is absent. Clicking an already-open target activates it. Different preview URL
fragments are separate tab targets. Opening either kind of reference from a
side Note adds a tab in that same side panel. Existing tabs stay mounted and
retain editor and preview state; these reference clicks do not replace content.

## Agent requests

Each mounted PageViewLayout registers in `window.dreamlakeLayouts` protocol v1.
Agents select a layout, inspect its revision and flat regions, resolve a request
without mutation, then apply it with an optional expected revision. Page reloads
and unmounts invalidate session IDs; list and inspect again instead of guessing.

Use [CLI layout control](https://cli.dreamlake.ai/layout) for an explicitly selected
local browser debugging session. Remote unattended control is not part of this
transport. A successful layout request means placement was accepted, not that an
artifact's asynchronous authorized loader succeeded.

| View kind | Resource identity | Required content metadata |
| --- | --- | --- |
| note | note ID | namespace, noteId; optional fragment |
| artifact | namespace/artifactId | namespace, artifactId; optional fragment |
| resource | namespace/notes | namespace, resource: notes |
| web-preview | normalized URL, or blank for an empty preview | url |

The application validates descriptors and their resource identity before changing
the layout. Inspection exposes descriptors, pins and layout metadata—not note
bodies, credentials, share tokens, editor state or iframe authorization context.
Applications can supply additional content metadata to the generic UIKit layer;
DreamLake's current descriptor table above defines what this adapter exposes.

## Layers and ownership

- UIKit PanelLayout handles low-level geometry and interaction mechanics.
- UIKit's controller handles named families, original/first/last, spatial and
  content queries, placement scope, reuse, pinning and guarded mutations.
- DreamLake handles target validation, content loading and the default artifact
  click policy. Notes content remains governed by the normal revision and
  authorization contracts; layout control cannot grant access to a resource.

The generic request reference lives in UIKit; CLI connection and command recipes
live in the CLI docs. This page describes DreamLake's integration rather than
maintaining a second copy of either API.

---

Source: https://docs.dreamlake.ai/lakeshore/hosts/enroll

# Enroll a host

**Released clients:** no-save SSH enrollment is available in CLI 0.13/Python 0.10 and later. CLI 0.16 (including its npm wrapper)/Python 0.13 support post-enrollment saving; [real hosted staging acceptance](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/infra/vault/hosted-host-saving-acceptance.md) covers Nymph installation, saving, restored SSH and tracked execution. Client release, backend rollout and each environment's live verification remain separate.

Use CLI **0.21.2**, Python **0.16.2** and Nymph **0.1.8** for the current [testing guide](/lakeshore/hosts/testing.md). Existing services are not upgraded by installing a new client; inspect the installed daemon version before testing recovery.

A **host** is a machine that executes or manages work, including a Slurm control node. Nymph maintains its connection independently after SSH bootstrap. Providers are not required to enroll an existing machine. Start with an SSH-accessible host; use [Resource setup](/lakeshore/providers/resource-setup.md) only when infrastructure is needed.

## Inspect in Compute

The [Compute dashboard](https://github.com/dreamlake-ai/dreamlake-ai/pull/310) uses `/:namespace/compute` for the host inventory and `/:namespace/compute/hosts/:hostId` for details. It preserves enrollment instructions, Unix-user identity, verified heartbeat status and a link to tracked runs. Search a group with a pattern such as `fortyfive/bos14/*`, or search `offline`. **Enroll host** opens the CLI handoff; enrollment still starts from an SSH-accessible machine.

Deployed to production on September 15, 2026 (05:10 UTC September 16). The old `/:namespace/hosts` list and detail links redirect to Compute. Host APIs, CLI commands and these guide URLs retain their existing names. See the [UI review guide](/lakeshore/hosts/testing/#review-the-live-host-ui).

## Repair an existing enrollment

CLI **0.20.1** and Python **0.16.1** configure persistent enrolled services with
`runtime.keep_alive_s = -1`. Re-enrollment regenerates `nymph.toml` and its systemd
user unit. Before repair, privately back up those two files on the target; retain
the original identity key. After repair, verify the generated idle setting, then
restore only required custom sections such as `private_tracked` and any reviewed
service overrides. Reload the user manager and restart the same unit if you edit
it, then wait for a fresh verified host status.

For an unresolved response, reuse the original request ID to reconcile it. A
confirmed `request_expired` receipt requires a new explicit repair operation ID;
a separately intended repair after a known completed enrollment is also a new
operation. If the server reports `enrollment_busy`, wait until its `retryAt`
window instead of issuing more operation IDs. Keep the same host name, SSH
profile, Unix user and identity key: the existing host/enrollment is reused,
and changing the identity is rejected. Keep the new ID for reconciliation:

**CLI**

```shell
dreamlake hosts enroll -n fortyfive/bos14/bos14-ctrl \
  --ssh bos14-ctrl --request-id bos14-idle-repair-001 \
  --no-save-credentials
dreamlake hosts status fortyfive/bos14/bos14-ctrl
```

**Python**

```python
from dreamlake import DreamLakeClient

client = DreamLakeClient()
result = client.hosts.enroll(
    "fortyfive/bos14/bos14-ctrl",
    ssh="bos14-ctrl",
    request_id="bos14-idle-repair-001",
    save_credentials=False,
)
host = client.hosts.status("fortyfive/bos14/bos14-ctrl")
```

See the [patch release and owned-host idle validation](/dev/notes/host-enrollment)
for evidence and the distinction between service restart and machine reboot.

## Enroll and inspect

The target needs Python 3, OpenSSL, a systemd user manager with linger enabled by its administrator, and control-plane connectivity. Bootstrap reuses installed nymph or invokes the official installer; it does not install uv. Authenticate your client, verify SSH access, then enroll:

**CLI**

```shell
ssh bos14-ctrl true
dreamlake hosts enroll -p fortyfive/bos14 -n bos14-ctrl \
  --ssh bos14-ctrl --request-id bos14-first-enrollment
dreamlake hosts status fortyfive/bos14/bos14-ctrl
dreamlake hosts status 'fortyfive/bos14/*'
```

**Python**

```python
from dreamlake import DreamLakeClient
client = DreamLakeClient()
result = client.hosts.enroll(
    name="bos14-ctrl", prefix="fortyfive/bos14", ssh="bos14-ctrl",
    request_id="bos14-first-enrollment", wait_seconds=60,
)
host = client.hosts.status("fortyfive/bos14/bos14-ctrl")
group = client.hosts.status("fortyfive/bos14/*")
```

Names are `<namespace>/<group>/<host-name>`. `-p fortyfive/bos14 -n bos14-ctrl` and `-n fortyfive/bos14/bos14-ctrl` identify the same host; conflicting prefixes fail. Keep the machine name (`bos14-ctrl`), and use `bos14-node-000` for another host. Wildcards inspect existing hosts only. A namespace prefix grants no authorization.

The API checks namespace access before target identity creation. Nymph's private key stays on the target; a short-lived grant binds its public key to host, Unix user, and enrollment. The initial implementation reserves the name to its owner and rejects another identity. Adding a second Unix user to the same host requires a future explicit linking workflow; names alone cannot authorize it.

## SSH, passwords, and jump hosts

`--ssh` accepts an SSH-config alias, `user@host`, or a quoted argument vector without a repeated `ssh` executable. Existing local SSH configuration remains useful:

```ssh-config
Host bos14-ctrl
  HostName bos14-ctrl.internal
  User geyang
  Port 2222
  ProxyJump ge@bastion.example.com
  IdentityFile ~/.ssh/bos14_ed25519
```

```shell
dreamlake hosts enroll -p fortyfive/bos14 -n bos14-ctrl \
  --ssh '-J ge@bastion.example.com
    -p 2222
    -i /Users/ge/.ssh/bos14_ed25519
    geyang@bos14-ctrl.internal'
```

Multiline strings preserve argument boundaries without shell expansion. There must be one destination and no appended remote command. Agent forwarding is not required. Never put passwords or private-key contents in arguments or JSON. Verify password access with `ssh geyang@bos14-ctrl.internal`; CLI terminal/password and separate jump-host prompt behavior still need real acceptance. Python always uses noninteractive SSH and fails if a password or passphrase prompt is needed.

## Configuration and dry-run

Save this as `bos14-host.json`. Identity-file paths refer to local bootstrap credentials, not uploaded key contents.

```json
{
  "name": "fortyfive/bos14/bos14-ctrl",
  "ssh": {
    "host": "bos14-ctrl.internal",
    "user": "geyang",
    "port": 2222,
    "identityFile": "/Users/ge/.ssh/bos14_ed25519",
    "jumpHost": "ge@bastion.example.com",
    "options": { "ServerAliveInterval": "30" }
  }
}
```

**CLI**

```shell
dreamlake hosts enroll --config ./bos14-host.json --dry-run --json
```

**Python**

```python
plan = client.hosts.plan(config="bos14-host.json")
preview = client.hosts.enroll(config="bos14-host.json", dry_run=True)
```

Explicit name/prefix fields override configuration fields; SSH replaces the whole SSH object. Unknown fields, invalid ports, unsupported options, and conflicts fail before effects. Dry-run returns `status: "validated"`, `enrolled: false`, and `authorizationVerified: false`; it contacts no server/host and reads no key. Direct-on-target enrollment without SSH is not implemented.

## Readiness, retry, and credentials

`online` means the backend verified a fresh active worker and matching bound identity; it does not prove runner readiness or successful execution. Timeout can return `pending`. Results include stable host/enrollment IDs and operation/request IDs, never bootstrap grants. Reuse the same request ID to reconcile an uncertain write; changed payloads conflict. Exact/group status uses the caller's access. Python raises sanitized exceptions rather than prompting or exiting.

Repeated enrollment and signed restart passed against real services with local transport/supervision adapters. Still verify actual Linux supervision, reboot recovery, and a workload on the intended host. Installation or a heartbeat alone is insufficient.

Credential saving happens after enrollment in native CLI 0.15/Python 0.12 with a compatible backend. Interactive consent defaults to `[y/N]`; `--save-credentials` consents, `--no-save-credentials` declines, and `--quiet` only suppresses progress. Password prompts are masked; Python accepts explicit `HostCredential` inputs and never prompts. Target and jump credentials are selected separately. Saving failure leaves the successful enrollment intact and does not authorize backend SSH delegation. Use CLI 0.16 or later for npm-wrapper password descriptors; the 0.15 wrapper dropped descriptors above 2. See [Managing host credentials](/lakeshore/hosts/credentials.md) for status and the paired acceptance examples.

## Live infrastructure is a separate delivery state

The September 12 bos14 demonstration had a signed Slurm heartbeat directly to `dev-api.lakeshore.dreamlake.ai:443` with trusted TLS and no laptop tunnel. Operator SSH still needs VPN. That recorded deployment required a fresh token after process restart; merged reconnect code does not prove it was upgraded. Production `api.lakeshore.dreamlake.ai` was verified as a separate fresh TLS-protected instance with zero workers. Neither observation establishes production host-API rollout or workload execution.

## Related documentation

- **[Python host API](https://github.com/fortyfive-labs/dreamlake/blob/main/docs/hosts.md)** — Actual methods, errors, pagination, and noninteractive behavior.
- **[Host credentials](/lakeshore/hosts/credentials.md)** — Vault operations and the optional enrollment-saving boundary.
- **[Resource setup](/lakeshore/providers/resource-setup.md)** — EC2/EKS Terraform examples; existing hosts need no provisioning.
- **[Python follow-up plan](/dev/plans/hosts-python-api)** — Remaining parity and acceptance work.
- **[Provider plan](/dev/plans/providers)** — Separate Slurm/Kubernetes registration, provisioning, and workload acceptance.

---

Source: https://docs.dreamlake.ai/lakeshore/hosts/credentials

# Managing host credentials

For a pinned repository task using selected env/file credentials, see [Private tracked runs](/lakeshore/private-runs.md), including CLI/Python submission, recovery and current availability.

For an agent-led checkout and credential provisioning workflow, see
[Setting Up Remote Agent Environment](/lakeshore/hosts/remote-agent-environment.md).

**Available in CLI 0.13.0 and Python 0.10.0 or later.** The hosted vault uses managed AWS KMS without requiring your own cloud account. Entries, scoped access keys, selected SSH/TOTP import and TOTP generation are released; [installed-client production checks](https://github.com/dreamlake-ai/dreamlake-workspace/pull/307) passed. The web Vault supports entry and scoped-key management, expiry and write recovery. See the [runtime note](/dev/notes/vault-runtime) for deployment evidence and remaining acceptance gaps.

Host enrollment saving is available in CLI **0.16.0**, including its npm wrapper, and Python **0.13.0** with a compatible backend. [Hosted staging acceptance](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/infra/vault/hosted-host-saving-acceptance.md) passed; production host saving is a separate rollout. Saving follows enrollment, so saving failure does not undo an online host. The published npm 0.16 wrapper passed target/jump password-descriptor saving; upgrade from the affected 0.15 wrapper. Published CLI 0.18.0/Python 0.15.0 key rotation has [hosted staging acceptance](https://github.com/dreamlake-ai/lakeshore-examples/pull/34). Password lifecycle, broader remote failure coverage and production KMS/retention obligations remain separately tracked in [issue #241](https://github.com/dreamlake-ai/dreamlake-workspace/issues/241).

## Guides and deliverables

- **[Runnable CLI/Python examples](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/README.md):** checkout setup, entry operations, scoped keys and credential imports.
- **[Isolated server](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/server/README.md):** explicit backend/Mongo/KMS configuration for synthetic accounts.
- **[Live smoke runner](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/live_smoke.py)** and **[results](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/LIVE_RESULTS.md):** bos14 AWS KMS roundtrip, client suites, failure handling and cleanup evidence.
- **[Terraform test setup](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/infra/README.md):** isolated plan/apply/test/cleanup commands. Includes reviewed plan/apply, readiness and guarded cleanup. Historical acceptance retained billable infrastructure; check the current state before reuse.
- **[Kubernetes fixture](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/kubernetes/README.md)** and **[Pod Identity IAM setup](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/kubernetes/iam/README.md):** merged in [examples PR #14](https://github.com/dreamlake-ai/lakeshore-examples/pull/14); see the [EKS results](https://github.com/dreamlake-ai/lakeshore-examples/blob/main/15-vault/kubernetes/RESULTS.md).
- **[Vault design and remaining work](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/design/rfcs/vault.md):** host credential selection, sync, lifecycle and KMS policy requirements.

The linked results record synthetic-account tests on bos14 and a Terraform-managed EKS cluster with real AWS KMS, client regression and failure checks, and fixture cleanup. These historical runs are separate from hosted production acceptance and do not establish live GCP readiness.

Personal entries live under your owner name, such as `ge/`. Account permissions control access; no device pairing is required. Customer KMS and BYOC backend setup are optional operator concerns.
## Inspect the owner-only policy tree

The policy tree shows metadata for your owner prefix, including the governing
key and migration state, without reading secret values. Sign in as the owner;
scoped access keys cannot use this view.

**Python 0.17.0 is published on PyPI; CLI 0.22.0 publication is incomplete.**
Use the reviewed CLI candidate or published Python package with a backend that
supports the tree route. A missing route is an error, not an empty tree. See the
[runtime development note](/dev/notes/vault-runtime) for compatibility and acceptance evidence.

**CLI**

```shell
# Explicit personal owner prefix; a scoped key cannot use this policy view.
dreamlake vault list -p ge/training --tree
# One metadata page for scripts; ordinary vault list JSON is unchanged.
dreamlake vault list -p ge/training --tree --to-json --limit 100
```

**Python**

```python
from dreamlake import RemoteClient

# Uses the securely saved login for this API origin.
client = RemoteClient("https://api.dreamlake.ai")
page = client.vault.tree(prefix="ge/training", limit=100)
if page["nextCursor"]:
    next_page = client.vault.tree(
        prefix="ge/training", limit=100, cursor=page["nextCursor"],
    )
```

In the terminal use arrows to select, collapse or expand, `n` for the next page,
and `q` to quit. Pages are fetched explicitly and do not form a frozen whole-tree
snapshot. JSON preserves detail truncated by terminal width. Prefixes and entries
remain distinct; governing policy/key metadata does not prove which key encrypted
historical ciphertext. Unknown policy or migration state remains unknown.
This view does not reveal values, change policies, provision credentials or preview
cross-boundary moves. `--include-deleted` is unsupported.

[Runnable tree example and local HTTP/Mongo/PTY evidence](https://github.com/dreamlake-ai/dreamlake-cli/tree/07bae34322612475a4093012375a4039f90e336d/examples/vault-tree),
[CLI artifact receipt](https://github.com/dreamlake-ai/dreamlake-cli/tree/07bae34322612475a4093012375a4039f90e336d/docs/releases/0.22.0)
and [Python archive receipt](https://github.com/fortyfive-labs/dreamlake/tree/d86e0be2cdb0d3777ed50345a548352683c29ab3/docs/releases/0.17.0)
record exact tested versions. [Python publication](https://github.com/dreamlake-ai/dreamlake-workspace/blob/87e2caf7760d9f0f6be4126fd4aced7a17f0f87e/infra/vault/production-tree-20260915/pypi-reconciliation.json) was separately verified against both frozen archives; a [fresh no-cache PyPI install and production metadata-only tree check](https://github.com/dreamlake-ai/dreamlake-workspace/blob/cc23e87431be8335c204b560cc18edae8f79534e/infra/vault/production-tree-20260915/python-public-verification.json) passed. The initial read-only install check failed without an established cause; its successful retry is recorded separately. CLI npm/native publication remains unproven.

## Save one file in the web Vault

Open your profile's **Vault** tab, choose **New entry** (or **Replace value**),
keep **String**, and choose one UTF-8 file. Selection reads that file locally.
Review its basename, byte count, destination and expiry, then explicitly save.
Manual input stays masked until **Reveal secret input**. No adjacent SSH keys,
aliases or jump-host credentials are discovered, and saving does not enroll a
host or install a remote key.

The file must be nonempty, valid UTF-8, no larger than 64 KiB, and contain no
NUL or unsupported control bytes. Its JSON-encoded value must also fit 64 KiB.
BOM, CRLF and trailing whitespace remain unchanged; revealing alone does not
rewrite them. Editing visible text uses browser newline handling. Closing,
leaving, changing accounts or canceling discards pending reads. Unknown writes
use the existing receipt recovery flow without automatically retrying uploads.
Web export/download and full remote setup review remain separate work.

[Staging and production evidence](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/infra/vault/hosted-ui-files-acceptance.md)
records desktop/mobile saving and cleanup. Equivalent explicit client operations:

**CLI**

```shell
# The selected CLI input here is UTF-8 without a BOM.
dreamlake vault add -n ge/remote-agent/key \
  --stdin --file-name id_ed25519 < ./id_ed25519
dreamlake vault show -n ge/remote-agent/key
```

**Python**

```python
from pathlib import Path

source = Path("./id_ed25519")
# read_bytes avoids newline normalization; no implicit prompt or secret logging.
entry = client.vault.add(
    name="ge/remote-agent/key",
    value=source.read_bytes().decode("utf-8"), file_name=source.name,
)
metadata = client.vault.show(name="ge/remote-agent/key")
```

## Read and compose

`list` returns metadata; `get` explicitly returns plaintext values. Python uses an authenticated `client` and never prompts automatically. Keep retrieved values out of logs and agent transcripts.

**CLI**

```shell
dreamlake vault list -p ge/training
dreamlake vault get -n ge/training/storage --to-json
dreamlake vault get -n ge/training/storage.access-key

# Compose entries using their saved environment names.
dreamlake vault -p ge/training get \
  -n ssh-key -n tracking-token --to-envs
```

**Python**

```python
entries = client.vault.list(prefix="ge/training")
storage = client.vault.get(name="ge/training/storage")
access_key = client.vault.get(name="ge/training/storage.access-key")
exports = client.vault.get(
    prefix="ge/training", name=["ssh-key", "tracking-token"], to_envs=True,
)
```

Use `path.field` for field selection and repeated `-n` for composition. `-p`/`--prefix` abbreviates paths for one invocation and can appear before or after subcommands. Leading `/` bypasses abbreviation; conflicting prefixes fail. `--to-json` and `--to-envs` are exclusive. Resolve the whole request before returning values; failures emit no partial secret output.

An entry can save output metadata:

```json
{
  "name": "ge/training/ssh-key",
  "type": "string",
  "keyName": "ssh_private_key",
  "env": "SSH_PRIVATE_KEY",
  "fileName": "id_ed25519",
  "value": "<illustrative secret; encrypted at rest>"
}
```

Ordinary secrets are strings or named string fields. `totp` adds code-generation behavior; reading a seed and generating a code are separate operations. CLI 0.16/Python 0.13 support [HOTP](/dev/plans/vault-hotp) with a compatible backend; hosted staging acceptance and production rollout are separate. `keyName` names a value in composed JSON, `env` names a single-value entry's environment variable, and `fileName` is a suggested basename for explicit file export. It never writes a file automatically.

For env output, an explicit alias such as `-n TOKEN=ge/tracking.value` wins. A selected field uses its normalized field name; a whole scalar entry uses saved `env`, then its normalized basename. Reading a whole map exports its field names, not the entry-level `env`. `--env-prefix` changes output names only. Reject invalid names/collisions rather than silently renaming them. Structured entries use field mappings, not one ambiguous entry-level env name.

## Supply values to a program

`--to-envs` emits quoted POSIX shell exports. It cannot change the parent shell itself. Check retrieval before evaluating output and use a subshell when variables should live only for the job. Do not enable shell tracing around secrets.

**CLI**

```shell
(
  exports=$(dreamlake vault get -n ge/tracking-token --to-envs) || exit
  eval "$exports"
  unset exports
  python train.py
)

# When the consumer accepts stdin; use a shell supporting pipefail.
set -o pipefail
dreamlake vault get -n ge/tracking-token | client-tool --token-stdin

# For an argv-only consumer, check lookup failure first.
token=$(dreamlake vault get -n ge/tracking-token) || exit
legacy-client --token "$token"
unset token
```

**Python**

```python
import os
import subprocess

token = client.vault.get(name="ge/tracking-token")
subprocess.run(
    ["python", "train.py"],
    env={**os.environ, "TRACKING_TOKEN": token}, check=True,
)
subprocess.run(["client-tool", "--token-stdin"], input=token, text=True, check=True)
subprocess.run(["legacy-client", "--token", token], check=True)
```

Consumer programs here are illustrative. Argv may be visible to process inspection; stdin is preferable when supported. Command substitution strips trailing newlines, so use JSON/stdin or Python for exact multiline values. A receiving process can copy or log secrets; delivery is not a secrecy boundary against that process.

## Save values and import selected TOTP entries

`add` uses a masked prompt on a TTY; noninteractive callers provide stdin explicitly. Python receives the securely collected value and never prompts. `show` returns metadata only. Host enrollment can save selected credentials; see [Enrollment](/lakeshore/hosts/enroll.md). Saving and remote key installation are separate operations.

**CLI**

```shell
# Collect a value through a masked TTY prompt, never as an argument.
dreamlake vault add -n ge/bos14-login
dreamlake vault show -n ge/bos14-login

# Preview only: use an explicit canonical store path.
dreamlake vault import --pass-otp -p ge --dry-run --store /absolute/pass-store
```

**Python**

```python
# Caller supplies securely collected secret; no implicit prompts.
client.vault.add(name="ge/bos14-login", value=secret)
metadata = client.vault.show(name="ge/bos14-login")
preview = client.vault.import_entries(
    source="pass-otp",
    store="/absolute/pass-store", prefix="ge", dry_run=True,
)
```

Preview uses noninteractive GPG and an explicit canonical store path. It decrypts locally but uploads nothing, excludes adjacent passwords, and never generates codes or advances HOTP counters. Paths must not traverse symlinks.

Choose canonical pass paths without `.gpg` from the preview. Only selected OTP registrations are uploaded; adjacent passwords are excluded. TOTP registrations can generate codes; HOTP registrations are inactive until DreamLake explicitly takes counter ownership. On a TTY, review and confirm the upload. Explicit `--select` supplies consent for noninteractive use; Python requires selection and never prompts.

**CLI**

```shell
dreamlake vault import --pass-otp -p ge --store /absolute/pass-store \
  --select accounts/example

dreamlake vault otp -n ge/accounts/example
```

**Python**

```python
result = client.vault.import_entries(
    source="pass-otp", prefix="ge", store="/absolute/pass-store",
    select=["accounts/example"],
)
code = client.vault.otp(name="ge/accounts/example")
```

OTP generation requires owner authentication; scoped keys cannot generate codes. Treat generated codes as secrets. Import does not overwrite existing OTP entries. If an upload outcome is unknown, stop and inspect it; do not blindly repeat the import.

For HOTP, stop every other generator before activation. Import is inactive by default; inspect the entry revision before activating it. The CLI example below uses revision `1` for a newly imported entry; substitute the actual inspected revision. Python uses the returned revision directly. Activation does not generate a code or update the local pass store.

**CLI**

```shell
dreamlake vault import --pass-otp -p ge --store /absolute/pass-store \
  --select accounts/hotp-example
dreamlake vault show -n ge/accounts/hotp-example
dreamlake vault otp -n ge/accounts/hotp-example \
  --activate --counter-owner dreamlake --if-match 1

mkdir -m 700 -p ./otp-requests
dreamlake vault otp -n ge/accounts/hotp-example \
  --request-file ./otp-requests/hotp-example-001.json
```

**Python**

```python
client.vault.import_entries(
    source="pass-otp", prefix="ge", store="/absolute/pass-store",
    select=["accounts/hotp-example"],
)
metadata = client.vault.show("ge/accounts/hotp-example")
client.vault.activate_otp(
    "ge/accounts/hotp-example", counter_owner="dreamlake", if_match=metadata["revision"],
)
from pathlib import Path
Path("otp-requests").mkdir(mode=0o700, exist_ok=True)
code = client.vault.otp(
    "ge/accounts/hotp-example",
    request_file="./otp-requests/hotp-example-001.json",
)
```

Run these examples in a writable, user-owned directory. The `otp-requests` directory must be private (mode 0700), including when it already exists. Each new HOTP issuance uses a new private request file. After an uncertain response, reuse the **same file** to recover that issuance; never substitute a fresh file. The durable intent contains identity and revision metadata, not the seed or code. Recovery expires after 24 hours; a missing or expired receipt does not prove that no code was issued. Initial activation supports SHA1 with at least a 128-bit seed; unsupported algorithms remain inactive. See the [HOTP ownership and recovery reference](https://cli.dreamlake.ai/vault-operations). These commands are supported by published CLI 0.20.1 and Python 0.16.1; they require the corresponding server capabilities.

<span id="ssh-sync-select-entries-before-uploading--proposed" />

<span id="ssh-sync-select-entries-before-uploading" />

### SSH import: select entries before uploading

Run from an authenticated interactive terminal:

```shell
dreamlake vault import --ssh -p ge/remote-agent
```

The checklist starts empty. Select profiles and private keys separately, then
review the server and vault destinations before confirming upload. Selecting a
profile does not select its key or jump-host entries. Empty selection or
cancellation before upload writes nothing; cancellation during upload preserves
completed entries and stops further uploads.

Preview discovery without reading private keys or contacting the vault:

```shell
dreamlake vault import --ssh -p ge/remote-agent --dry-run --json
```

For noninteractive use, pass the item IDs shown by discovery explicitly.
Python uses explicit selection and never opens a checklist:

**CLI**

```shell
dreamlake vault import --ssh -p ge/remote-agent \
  --select profile:dev-box --select key:dev-box:1 --json
```

**Python**

```python
preview = client.vault.import_entries(source="ssh", prefix="ge/remote-agent", dry_run=True)
result = client.vault.import_entries(
    source="ssh", prefix="ge/remote-agent",
    select=["profile:dev-box", "key:dev-box:1"],
)
```

Use `--config` for a specific SSH config file. Discovery does not expand `Include`
files. Compatibility aliases remain `vault ssh sync` and `vault pass sync --otp`.

Unknown writes are reconciled only within the same bounded retry call. Do not blindly start a new import after an unknown outcome.

Host enrollment and explicit password saving are available in the published clients; see the [enrollment guide](/lakeshore/hosts/enroll.md). Remote password mutation, rollback and destination revocation require separate acceptance; a saved credential or a revoked Vault key does not prove access was removed from the remote host. Enrollment must succeed independently of saving; interactive saving defaults to `[y/N]`, and quiet mode never grants consent.

## Access keys and retirement

Access keys authenticate scripts to selected vault entries; they are not SSH credentials or agent objects. Reuse appropriate keys instead of creating permanent entries per worker. Renewal is policy-checked, and one-time means one atomic successful retrieval request. Expired/revoked keys cannot renew themselves; one-time keys are nonrenewable.

**CLI**

```shell
dreamlake vault keys create -n ge/training/storage --ttl 1h --renewable \
  --request-id training-key-1 --token-file ./training-vault.key
dreamlake vault keys create -n ge/bootstrap --ttl 10m --one-time \
  --request-id bootstrap-key-1 --token-file ./bootstrap-vault.key

dreamlake vault delete -n ge/bos14-login
dreamlake vault restore -n ge/bos14-login
```

**Python**

```python
# Results redact bearer material in repr; provision .token securely once.
key = client.vault.keys.create(name="ge/training/storage", ttl="1h", renewable=True,
    request_id="training-key-1")
once = client.vault.keys.create(name="ge/bootstrap", ttl="10m", one_time=True,
    request_id="bootstrap-key-1")
client.vault.delete(name="ge/bos14-login")
client.vault.restore(name="ge/bos14-login")
```

Token files must be new and are created with mode 0600. Retain the request ID when retrying uncertain issuance: replay returns metadata without re-revealing the token. Revoke and replace a key whose token was lost. Public GC commands and remote `destroy` remain proposed.

Deletion sets `deleteAt`, blocks new reads, and retains encrypted data until `purgeAt`. Restore during retention does not renew expiry or reinstall a revoked host key. Internal purge rechecks lifecycle state before hard deletion. Scheduled cleanup of terminal access-key metadata is deployed; it does not purge entry ciphertext or revoke remote host access. Scheduled entry/binding cleanup has [isolated EKS acceptance](https://github.com/dreamlake-ai/lakeshore-examples/pull/38). The [hosted retention fixture](https://github.com/dreamlake-ai/lakeshore-examples/pull/47) retains its captured October 15 deadlines; hosted physical purge and backup coverage remain unproven. Intentionally unbound entries are not garbage.

Keep four lifetimes distinct: host access, vault availability, account/client cache, and retained storage. Vault expiry cannot invalidate a copied static password. Rotate by verifying new access before retiring old access. The proposed future `destroy` flow would combine remote revocation with soft retirement and later purge, keeping unreachable hosts pending; it is not an available command. Never claim deletion recalls downloaded secrets or ends existing SSH sessions.

## Web management and uncertain writes

In the personal Vault page, create or replace entries, reveal/hide values, set or
remove UTC expiry, and confirm retirement or restore. Scoped-key controls support
selected-field issuance, renewal and confirmed revocation. Revealed entry values
clear after 30 seconds or at expiry, whichever is first. Expiry does not retire
an entry or revoke a copied remote credential.

If a create/replacement response is lost, **Entry write recovery** retains the
request ID across reload. **Check result** reads the historical receipt;
**Open current entry metadata** shows later changes separately. Forgetting an ID
only removes the browser reference. A missing receipt does not prove a write
failed. CLI/Python can look up a retained request ID without revealing values:

**CLI**

```shell
dreamlake vault write-status --request-id saved-write-id
```

**Python**

```python
receipt = client.vault.write_status(request_id="saved-write-id")
```

Use the original ID from the uncertain write. Do not start a new write to test
whether the old one committed. See [recovery behavior and hosted evidence](/dev/notes/vault-runtime#2026-09-13--entry-write-recovery).

## Prefix policies and agent behavior

Prefix KMS management and migration have implementation and bounded live cloud evidence; see the [Prefix KMS note](/dev/notes/vault-prefix-kms) for verified scope and remaining hosted/operator acceptance, and the [operator setup reference](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/design/rfcs/vault-cloud-setup.md). Ordinary hosted users use managed KMS without cloud setup.

When using this guide as a skill, check installed capabilities and the target endpoint first. Keep secrets out of transcripts. Report provisioning, login verification, enrollment, saving and remote cleanup separately; do not infer credential export or removal of existing access from a setup request. Report unsupported operations rather than simulating them with plaintext files.

---

Source: https://docs.dreamlake.ai/lakeshore/hosts/remote-agent-environment

# Setting Up Remote Agent Environment

Set up a remote machine for development or a coding agent. You will need SSH
access, Git access to the repository, and the runtime versions specified by the
project.

The examples use `dev-box` as the SSH alias and `alice` as the DreamLake account.
Replace both with your own values.

## Connect to the machine

Run on your local machine:

```shell
ssh dev-box
```

For provisioning and network/key prerequisites, see [Resource setup](/lakeshore/providers/resource-setup.md).

## Prepare a checkout

Run on the remote machine. This example creates a separate DreamLake CLI checkout
and checks out a specific commit. Replace the revision before running it.

```shell
bash <<'SH'
set -eu
TASK_REVISION='REPLACE_WITH_FULL_COMMIT_SHA'
case "$TASK_REVISION" in
  REPLACE_*) printf '%s\n' 'Set TASK_REVISION first'; exit 1 ;;
esac

mkdir -p "$HOME/workspaces"
TASK_DIR=$(mktemp -d "$HOME/workspaces/dreamlake-cli-task.XXXXXX")
git clone https://github.com/dreamlake-ai/dreamlake-cli.git "$TASK_DIR"
cd "$TASK_DIR"
git switch --detach "$TASK_REVISION"
git switch -c work/remote-dev
printf 'Checkout: %s\n' "$TASK_DIR"
git rev-parse HEAD
SH
```

Use the printed checkout path as the working directory for your editor or agent.
Each concurrent task should have its own checkout and branch.

Install the Node and pnpm versions specified by the checkout, then run from that
directory:

```shell
bash <<'SH'
set -eu
node --version
pnpm --version
pnpm install --frozen-lockfile
pnpm run build
pnpm test
SH
```

## Configure access

Set up the services your project uses on the remote machine.

| Service | Local configuration | Remote setup |
| --- | --- | --- |
| DreamLake | `~/.dreamlake/` | Run `dreamlake login`. |
| Application or integration tests | `.env`, `.env.test` | Create from the project's example file and supply the required values. |
| SSH | `~/.ssh/config`, selected keys | Add the required host entries and keys. |
| AWS | `~/.aws/config`, credentials or SSO session | Configure the required profile and log in. |
| Google Cloud | gcloud configuration and application credentials | Authenticate the remote account or provision its service identity. |
| Kubernetes | kubeconfig | Install the required cluster context. |
| GitHub, npm, Docker | CLI login and registry configuration | Log in on the remote machine. |

Desktop keychain credentials and hardware-backed keys require remote login or a
separate remote credential. For existing deployments, retain the encryption keys
needed to read stored data and use the authoritative Terraform state/backend.

## Upload configuration files to the vault

Use a CLI version with vault support and a vault-enabled server. See
[#241](https://github.com/dreamlake-ai/dreamlake-workspace/issues/241) for release
and deployment status.

Run on the local machine:

```shell
dreamlake login
dreamlake vault add --help

# Application configuration.
dreamlake vault add -n alice/remote-agent/app-env \
  --stdin --file-name .env < ./service/.env

# A selected SSH private key.
dreamlake vault add -n alice/remote-agent/ssh-key \
  --stdin --file-name id_ed25519 < "$HOME/.ssh/remote_agent_ed25519"

# A selected cluster configuration.
dreamlake vault add -n alice/remote-agent/kubeconfig \
  --stdin --file-name config < ./selected-cluster.kubeconfig

dreamlake vault list -p alice/remote-agent
dreamlake vault show -n alice/remote-agent/app-env
```

Run only the uploads you need. `--stdin` preserves UTF-8 text and trailing
newlines; the JSON-encoded value is limited to 64 KiB. `--file-name` records a
suggested filename. To replace an existing entry, inspect its revision with
`show` and pass that revision with `--if-match`.

`dreamlake upload` is for episode assets. Use `dreamlake vault add` for secrets.

<span id="select-ssh-entries-to-sync" />

## Select SSH entries to import

Selected SSH import is available in the released clients. See the [credential guide](/lakeshore/hosts/credentials.md) for supported versions, CLI/Python usage and current limitations.

Run in an authenticated interactive terminal on your local machine:

```shell
dreamlake vault import --ssh -p alice/remote-agent
```

The checklist starts with no entries selected. Profiles and private keys are
separate items:

```text
Select SSH entries to upload

[ ] dev-box profile       dev@dev.example.com
[ ] dev-box private key   ~/.ssh/dev_box
[ ] bastion profile       dev@jump.example.com
[ ] bastion private key   ~/.ssh/bastion

Space: select    Enter: review selected    Esc: cancel
```

Select the entries you want, review their vault destinations, and upload the
selection. Only checked entries are uploaded. An empty selection or cancellation
before upload writes nothing. Private keys and jump-host entries require their
own selection.

To inspect discovered items without reading private keys or contacting the vault:

```shell
dreamlake vault import --ssh -p alice/remote-agent --dry-run --json
```

See [SSH import](/lakeshore/hosts/credentials.md#ssh-sync-select-entries-before-uploading)
for the selection and retry behavior.

## Restore a file remotely

Log in on the remote machine:

```shell
dreamlake login
```

From your application checkout, restore the saved environment file to
`service/.env`. The `service` directory must already exist. This example creates
a mode-0600 file and fails if the destination exists or retrieval fails.

```shell
python3 - <<'PYTHON'
import json
import os
from pathlib import Path
import subprocess

destination = Path("service/.env")
if not destination.parent.is_dir():
    raise SystemExit("Create the service checkout first")
result = subprocess.run(
    ["dreamlake", "vault", "get", "-n", "alice/remote-agent/app-env", "--to-json"],
    stdout=subprocess.PIPE, stderr=subprocess.PIPE,
)
if result.returncode:
    raise SystemExit("Vault retrieval failed")
value = json.loads(result.stdout)
if not isinstance(value, str):
    raise SystemExit("Expected a text-file entry")
fd = os.open(destination, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "wb") as output:
    output.write(value.encode("utf-8"))
print("Created service/.env")
PYTHON
```

Change the entry name and destination for other files. Use mode `0700` for SSH
and credential directories. For individual environment variables, see
[Environment exports](/lakeshore/hosts/credentials.md#supply-values-to-a-program).

## Run development tools or an agent

Start your editor or coding agent in the remote checkout under the account that
owns the configuration files. Use the project's commands to start the service
and run its checks. Applications that read `.env` files must use the configured
file location; other programs need the variables exported into their process
environment.

The DreamLake CLI development example uses `pnpm run build` and `pnpm test`.
Application integration tests may additionally need the configuration restored
above. Set up remote agent authentication separately if your agent requires it.

## Check the setup

- Confirm the checkout revision with `git rev-parse HEAD`.
- Run the project's build and tests from the remote account.
- Check required configuration files exist and have the intended permissions.
- Verify access to each required API, registry or cluster with a read-only call.
- Verify SSH access with a fresh connection.

Keep secret values out of terminal output and logs. If a check fails, fix its
reported dependency, configuration or authentication error and rerun that check.

---

Source: https://docs.dreamlake.ai/lakeshore/hosts/testing

# Test hosts and tracked runs

Tracked-run submission, status, logs and cancellation have shipped since CLI 0.13.0 and Python 0.10.0. Use Python 0.16.2 or later for the noninteractive ProxyJump fix. Use an explicitly selected test host and compatible server. A running public control plane does not imply the main server has host/run APIs or current schema. Do not point these tests at production by default. [Enrollment](/lakeshore/hosts/enroll.md) explains the implementation and delivery boundaries.

For the commands below, use released **CLI 0.21.2**, **Python 0.16.2** and **Nymph 0.1.8**. The [CLI publication receipt](https://github.com/dreamlake-ai/dreamlake-cli/pull/90) covers native/npm latest; the stable channel remains 0.21.0. The [Nymph release receipt](https://github.com/dreamlake-ai/nymph/pull/55#issuecomment-5680230392) includes exact checksums and a scratch-install command; all public artifacts match the reviewed manifest. These version pins do not upgrade an existing host or prove hosted recovery. Dated receipts below retain the versions actually tested.

## Python SSH authentication checks

Install the published SDK in a fresh environment:

```shell
uv venv .venv-host-check
uv pip install --python .venv-host-check/bin/python --no-cache dreamlake==0.16.2
.venv-host-check/bin/python -c 'import importlib.metadata; print(importlib.metadata.version("dreamlake"))'
```

Expect `0.16.2`. Python requires noninteractive key or agent access for both target and jump host; password-only access must fail without a terminal or GUI prompt. The CLI continues to support interactive password authentication.

For repeatable transport acceptance, use the [tag-pinned SDK procedure](https://github.com/fortyfive-labs/dreamlake/blob/v0.16.2/scripts/HOST_NONINTERACTIVE_SSH.md) and [committed OpenSSH fixture](https://github.com/dreamlake-ai/dreamlake-cli/pull/72). The fixture checks direct/jump passwords in the CLI, SDK no-prompt rejection, and key/agent success. It creates temporary loopback SSH servers and cleans them; systemd is stubbed, so this is not machine enrollment or reboot proof. Remove only the disposable `.venv-host-check` when finished.

Open [staging run 6aa90495100be79cea5a92bf](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa90495100be79cea5a92bf), verified in the signed-in browser. It separately records a real process through published Python 0.16.2: `succeeded`, exit 0, stdout `DreamLake Python 0.16.2 live acceptance`. Use an authorized staging account to review the existing record; no resubmission is needed. [Evidence and remaining scope](/dev/notes/host-enrollment).

## Real SSH enrollment

Choose an authorized disposable Linux account with SSH access, Python 3, OpenSSL, and a user systemd manager with administrator-enabled linger. If nymph is absent, enrollment downloads the requested version into the account’s local bin directory. Provide uv separately in the user service environment before testing tracked runs. Configure your client for the intended main server and account. The target must reach its configured control plane. Check SSH before starting; Python requires noninteractive key/agent authentication.

**CLI**

```shell
ssh test-host true
dreamlake hosts enroll -p ge/testing -n test-host --ssh test-host \
  --request-id manual-host-test --nymph-version v0.1.8
dreamlake hosts status ge/testing/test-host
```

**Python**

```python
from dreamlake import DreamLakeClient
client = DreamLakeClient()
result = client.hosts.enroll(
    "ge/testing/test-host", ssh="test-host", request_id="manual-host-test",
    nymph_version="v0.1.8",
)
assert result["status"] == "online"
print(client.hosts.status("ge/testing/test-host"))
```

Repeat the identical request while its receipt is valid: host/enrollment IDs must stay stable. Inspect the generated `dreamlake-host-*.service` in the target user's `~/.config/systemd/user`; restart that exact test service and verify a new heartbeat with the same identity. Test reboot recovery separately. A heartbeat proves connectivity, not successful execution. Cleanup stops only that exact disposable service; do not disable a shared cluster daemon or delete another user's identity.

The [published installer acceptance procedure](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/infra/hosts/installer-acceptance.md)
checks fresh CLI and Python bootstrap paths on separate accounts, installed binary
hashes, mode-0600 files, stable replay and a new signed heartbeat after removing
the bootstrap token. Require a successful tracked run as well. Service restart
does not establish machine reboot recovery.

## Run a small script

The selected host must advertise tracked-run and uv capability. Create `hello.py` containing `print("hello from the remote host")`; keep it outside Git to check explicit source staging. Replace the example namespace/host with your authorized target.

**CLI**

```shell
dreamlake run --target ge/testing/test-host --include hello.py \
  --request-id manual-run-test --uv-run --no-project hello.py
dreamlake runs status "ge/$RUN_ID" --json
dreamlake runs logs "ge/$RUN_ID" --json
```

**Python**

```python
run = client.runs.submit(
    "ge/testing/test-host", kind="uv-run", argv=["--no-project", "hello.py"],
    include=["hello.py"], request_id="manual-run-test",
)
result = client.runs.wait("ge", run["id"], timeout_seconds=60)
assert result["status"] == "succeeded" and result["exitCode"] == 0
page = client.runs.logs("ge", run["id"])
```

Expect the printed remote output, a durable run ID, `succeeded`, and exit code0. No files beyond explicit inclusions are uploaded; source limits are100 files and1MiB total. Everything after `--uv-run` or `--uvx` belongs to the workload. Log pages contain base64 bytes for separate stdout/stderr streams; follow `nextCursor` until `done`, using an incremental decoder if rendering text.

For cancellation, submit a script that sleeps using CLI `--no-wait` or Python `submit`, then call `dreamlake runs cancel "ge/$RUN_ID"` or `client.runs.cancel("ge", run_id)`. Poll until `cancelled`; `cancel_requested` alone is insufficient. A failed script should return its nonzero exit code. Local wait timeout does not cancel remote work.

## Inspect recovery without submitting again

Set `RUN_ID` to your original run ID and replace `ge` with its namespace. Keep that ID after a connection loss or worker restart. Read it again; do not repeat submission with a new request ID. On a compatible server, `recoveryObservation` explains why an admitted run is still uncertain. It is not a terminal result or proof that the process stopped. A genuine completed result clears the observation. A local wait timeout does not cancel the remote run.

**CLI**

```shell
dreamlake runs status "ge/$RUN_ID" --json
dreamlake runs logs "ge/$RUN_ID"
```

**Python**

```python
run = client.runs.status("ge", run_id)
print(run["status"], run.get("recoveryObservation"))
```

Open the same run-detail URL in the UI and refresh. When the server reports recovery uncertainty, the warning must remain after reload; only an authoritative terminal result clears it. Do not infer a cancellation from `cancel_requested` alone.

**[Full recovery acceptance](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/dreamlake-server/docs/recovery-chain-acceptance.md)** — A runnable isolated test connects real API, control plane, Nymph, CLI, Python and browser. It checks one launch total across daemon crash/restart and warning removal after replaying a retained genuine result, with screenshots and cleanup. Its storage rollback case is an explicit fault injection. Run it on disposable local fixtures, not an enrolled shared host; it does not establish hosted recovery deployment.

## Review the hosted recovery record

Open [production run 6aa93b7ab30c4066ffc61361](https://dreamlake.ai/geyang/tracked-runs/6aa93b7ab30c4066ffc61361) using the authorized `geyang` account. Published Nymph **0.1.8**, CLI **0.21.2** and Python **0.16.2** observed one launch across an owned daemon SIGKILL and systemd restart. The UI retained stdout and the **Reconciliation required** warning after a full reload. The stored status is `running` with no exit code; it does not mean the interrupted payload is still alive.

Read the existing record without submitting or cancelling anything:

**CLI**

```shell
dreamlake runs status geyang/6aa93b7ab30c4066ffc61361 --json
dreamlake runs logs geyang/6aa93b7ab30c4066ffc61361
```

**Python**

```python
from dreamlake import DreamLakeClient
client = DreamLakeClient()
run = client.runs.status("geyang", "6aa93b7ab30c4066ffc61361")
print(run["status"], run.get("recoveryObservation"))
```

Expect `reconciliation_required` / `prior_boot_admission`, observed at `2026-09-15T12:35:44.499Z`, with retained logs. No authentic terminal result survived this hosted interruption, so warning clearing is established by the isolated full-chain test above, not this run. Do not resubmit to resolve uncertainty. The [sanitized hosted receipt and read-only verifier](https://github.com/dreamlake-ai/dreamlake-workspace/tree/main/infra/hosts/recovery) record one marker after the deadline, no remaining payload process, unchanged other daemons and removal of the temporary SSH rule. A separate intentional [post-restart hello](https://dreamlake.ai/geyang/tracked-runs/6aa93c1ab30c4066ffc61364) succeeded; it does not resolve the original run.

## Check published clients on an enrolled test host

Use [published-client-acceptance.py](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/infra/hosts/published-client-acceptance.py)
from a workspace checkout. This test submits eight short synthetic runs to the
exact host you name. It does not enroll or restart a worker. It checks explicit
file selection, unchanged arguments, stable replay, log cursors, failure exit 7,
remote timeout and confirmed cancellation. Only its own runs may be cancelled;
durable run records remain afterward.

Install the released clients in a temporary directory:

```shell
test_dir=$(mktemp -d)
npm install --prefix "$test_dir/cli" @dreamlake/dreamlake-cli@0.21.2
uv venv "$test_dir/python"
uv pip install --python "$test_dir/python/bin/python" dreamlake==0.16.2
```

Create a protected `host-test-session.json` containing `remote` (the HTTPS main
API URL), `namespace` and your test account's `token`. Keep it outside your checkout
and out of shell history. Then run:

```shell
"$test_dir/python/bin/python" infra/hosts/published-client-acceptance.py \
  --session-file /absolute/path/to/host-test-session.json \
  --target ge/testing/test-host \
  --cli "$test_dir/cli/node_modules/.bin/dreamlake" \
  --output "$test_dir/acceptance.json"
```

Require `passed: true`, `cleanup: true` and terminal states for all eight recorded
run IDs. A local timeout is not proof the remote task stopped; inspect the recorded
IDs before retrying. This checks an existing process worker. It does not verify
fresh enrollment, installer/reboot recovery, Slurm/GPU execution or production
readiness.

## Repeatable isolated acceptance

The committed harnesses use real main HTTP/JWT routes, disposable persistent MongoDB, a signature-required control plane, the actual nymph binary, and uv. Only SSH/systemd transport is adapted locally; they do not prove Linux supervision or real remote SSH. Their fixture setup and protected credentials are separate from production configuration.

- **[Backend fixture setup](https://github.com/dreamlake-ai/dreamlake-workspace/blob/feat/218-tracked-runs/dreamlake-server/src/runs/README.md)** — Operator prerequisites and acceptance commands from [backend PR #281](https://github.com/dreamlake-ai/dreamlake-workspace/pull/281). A public endpoint does not establish that rollout; use a configured disposable test server.
- **[CLI acceptance script](https://github.com/dreamlake-ai/dreamlake-cli/blob/main/scripts/test-runs-integration.mjs)** — Builds a disposable worker and checks explicit source, argument vectors, logs, replay, failure, uvx, timeout, cancellation, and denied access.
- **[Python acceptance script](https://github.com/fortyfive-labs/dreamlake/blob/main/scripts/test_runs_integration.py)** — Equivalent actual-service tests; local adapters and cleanup are committed with the script.

Build nymph from the tested source and ensure `uv`, Python 3, and OpenSSL are available. Obtain a test namespace, its Lakeshore connection ID, a member token allowed to enroll/run, and an outsider token from the test server's operator. Create your own protected configuration; no coordinator temporary files are required:

```shell
python3 - <<'PY'
import getpass, json, os
config = {
    "remote": input("Isolated loopback main-server URL: ").rstrip("/"),
    "namespace": input("Test namespace: "),
    "lakeshoreId": input("Test Lakeshore connection ID: "),
    "token": getpass.getpass("Test member token: "),
    "outsiderToken": getpass.getpass("Test outsider token: "),
}
with os.fdopen(os.open("run-test-env.json", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w") as file:
    json.dump(config, file)
PY
```

Run from each corresponding repository. These examples require an isolated loopback API; the drivers do not create database infrastructure or obtain account credentials:

**CLI**

```shell
pnpm install --frozen-lockfile
pnpm build
node scripts/test-runs-integration.mjs run-test-env.json /path/to/nymph
```

**Python**

```shell
uv sync --extra dev --extra dreamdb
uv run python scripts/test_runs_integration.py \
  --env-file run-test-env.json --nymph /path/to/nymph
```

Expect a JSON success summary and a zero exit status; first use can take several minutes, including package access/cache for the Ruff uvx check. The harnesses stop their disposable nymph services and remove temporary source/identity files; records remain in the disposable databases for inspection. Stop the fixture processes and remove only their dedicated database directories after review. A failed or interrupted run requires checking for remaining test services before cleanup. Delete your `run-test-env.json` afterward; never print it or pass bearer tokens as command-line arguments.

## Production control-host review

On September 15, released Python **0.16.2**, CLI **0.20.1** and nymph **0.1.6** passed no-save enrollment and process execution on [geyang/bos14/bos14-ctrl](https://dreamlake.ai/geyang/compute/hosts/6aa9095356dcd24e450ec814). The host reconnected with the same identity; three existing bos14 daemons retained their PIDs and configuration. The signed-in browser verified the host heartbeat, SDK success with both streams, and terminal cancellation. These are production control-host diagnostics, not Slurm allocation or a production-machine reboot. Use the authorized **production** account; staging credentials and namespace differ.

| Review record | Expected result |
| --- | --- |
| [Python hello](https://dreamlake.ai/geyang/tracked-runs/6aa9096056dcd24e450ec816) | `succeeded`, exit `0`, hostname/user and separate stdout/stderr |
| [CLI hello](https://dreamlake.ai/geyang/tracked-runs/6aa9096c56dcd24e450ec817) | `succeeded`, exit `0` |
| [Cancellation](https://dreamlake.ai/geyang/tracked-runs/6aa9097d56dcd24e450ec818) | `cancelled`, exit `-3`, terminal action disabled |
| [Intentional failure](https://dreamlake.ai/geyang/tracked-runs/6aa90d2856dcd24e450ec83c) | `failed`, exit `7`, expected stdout/stderr |
| [Bounded timeout](https://dreamlake.ai/geyang/tracked-runs/6aa90d3856dcd24e450ec841) | `timed_out`, exit `-2`, expected stdout |

Review the retained records without submitting new work. With the production client environment already configured:

```shell
npm exec --yes --package=@dreamlake/dreamlake-cli@0.20.1 -- dreamlake runs \
  status geyang/6aa9096056dcd24e450ec816 --json
npm exec --yes --package=@dreamlake/dreamlake-cli@0.20.1 -- dreamlake runs \
  logs geyang/6aa9096056dcd24e450ec816 --json
```

The failure and timeout were also verified in the signed-in production browser.
Their [sanitized receipts](https://github.com/dreamlake-ai/dreamlake-workspace/tree/main/infra/hosts/evidence)
and [replayable scripts](https://github.com/dreamlake-ai/dreamlake-workspace/tree/main/examples/host-run-demo)
retain the exact payloads. To deliberately create a new pair of bounded runs,
set `DREAMLAKE_REMOTE=https://api.dreamlake.ai`, provide `DREAMLAKE_API_KEY` through
your secure local environment, and run from `examples/host-run-demo`:

```shell
uv run --no-project --with dreamlake==0.16.2 python check_outcomes.py \
  geyang/bos14/bos14-ctrl --enrollment-id 6aa9095356dcd24e450ec815 \
  --request-prefix YOUR_UNIQUE_REVIEW_PREFIX
```

Only the selected payload is uploaded. The failure intentionally exits `7`; the
12-second sleep has a 3-second remote limit and must report `timed_out`, not just
any failure. The verifier requires those exact statuses and diagnostic output.
A local wait timeout does not cancel remote work; inspect its printed run ID.

For **machine reboot** acceptance, the [separate disposable-EC2 procedure and evidence](https://github.com/dreamlake-ai/dreamlake-workspace/tree/main/infra/hosts/reboot) prove a changed boot ID, unchanged identity, no bootstrap grant, a fresh signed heartbeat and successful hello. The subsequently strengthened heartbeat/cleanup guards have offline tests; that stronger script revision was not rerun on another billable VM. Do not equate this isolated reboot with rebooting the retained production host. Ge review remains pending.

## bos14 control-host acceptance

On September 15, 2026, released Python SDK **0.16.2** and CLI **0.20.1** both ran
an explicitly uploaded `hello.py` on
[ge-yang-d4c5da/bos14/bos14-ctrl](https://staging.dreamlake.ai/ge-yang-d4c5da/compute/hosts/6aa905731a2141d8f981ba84).
Both receipts show `succeeded`, exit `0`, hostname
`bos14-ctrl-000.bos14.internal`, Unix user `geyang`, and separate stdout/stderr.
These are small process diagnostics on the control host, not Slurm allocation
or compute-node acceptance. Login with an account authorized for the staging
namespace to inspect the records.

| Client/check | Retained receipt |
| --- | --- |
| Python 0.16.2 hello | [6aa905991a2141d8f981ba86](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa905991a2141d8f981ba86) |
| CLI 0.20.1 hello, followed by status and logs | [6aa905e71a2141d8f981ba87](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa905e71a2141d8f981ba87) |
| Python cancellation after observing a bounded sleep running | [6aa9061e1a2141d8f981ba88](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa9061e1a2141d8f981ba88): `cancelled`, exit `-3` |

### Reproduce the bounded hello

Use the [example scripts](https://github.com/dreamlake-ai/dreamlake-workspace/tree/main/examples/host-run-demo).
Set `DREAMLAKE_REMOTE=https://staging-api.dreamlake.ai` and supply
`DREAMLAKE_API_KEY` through your existing secure local environment; do not put
the token in a command argument. From `examples/host-run-demo`, the following
uses temporary client packages without changing a global installation. Choose
a fresh request ID for a new run and reuse it only to retry that same operation.

```shell
TARGET=ge-yang-d4c5da/bos14/bos14-ctrl
ENROLLMENT=6aa905731a2141d8f981ba85

uv run --no-project --with dreamlake==0.16.2 python check_hello.py "$TARGET" \
  --enrollment-id "$ENROLLMENT" --request-id YOUR_UNIQUE_PYTHON_REQUEST

npm exec --yes --package=@dreamlake/dreamlake-cli@0.20.1 -- dreamlake run \
  --target "$TARGET" --enrollment-id "$ENROLLMENT" \
  --request-id YOUR_UNIQUE_CLI_REQUEST --timeout-seconds 30 --include hello.py \
  --json --uv-run --offline --no-project hello.py

# Substitute the returned run ID.
npm exec --yes --package=@dreamlake/dreamlake-cli@0.20.1 -- dreamlake runs \
  status ge-yang-d4c5da/RUN_ID --json
npm exec --yes --package=@dreamlake/dreamlake-cli@0.20.1 -- dreamlake runs \
  logs ge-yang-d4c5da/RUN_ID --json
```

### Preserve existing services during enrollment

The dedicated enrollment used `ssh="bos14-ctrl"`, `save_credentials=False`,
nymph `0.1.6`, and the existing execution-capable Lakeshore connection
`6aa64f45bb6b4dd839157e21`. Queue-only mounts cannot enroll hosts or execute
tracked runs. Its per-host identity and systemd unit are separate from the
existing `bos14-nymph.service` Slurm daemon and Vault workstream host. Baseline
and post-run comparisons confirmed those services' PIDs, unit/config hashes,
and the shared nymph binary hash stayed unchanged.

The account's Snap `uv` was broken. This enrollment therefore uses a private
copy of nymph and checksum-verified uv **0.8.15** in its own host-state `bin`
directory. A drop-in for only its generated `dreamlake-host-*.service` overrides
`ExecStart` to that private nymph and prepends that private `bin` to `PATH`.
This survives regenerated unit files without changing the global PATH or other
daemons. On another host, derive the exact unit and state directory from that
host's enrollment; do not copy bos14's identity files or restart a shared unit.
Python 3, OpenSSL, a working user systemd manager, and linger were verified.
Restart and fresh-heartbeat checks passed; machine reboot recovery remains a
separate check. The retained host's current online state must be checked live.

## Review the live host UI

Compute is available on **production** in your authorized namespace. The historical execution examples below use **staging** and the account authorized for `ge-yang-d4c5da`. Production and staging have separate login/namespace contexts. The links do not grant access. The examples exercise host inspection and run monitoring; browser-based SSH enrollment, run submission, and a server-backed run list are separate work.

### Compute

**Production migration:** [frontend PR #310](https://github.com/dreamlake-ai/dreamlake-ai/pull/310) is deployed. Legacy list and detail URLs redirect to Compute while preserving the host ID and query string. The staging Compute links below require a separate rollout; until then its earlier `/:namespace/hosts` view remains available.

Open [production Compute](https://dreamlake.ai/geyang/compute), replacing `geyang` with your namespace. After the corresponding staging rollout, use [staging Compute](https://staging.dreamlake.ai/ge-yang-d4c5da/compute) for the demo inventory. Search host paths, IDs, machine IDs or status. Plain text matches substrings; `*` matches any text and `?` one character. For example, `ge-yang-d4c5da/demo/*` selects a group and `offline` finds offline hosts. The eyebrow shows the shared parent prefix of the matching hosts.

The UI loads all API pages into one scrollable list; there are no page controls. Inventory refreshes every ten seconds while the tab is visible, with a manual Refresh action. Open a host to inspect its Unix-user enrollments, machine IDs, verification state and last heartbeat. `Online` confirms a verified Nymph heartbeat; it does not prove uv capability, workload readiness or SSH availability. **Enroll host** opens the existing CLI/SSH handoff. **Tracked runs** opens run lookup; browser SSH and run submission remain separate work.

The [demo host](https://staging.dreamlake.ai/ge-yang-d4c5da/compute/hosts/6aa64f90bb6b4dd839157e22), `ge-yang-d4c5da/demo/dev-runner`, uses a dedicated Linux account and the public development control plane. It does not depend on a laptop tunnel. Its online state is time-dependent; check the current heartbeat.

### Tracked runs

Open [staging tracked-run lookup](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs), then enter a run ID from the CLI. The detail page shows persisted status, target identity, logs, result, and exit code. A failed request must not be presented as a successful run or confirmed cancellation.

These records came from real SSH, systemd, and nymph execution on the demo host:

| Record | Expected result |
| --- | --- |
| [Success](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa65466b3f4c46e7de717da) | `succeeded`, exit `0`, short stdout/stderr |
| [Failure](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa65476b3f4c46e7de717db) | `failed`, exit `7` |
| [Cancelled](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa65488b3f4c46e7de717dc) | `cancelled`, exit `-3` |
| [Bounded heartbeat](https://staging.dreamlake.ai/ge-yang-d4c5da/tracked-runs/6aa654a5b3f4c46e7de717dd) | Running during the review window; ends around September 13, 2026, 08:46 UTC, with logs retained |

The heartbeat is time-limited. A later terminal state is expected; use a fresh authorized disposable run to test active cancellation.

### Verified screenshots

Captured from staging on September 13, 2026, using the earlier Hosts view. These are historical execution receipts, not screenshots of Compute or a promise that the demo host remains online. New Compute review screenshots in PR #310 use synthetic data.

![Demo host with a verified online nymph heartbeat](/images/hosts/live-host.png)

![Successful run with exit zero and separate stdout and stderr](/images/hosts/live-success.png)

[Failure screenshot](/images/hosts/live-failure.png) · [Cancelled screenshot](/images/hosts/live-cancelled.png)

### How to test

1. Open Compute, search a group prefix with `*`, and open a host detail page. Confirm the URL identifies the same host after reload.
2. Open a known successful run. Confirm its terminal status, exit code, and stdout/stderr; reload and verify the same server record and output.
3. Inspect a failed run. Confirm its failure reason or nonzero exit code remains visible.
4. For an authorized disposable running job, request cancellation once. Distinguish “Requesting cancellation” from the server's `cancel_requested`, then wait for a terminal result. Do not cancel another user's workload.
5. On a temporary connection failure, verify stale/error handling and recovery without resubmitting work. Signing out or changing accounts must not retain the prior account's data.

The [committed demo scripts](https://github.com/dreamlake-ai/dreamlake-workspace/tree/main/examples/host-run-demo) produce small success, failure, and cancellation workloads. For repeatable source-based checks, use [Test hosts and tracked runs](/lakeshore/hosts/testing.md) and its committed manual scripts. See the [basic UI design](/dev/plans/host-run-ui) for the deliberately limited first slice.

---

Source: https://docs.dreamlake.ai/lakeshore/access

# Declaring access

**`[ draft ]`** — none of these fields exist yet. `udf()` takes exactly `fn`,
`queue`, and `transport`, and nothing enforces what a body reads or writes. See
[Providers](/lakeshore/providers.md) for what the marker means.

  A [scope](/lakeshore/patterns.md) sets *where* keys resolve. It does not say
  *what* a function may reach. These three fields do — as paths **relative to
  the workdir**, the same coordinate system the body already writes in.

## The three fields

```python file="access.py"
@dls.udf(
    queue="gpu",
    source=["raw/**"],          # may read, relative to workdir
    target=["frames/**"],     # may write, relative to workdir
    mounts=["raw-video"],        # filesystems to attach, by name
)
def encode(src: str) -> dict[str, str]:
    ...
```

| Field | Grants | Names |
| --- | --- | --- |
| `source` | Read | A key pattern, relative to the workdir |
| `target` | Write | A key pattern, relative to the workdir |
| `mounts` | Attach | A [Mount](/lakeshore/mounts.md) by name — a resource, not a path |

### Relative to the workdir, not absolute

This is the part worth getting right. `source` and `target` are **not**
[Source](/lakeshore/dreamdb.md) identifiers. They are patterns in the same
coordinate system the body already uses:

```python
@dls.udf(queue="gpu", source=["raw/**"], target=["frames/**"])
def encode(src: str) -> dict[str, str]:
    data = dls.run.read(f"raw/{src}")           # matches source=
    out  = dls.run.write("frames/final.png")    # matches target=
    ...
    return {"frame": "frames/final.png"}
```

The declaration and the body are the same strings. Nothing has to be resolved or
translated to check one against the other, and the returned-key contract — which
already holds every key the body wrote, relative — can compare them directly.

The **scope supplies the absolute half** at invocation — see
[Specifying the prefix](#specifying-the-prefix) below. The declaration only
constrains the shape inside it. Two consequences follow, and both are the reason to do it
this way:

- **The function is portable.** The same `encode` runs against any project. If
  the declaration named `alice@robotics/raw`, it would be pinned to one dataset
  and a second project would need a second function that differed only in a
  string.
- **The graph is project-independent.** A pipeline drawn from declarations is
  the shape of the computation, not a picture of one dataset. The same graph
  describes every run.

## The workdir, and where things land

Two fixed paths on every worker, so nothing has to be configured per job:

```
/workspace              ← the workdir. source= and target= resolve here.
/mounts/<name>          ← each mount in `mounts=`, attached under its own name.
```

A body never writes either path literally. `dls.run.read` / `dls.run.write` take
workdir-relative keys and resolve under `/workspace`; a mount is reached at
`/mounts/<its name>`:

```python file="encode.py"
@dls.udf(queue="gpu", source=["raw/**"], target=["frames/**"], mounts=["raw-video"])
def encode(src: str) -> dict[str, str]:
    data = dls.run.read(f"raw/{src}")          # → /workspace/raw/run01.mp4
    out  = dls.run.write("frames/0000.png")    # → /workspace/frames/0000.png
    ...
    return {"frame": "frames/0000.png"}
```

```
/workspace/
  raw/run01.mp4          ← matched by source: raw/**
  frames/0000.png        ← matched by target: frames/**
/mounts/
  raw-video/             ← the mount named in mounts=["raw-video"]
```

> **Note:** [Mounting Storage](/lakeshore/mounts.md) notes that no mount kind carries a
>   target path, so a registered mount cannot say where it attaches. `/mounts/<name>`
>   answers that without adding a field: the mount's own name *is* its
>   attachment point. That also makes it unique by construction, since mount names
>   are already unique per namespace.

## Specifying the prefix

`/workspace` is the *worker-side* path. What it maps to — which project, which
episode, which stage — is the prefix, and it is assembled from up to three
layers:

```python file="run.py"
with dls.scope("alice@robotics/run-042"):       # 1. the caller, or the pipeline
    encode(src="run01.mp4")
```

```python file="encode.py"
@dls.udf(queue="gpu", workdir="encode")         # 2. a per-UDF sub-prefix
def encode(src: str) -> dict[str, str]:
    ...
```

They **compose, outermost first**:

```
alice@robotics/run-042  /  encode        → mounted at /workspace
      caller or pipeline      decorator
```

So the body's `frames/0000.png` lands at
`alice@robotics/run-042/encode/frames/0000.png`, and the same function run under
a different scope writes somewhere else entirely without editing anything.

> **Warning:** It is tempting to put `workdir: alice@robotics` in `.dreamrc` and stop passing
>   it. Do not — it pins the repository to one project and undoes the portability
>   that made these paths relative in the first place. A repo is not a dataset. The
>   caller or the pipeline knows which project a run belongs to; the code does not,
>   and should not have to be edited to move.
>
>   `.dreamrc` still carries the *relative* defaults below. What it must not carry
>   is the absolute root.

The decorator's `workdir=` is optional and also relative. With neither, the
scope alone is the prefix — which is [what scopes already do
today](/lakeshore/patterns.md), so this adds one inner level rather than replacing
the mechanism.

### Worked example: two stages over one run

```python file="pipeline.py"
import dreamlake.lakeshore as dls

@dls.udf(queue="gpu", workdir="encode",
         source=["raw/**"], target=["frames/**"])
def encode(src: str) -> dict[str, str]:
    ...

@dls.udf(queue="cpu", workdir="label",
         source=["frames/**"], target=["labels/**"])
def label(frame: str) -> dict[str, str]:
    ...

with dls.scope("alice@robotics/run-042"):     # the caller names the project
    frames = encode(src="run01.mp4")
    label(frame=frames["frame"])
```

| Stage | Effective prefix | Reads | Writes |
| --- | --- | --- | --- |
| `encode` | `alice@robotics/run-042/encode` | `raw/**` | `frames/**` |
| `label` | `alice@robotics/run-042/label` | `frames/**` | `labels/**` |

> **Warning:** `encode` writes `frames/**` under its own prefix, and `label` reads `frames/**`
>   under *its* prefix — two different absolute locations. Declared patterns
>   overlap on the relative name, which is what draws the edge in the graph, but
>   the keys the body returns are what actually carry data between them. A stage
>   sub-prefix isolates; it does not connect. If two stages must share a directory,
>   give them the same `workdir=` or none at all.

## Two spellings, one meaning

Every field takes **either a list or a multi-line string**, and the two are
equivalent:

**List**

```python file="access.py"
@dls.udf(queue="gpu", source=["raw/**", "calibration/*.json"])
def encode(src: str) -> dict[str, str]:
    ...
```

**Multi-line string**

```python file="access.py"
@dls.udf(queue="gpu", source="""
    raw/**
    calibration/*.json
""")
def encode(src: str) -> dict[str, str]:
    ...
```

The string form is **dedented automatically**, so the block indents with the
code around it and the leading whitespace never reaches the parser. Lines are
split, stripped, and empties dropped — which means the closing `"""` can sit on
its own line without producing a phantom entry.

```python
"""
    raw/**
    calibration/*.json
"""                             # → ["raw/**", "calibration/*.json"]
```

Both spellings normalize to the same list before anything else sees them, so a
decorator, a `.dreamrc`, and a stored record all hold one shape.

The multi-line form exists because these lists get long and are read far more
often than they are written. A list literal of six entries wraps awkwardly and
diffs badly; six lines in a block diff one line at a time.

## Read and write are different lists

Access has a direction, and one list cannot carry both. A function that reads a
raw capture and writes derived frames should be able to say so — and be denied
the reverse:

```python file="access.py"
@dls.udf(
    queue="gpu",
    source="""
        raw/**
    """,
    target="""
        frames/**
    """,
)
def encode(src: str) -> dict[str, str]:
    ...
```

**Why a separate field rather than a mode on one list.** The compact alternative
is per-entry modes on `source=` — `["raw", "frames:rw"]` — one field, no
duplication. Three things argue against it:

- **Direction is not derivable, and the safe default is wrong.** One list means
  either everything is read-write, which over-permissions the ordinary
  read-raw-write-derived function, or a mode has to be spelled per entry anyway.
- **The enforcement site already exists, and it is write-shaped.** The
  returned-key contract runs on the way out of the run context and already knows
  every key the body wrote. Checking those against a declared write list is the
  same pass with one more predicate — no new interception point. There is no
  equivalent existing hook on the read side.
- **The write list is the one you audit.** Functions read from several places
  and usually write to one. "Which functions can write to `frames`?" should be a
  field lookup, not a substring search for `:rw` inside a list of strings.

The cost is real but small: a read-modify-write source appears in both fields.
That repetition is legible, which is the point.

> **Note:** `source=` and `target=` are singular because each names a **role**, not a
>   count — the source of this function, the target of this function — even though
>   both accept several patterns. They mirror the `src` / `dest` vocabulary the
>   bodies already use.
>
>   `mounts=` stays plural deliberately: it is a set of distinct resources rather
>   than one role, and the entries are names of things that exist independently.

## Mounts

`source` and `target` grant access to keys. `mounts` asks for a
**filesystem** — the S3 bucket or network share a body expects to find already
on disk:

```python file="access.py"
@dls.udf(queue="gpu", mounts=["raw-video"])
def encode(src: str) -> dict[str, str]:
    ...
```

Each entry names a registered [Mount](/lakeshore/mounts.md) in the namespace. The
mount already carries its own target — an S3 mount points at a
[Storage](/lakeshore/mounts.md#the-type), which holds the bucket, region and
credentials — so the UDF names *which* mount, never how to reach it.

That separation is the reason this is a list of names and not a config block: a
credential rotation or an endpoint change happens once on the Storage, and every
UDF referencing it follows without an edit.

> **Warning:** The [Mounting Storage](/lakeshore/mounts.md) page notes that no queue, mode, or
>   `RunConfig` field names a mount, so even a daemon able to attach one would not
>   know which. `mounts=` is that field. Until it exists, a registered mount
>   changes nothing about how a job runs.

## Repo-wide defaults in `.dreamrc`

Most repositories read and write the same handful of shapes everywhere, and repeating
them on every decorator is noise. `.dreamrc` — the YAML config the SDK already
resolves — carries the repo-level set:

```yaml file=".dreamrc"
source:
  - raw/**
  - calibration/*.json

target:
  - frames/**

mounts:
  - raw-video
```

The resolution order is the one the SDK already documents: an explicit path,
then `$DREAMRC`, then `./.dreamrc` walking up to the filesystem root, then
`~/.dreamrc`. So a repo's file sits at its root and applies to every UDF beneath
it.

### How the two combine

**The decorator adds to the file; it does not replace it.** A UDF's effective
access is the union of what `.dreamrc` grants and what the decorator names:

```yaml file=".dreamrc"
source:
  - raw/**
```

```python file="encode.py"
@dls.udf(queue="gpu", source=["calibration/*.json"])
def encode(src: str) -> dict[str, str]:
    ...
    # effective source: raw/** + calibration/*.json
```

Union rather than override, because the alternative surprises in the dangerous
direction. If a decorator replaced the file, adding one narrow entry to a
function would silently revoke everything the repo had granted it, and the
failure would appear at runtime in a body that used to work.

> **Note:** Union means a decorator cannot *reduce* access. That is deliberate — a field
>   that sometimes widens and sometimes narrows is impossible to review. Running
>   with less than the repo grants is a real need, and it gets its own form at the
>   call site rather than an overload here: see
>   [Overrides](#overrides-and-the-direction-they-may-move).

## Why this belongs on the spec, not in the arguments

The obvious objection is that `src` is already a parameter — `encode(src="raw/run01.mp4")`
says what it reads. It does, but only at call time, and that is the whole
problem.

An argument is a **value**; a declaration is a **property of the function**.
Three things need the second and cannot use the first:

- **The graph is static.** The tracer derives a pipeline from source *without
  running it*. If the only statement of what a node reads is an argument passed
  at some future call site, there is nothing to draw until the pipeline has
  already run. Declared access is what makes a node's ports knowable before
  execution.
- **The registry cannot be queried otherwise.** "Which functions write to
  `frames`?" is answerable from a declaration and unanswerable from argument
  values, which are not stored on the function at all.
- **Checking happens too late.** An argument is validated when the body uses it.
  A declaration can be checked at dispatch, before a worker is paid for.

So the argument stays — it says *which* raw capture this call reads. The
declaration says *which family of things this function is ever allowed to read*.
They are different statements and both are needed.

## Wildcards

A declaration that had to name concrete keys would be useless: the scope prefix
is per-invocation, fan-out writes shard names that do not exist yet, and a
function meant to run over every episode in a project cannot enumerate them.
Patterns are the normal case, not an escape hatch.

```python file="access.py"
@dls.udf(
    queue="gpu",
    source="""
        raw/*.mp4                     # one segment, any mp4 directly under raw/
        calibration/**                # any depth under calibration/
    """,
    target="""
        frames/**                     # any depth under frames/
    """,
)
def encode(src: str) -> dict[str, str]:
    ...
```

| Pattern | Matches |
| --- | --- |
| `*` | One segment — `raw/*.mp4` matches `raw/run01.mp4`, not `raw/a/b.mp4` |
| `run-*` | Prefix within a segment — `frames/run-*` |
| `**` | Any depth — `frames/**` covers `frames/a/b.png` |

Enforcement is then "does the concrete key match a declared pattern", which is
the check the returned-key contract is already positioned to make — it runs on
the way out of the run context and already holds every key the body wrote.

> **Warning:** A broad `source` pattern costs you read amplification. A broad `target`
>   pattern is how a function silently overwrites something it was never meant to
>   touch, and it is the one that cannot be undone. A bare `**` in `target`
>   grants the entire workdir — it reads as convenience and behaves as a blank
>   cheque, and is worth rejecting rather than accepting as shorthand.

## Overrides, and the direction they may move

Overrides are wanted — the same function against a dev dataset, a backfill
pointed at last year's project, a test run confined to one episode. The rule
that keeps them safe is that they may only ever **narrow**:

```python file="access.py"
inv = encode.submit(
    src="raw/run01.mp4",
    _source=["raw/run01.mp4"],            # intersected with the declaration
)
```

That gives two layers with deliberately different rules:

| Layer | Combines by | What it is |
| --- | --- | --- |
| `.dreamrc` + decorator | **Union** | The grant. Static, reviewable, what the graph draws. |
| Call-site override | **Intersection** | This run's slice of the grant. Never widens it. |

The asymmetry is the point. Declaration unions because a decorator that replaced
the repo file would silently revoke access and fail at runtime in a body that
used to work. Invocation intersects because a call that could widen its own
permissions is not a permission system — the declaration would become a default
rather than a bound.

An override naming something outside the grant is an error at submit, not a
silent no-op. Failing loudly matters more here than convenience: the caller
asked for something the function is not allowed to do, and quietly clamping to
the intersection would hide that.

## In the node graph

Declared access is what lets the [pipeline graph](/workflows.md) draw a node
without running it, and it maps onto the existing shape rather than needing a
new one:

- **`source` become inbound ports; `target` become outbound ports.** These
  are the `inputs` and `outputs` the node schema already carries.
- **Edges come from overlap.** Where one node's `target` pattern intersects
  another's `source` pattern, there is an edge. The graph stops being an
  inference from dataflow in the body and becomes a join over declarations —
  which is both cheaper and harder to get wrong.
- **Mounts are annotations, not ports.** A mount is an attachment, not a flow
  between nodes. It belongs on the node as a badge; drawing it as an edge would
  imply a producer that does not exist.

Wildcards are where it gets interesting, and they need their own treatment:

**A pattern port is a family, not a thing.** `frames/**` is one declaration that
may correspond to a thousand keys or none. Drawn as an ordinary port it looks
like a single artifact; drawn as nothing it disappears. It wants to render as a
port that visibly stands for a set.

**A pattern edge is "may flow", not "does flow".** Two overlapping patterns
prove a *possible* connection, not an actual one — the concrete keys may never
intersect at runtime. That is a real distinction and the graph already has a
vocabulary for it, since edges are typed. A speculative edge should not look
identical to an observed one.

**Runtime resolves it.** Once invocations exist, the concrete keys are known, so
a run overlay can promote the speculative edges that actually carried data and
grey the ones that did not. The static graph shows what *could* connect; the
overlay shows what did.

> **Note:** Promoting speculative edges requires knowing which invocation produced which
>   key. `Invocation` already carries `correlationId`, `parentInvocationId` and
>   `rootInvocationId` — and nothing writes them today. The static half of this
>   works without that; the overlay does not.

    What a source name resolves to, and how one is created.

    The Mount record `mounts=` names, and the Storage behind it.

    Scopes and the returned-key contract these fields build on.

---

Source: https://docs.dreamlake.ai/lakeshore/dreamdb

# Sources (DreamDB)

  A DreamLake-hosted store for your own videos and structured data. Push from
  the terminal — each video is sliced into streamable fragments automatically.

## Install

```bash
pip install "dreamlake[auth,dreamdb]"    # or: uv add "dreamlake[auth,dreamdb]"
brew install ffmpeg                      # apt install ffmpeg on Linux
```

`ffmpeg` must be on `PATH` for any push with video.

## Log in

```bash
dreamlake login                          # OAuth device flow
```

## Model: source → collection → data

Think **database → table → rows**.

| Layer | What it is | Command |
|-------|-----------|---------|
| **Source** | Namespaced, permissioned store | `source create` |
| **Collection** | A dataset with a schema | `source collection create` |
| **Data** | Records at time anchors | `source push` |

One source holds many collections; access is granted per source.

## Quick start — a folder of videos

```bash
dreamlake sources create charlie-57/my-videos
dreamlake sources collections create clips --source my-videos --preset video
dreamlake sources push ./videos --source my-videos --collection clips
```

`--preset video` = two fields (`video` + `path`); `push <dir>` uploads every
video as one record. Each is normalised to H.264 854×480 (`--width`/`--height`
to change) and sliced into ~2s fragments.

## Naming a source

A source name may carry its namespace as a prefix:

```
[<namespace>/]<name>
```

`charlie-57/my-videos` creates the source under the `charlie-57` namespace.
**Omit the prefix and it lands in your own namespace** — `dreamlake sources
create my-videos` is the common case and needs nothing extra.

The prefix is how you write into an org you own: `dreamlake sources create
charlie-57-org/my-videos`. Ownership is still required; the syntax only says
where, not whether you may.

> **Warning:** This page describes the target surface. `dreamlake-py` ships
>   `dreamlake source` (singular), `dreamlake source collection` (singular), and
>   takes the namespace as `--ns <slug>` rather than as a `namespace/name` prefix.
>   Until the rename lands, translate: `dreamlake sources create ns/name` is
>   `dreamlake source create name --ns ns` today.

> **Note:** The namespace travels with the name rather than in a separate `--ns` flag, so
>   a source is always identifiable from a single string — in a command, in a
>   config file, or pasted into a message. The unprefixed form stays short for the
>   case that dominates.

## Custom schema

Write a schema JSON, pass it to `collection create`:

```json file="schema.json"
{
  "fields": [
    { "name": "video",    "type": "video", "mime": "h264" },
    { "name": "path",     "type": "scalar_string" },
    { "name": "category", "type": "scalar_categorical" },
    { "name": "verified", "type": "scalar_bool" }
  ]
}
```

```bash
dreamlake sources collections create labeling --source charlie-57/my-videos --schema schema.json
```

### Field types

| Type | Value in a record |
|------|-------------------|
| `video` | file path — needs `mime` (e.g. `"h264"`) |
| `image` | file path (raw bytes) |
| `embedding` | `.npy` path or inline list — needs `dim` |
| `scalar_string` · `scalar_categorical` | a string |
| `scalar_int` · `scalar_timestamp` | an integer (timestamp = ns) |
| `scalar_float` | a number |
| `scalar_bool` | `true` / `false` |

## Push structured data — manifest

A folder can't carry scalar values, so custom schemas push with a **manifest**:
one JSON listing fields + every record. Its `fields` block **is** a schema —
same file works for both steps.

```bash
dreamlake sources collections create labeling --source my-videos --schema manifest.json
dreamlake sources push --manifest manifest.json --source my-videos --collection labeling
```

```json file="manifest.json"
{
  "fields": [
    { "name": "video",       "type": "video",     "mime": "h264" },
    { "name": "thumb",       "type": "image",      "mime": "jpeg" },
    { "name": "clip",        "type": "embedding",  "dim": 512 },
    { "name": "path",        "type": "scalar_string" },
    { "name": "frame_count", "type": "scalar_int" },
    { "name": "duration_s",  "type": "scalar_float" },
    { "name": "verified",    "type": "scalar_bool" },
    { "name": "category",    "type": "scalar_categorical" },
    { "name": "recorded_at", "type": "scalar_timestamp" }
  ],
  "records": [
    {
      "anchor": 0,
      "video": "clips/a.mp4", "thumb": "thumbs/a.jpg", "clip": "embeds/a.npy",
      "path": "a.mp4", "frame_count": 360, "duration_s": 12.0,
      "verified": true, "category": "assembly", "recorded_at": 1750000000000000000
    },
    {
      "anchor": 3600000000000,
      "video": "clips/b.mp4", "thumb": "thumbs/b.jpg", "clip": "embeds/b.npy",
      "path": "b.mp4", "frame_count": 180, "duration_s": 6.0,
      "verified": false, "category": "electronics", "recorded_at": 1750003600000000000
    }
  ]
}
```

- **`video` / `image`** — path relative to the manifest.
- **`embedding`** — a `.npy` path, or an inline list of exactly `dim` numbers.
- **`anchor`** — required per record, integer ns. For unrelated videos use
  `index × 3_600_000_000_000` (a 1-hour slot each).

Lay files out next to the manifest: `clips/  thumbs/  embeds/`.

Everything is validated **before** anything uploads — bad manifest fails fast,
never a half-written collection.

## Command reference

```bash
dreamlake sources create [<namespace>/]<name>

dreamlake sources collections create <name> --source [<namespace>/]<src> \
    [--preset video | --schema <schema.json>]

dreamlake sources push <dir> --source [<namespace>/]<src> --collection <col> \
    [--width <px>] [--height <px>] [--frag-duration <seconds>]
dreamlake sources push --manifest <manifest.json> --source [<namespace>/]<src> --collection <col>
```

---

Source: https://docs.dreamlake.ai/lakeshore/mounts

# Mounting Storage

## The type

A mount is not a store. **`Storage` says where bytes live; `Mount` says how they
are attached to a job.** So the S3-family kinds carry a `storage` reference
rather than re-declaring a bucket, and the connection details stay in one place.

```ts file="Mount"
type SecretRef = { $secret: string }

interface MountBase {
  id:           string
  namespaceId:  string        // the prefix — name is unique within it
  name:         string
  createdAt:    Date
  updatedAt:    Date
}

type Mount = MountBase & (
  // ── Object storage: the target is a registered Storage ──────────────
  | { kind: 's3';           storage: string;  prefix?: string }
  | { kind: 's3fs';         storage: string;  prefix?: string; options?: string }

  // ── Everything else carries its own connection ──────────────────────
  | { kind: 'nfs';          server: string;  path: string;   options?: string }
  | { kind: 'samba';        server: string;  share: string;  options?: string; creds?: SecretRef }
  | { kind: 'ftp';          server: string;  path?: string;  port?: number;    creds?: SecretRef }
  | { kind: 'sftp';         server: string;  path?: string;  port?: number;    creds?: SecretRef; key?: SecretRef }
  | { kind: 'google_drive'; folderId: string; creds?: SecretRef }
  | { kind: 'dropbox';      path: string;     creds?: SecretRef }
  | { kind: 'bind';         hostPath: string; readOnly?: boolean }
  | { kind: 'configmap';    kubeNamespace: string; configMapName: string; items?: Record<string, string> }
)
```

`storage` is a **Storage name**, resolved within the same namespace — the same
by-name reference [code snapshots](/lakeshore/code-snapshots.md) already use in
`storageName` to presign a download.

Like every other Lakeshore resource the identity is the pair —
`@@unique([namespaceId, name])` — so `raw-video` in two namespaces is two
mounts. The union is closed on `kind`, so a writer knows which fields are
required without consulting a second table, and a reader can narrow on `kind`
and get the right fields typed.

### Why the S3 kinds delegate

A `Storage` already carries `bucket`, `prefix`, `endpoint`, `region`, and a
`creds` secret — and it is deduped on `(namespaceId, bucket, prefix, endpoint)`,
so one S3 target is one row. Restating those on the mount would create a second
source of truth for the same bucket, with no constraint keeping them agreed.

It also inherits two things a mount would otherwise have to reimplement:
provisioning (`provision: true` on create calls `CreateBucket`, idempotently)
and the immutability rule — `bucket` / `prefix` / `endpoint` cannot be edited
after creation, because changing an S3 target in place would silently break
every reference to it.

`prefix` still appears on the mount, and it is not a duplicate: `Storage.prefix`
scopes the store, while `Mount.prefix` scopes *this attachment* within it.

> **Note:** `Storage` is S3-compatible object storage — kinds `s3` and `s3-prefix`.
>   There is no registered-resource equivalent for NFS, SMB, FTP, Drive, Dropbox,
>   a host path, or a ConfigMap, so those kinds still carry their own connection
>   fields and their own `$secret` refs. If a shared registry for non-S3 targets
>   is wanted later, this is the seam where it would go.

> **Warning:** **`configmap` has to rename its `name`.** The Kubernetes ConfigMap's own name
>   collided with the mount's `name` once both sat at the root, so it appears
>   above as `configMapName`.

**`[ dev ]`** — a mount can be registered, validated and read back, but nothing
attaches it yet, and the record cannot yet say where it would attach. See
[Providers](/lakeshore/providers.md) for what the marker means, and
[What is missing](#what-is-missing) for the specifics.

  A **mount** is a shared filesystem the runner attaches into a job's workdir
  before dispatch. Where a [code snapshot](/lakeshore/code-snapshots.md) ships the
  code, a mount supplies the data the code expects to find already on disk.

## Coming from a jaynes config

Jaynes describes a mount by **role and direction**. Lakeshore describes one by
**protocol**. That difference is why a jaynes config does not translate
field-for-field.

```yaml file=".jaynes.yml"
mounts:
  - !mounts.SSHCode &code_mount
    local_path: .
    host_path: "{secret.JYNS_HOME}/demo/{now:%Y-%m-%d}"
    container_path: /workspace
    pypath: true
    excludes: >-
      --exclude='data' --exclude='*.git' --exclude='*__pycache__'
    compress: true
```

The class picks the role. `SSHCode`, `S3Code` and `GSCode` carry code **in**;
`S3Output` syncs results **out** on an `interval`; `Host` and `TarMount` attach
something already present.

### The paths

Every jaynes mount names `container_path` — where it appears to the job — and
all but `Host` also name a `local_path` to ship from. Lakeshore answers both,
but by **convention rather than by field**:

| jaynes field | What it expresses | Lakeshore |
| --- | --- | --- |
| `container_path` | Where it appears to the job | **`/mounts/<name>`** — the mount's name is its attach point |
| `host_path` | Staging path on the host | Daemon-managed; not something you set |
| `local_path` | Source on your machine | [Code snapshots](/lakeshore/code-snapshots.md) for code; a `Storage` for data |

That is a real difference in kind, not a missing feature: jaynes makes you name
three paths per mount, and Lakeshore fixes two of them so a mount only has to
say *what* it is. See [Declaring access](/lakeshore/access.md#the-workdir-and-where-things-land)
for the `/workspace` and `/mounts/<name>` layout.

### What genuinely has no equivalent

| jaynes | What it expresses | Lakeshore |
| --- | --- | --- |
| `S3Code` vs `S3Output` | Direction — read in, or sync out | **Nothing.** `kind` names a protocol; a mount has no direction |
| `interval`, `sync_s3` | Periodic push-out cadence | **Nothing.** There is no sync-out mount at all |
| `pypath: true` | Add the mount to `PYTHONPATH` | **Nothing** for mounts. Code snapshots do their own `sys.path` insert |
| `docker_mount_type` | Attach *mechanism* — `bind` / `volume` / `tmpfs` | **Nothing.** Lakeshore's `bind` kind names a *source* (a host directory), which is a different axis |
| `volume`, `mount_path`, `sub_path` | Kubernetes volume + subPath wiring | **Nothing.** The `configmap` kind is the only k8s-aware mount |
| `init_image`, `init_image_pull_policy`, `init_image_pull_secret`, `cpu`, `mem` | The init container that stages the data, and its resources | **Nothing.** `S3Code` and `GSCode` emit a full `init_container` and `volume_mount` spec; Lakeshore emits neither |
| `excludes`, `file_mask`, `compress`, `exclude_vcs`, `exclude_from` | Tar shaping on upload | Belongs to [code snapshots](/lakeshore/code-snapshots.md), not to mounts |
| `{secret.X}` interpolation | Credential injection | `{ "$secret": "name" }` — the nearest thing that **is** implemented |

The Kubernetes rows are the largest omission and the easiest to miss. A jaynes
`S3Code` mount does not merely describe storage — it *emits* a Kubernetes init
container that stages the tarball into a volume, plus the `volumeMount` (with
`subPath`) that exposes it to the job, sized by `cpu` and `mem`. Lakeshore's
Kube launcher runs a pod; nothing in the `Mount` model contributes to its spec.

### Two structural differences

**Jaynes mounts are per-run; Lakeshore mounts are registered resources.** A
`.jaynes.yml` builds its mount list fresh for each launch, which is why
`{now:%Y-%m-%d}` templating appears in the paths at all. A Lakeshore `Mount` is a
durable row under `(namespace, name)` that many jobs reference. Anything per-run
in a jaynes path has nowhere to go on the Lakeshore side.

**Jaynes code mounts are Lakeshore code snapshots, not Lakeshore mounts.**
`SSHCode` / `S3Code` tar a local tree, upload it, and unpack it remotely — which
is exactly what a [code snapshot](/lakeshore/code-snapshots.md) does, and it works
today. Porting a jaynes config, the code mount is the part that already has a
home; the data mounts are the part that does not.

## Kinds

| Kind | Fields at root | Notes |
| --- | --- | --- |
| `s3` | `storage`, `prefix?` | Userspace client — **copy-on-read, no FUSE**. Target comes from the named Storage. |
| `s3fs` | `storage`, `prefix?`, `options?` | The s3fs-fuse driver — a real filesystem path |
| `nfs` | `server`, `path`, `options?` | POSIX network filesystem; `path` is the export |
| `samba` | `server`, `share`, `options?`, `creds?` | CIFS; runner uses `mount -t cifs` |
| `ftp` | `server`, `path?`, `port?`, `creds?` | only `server` is structurally required |
| `sftp` | `server`, `path?`, `port?`, `creds?`, `key?` | runner uses sshfs or curlftpfs |
| `google_drive` | `folderId`, `creds?` | rclone-backed; `folderId` may be `"root"` |
| `dropbox` | `path`, `creds?` | rclone-backed |
| `bind` | `hostPath`, `readOnly?` | Host directory; `hostPath` is the source |
| `configmap` | `kubeNamespace`, `configMapName`, `items?` | Kubernetes; renamed to avoid colliding with the mount's `name` |

> **Note:** Same target, different activation. Both name a Storage; **`s3`** pulls objects into the
>   workdir on demand through a userspace client — higher throughput, simple
>   semantics, no privileges. **`s3fs`** mounts the bucket through FUSE so job
>   code sees a real path. Reach for `s3` unless the code genuinely needs
>   filesystem behaviour it cannot get from a copied tree.

## Credentials

For the S3 kinds there is no credential field on the mount at all — the
`creds` secret belongs to the [Storage](https://lakeshore.dreamlake.ai/admin/storages)
it names, which is the point of delegating.

For every other kind, credentials never sit in the row as plaintext. Use a
`$secret` marker in any credential field and the control plane resolves it
through the same plumbing the providers and tunnels routes use:

```json
{ "kind": "sftp", "server": "lab-nas", "creds": { "$secret": "nas-login" } }
```

The referenced secret must exist in the same namespace, or the write is rejected
with a 422.

Credential refs are **not** required on kinds that can attach anonymously — a
public NFS export, an unauthenticated FTP server. That is deliberate: the runner
enforces it at activation time, where it can give a clearer error than "field
required" would at write time.

## The interface

### Python

There is none. No `Mount` type, no mount argument on `@udf`, nothing in
`RunConfig` that names one. A job cannot request a mount from Python today —
mounts are an operator-side resource registered out of band.

### CLI

```bash file="terminal"
lakeshore mounts add raw-video --kind s3 \
    --kwarg storage=training-data \
    --kwarg prefix=2026/

lakeshore mounts list
lakeshore mounts show raw-video
lakeshore mounts update raw-video --kwarg prefix=2027/
lakeshore mounts remove raw-video
```

`--kwarg key=value` is repeatable and dotted keys nest, so
`creds.$secret=nas-login` builds a nested credential ref. For anything larger,
`--config-file foo.yaml` (or `.json`) is posted as-is. The two combine — the
file seeds the config and `--kwarg` entries override on top — and one of them is
required.

### HTTP

```json file="POST /v1/namespaces/:ns/mounts"
{
  "name": "raw-video",
  "kind": "s3",
  "storage": "training-data",
  "prefix": "2026/"
}
```

> **Warning:** The flattened shape above is the intended one. The route as deployed today
>   accepts `{ name, kind, config }` with the kind-specific fields inside
>   `config`, and the `Mount` row stores `config` as an opaque `Json` column. Both
>   spellings appear in this repo's history; the flat one is where it is going.

The rest is ordinary CRUD over `(namespace, name)`:

```
GET    /v1/namespaces/:ns/mounts
GET    /v1/namespaces/:ns/mounts/:name
PATCH  /v1/namespaces/:ns/mounts/:name
DELETE /v1/namespaces/:ns/mounts/:name
```

## What is missing

The control plane's own header says it: this pass is **metadata-only**. It
accepts the kind-specific config, validates `$secret` refs, and persists the row
as-is. The actual `mount -t <kind> …` — or the rclone / aws-cli equivalent — at
launch time is described there as "a daemon-side follow-up."

Concretely, today:

- **A mount attaches at `/mounts/<name>`, by convention.** No kind's config
  carries a target path, and none needs to — the name is the attach point. What
  is still absent is any way to *override* that for a job expecting a specific
  location.
- **Nothing reads a `Mount`.** The daemon does not fetch mounts, and the Python
  SDK has no concept of one.
- **No job can reference one.** No field on a queue, a mode, or a `RunConfig`
  names a mount, so even a daemon that could attach one would not know which.
  [`mounts=` on the decorator](/lakeshore/access.md#mounts) is the proposed field
  that would close this.

If you need data on a worker now, the working path is the one the SDK already
uses: string keys through `dls.run.read` / `dls.run.write` under a
`dls.scope(...)`, with bytes travelling by reference. See
[Simple functions](/lakeshore/patterns.md).

    The other half of what a worker needs — the code, versioned by commit. This
    is where a jaynes `SSHCode` / `S3Code` mount actually lands.

    What runs on a worker before it takes work.

---

Source: https://docs.dreamlake.ai/lakeshore/code-snapshots

# Code snapshots

## The type

```ts file="CodeRepo"
interface CodeRepo {
  id:           string
  namespaceId:  string        // the prefix — dedup is scoped to it
  remote:       string        // git remote URL, lowercased for dedup
  commit:       string        // 40-hex commit, or a synthetic hash when dirty
  branch?:      string        // informational; not part of the dedup key

  backend:      's3' | 'github'   // default 's3'
  archiveKey:   string        // S3 object key, or the GitHub ref name
  storageName?: string        // Storage entry used to presign the download;
                              // null for the github backend

  sizeBytes?:   number        // informational
  submodules?:  Array<{ path: string; commit: string; remote: string }>
  dirty:        boolean       // snapshot includes uncommitted changes

  createdAt:    Date
}
```

> **Warning:** `'s3' | 'github'` are not the same kind of thing. `s3` is a **protocol** —
>   compare `Storage.kind`, which is `s3` / `s3-prefix`, consistently one axis.
>   `github` is a **vendor**, and choosing it changes something else entirely:
>   whether an archive exists at all.
>
>   The damage shows up in the neighbouring fields. `archiveKey` means "S3 object
>   key" under one value and "GitHub ref name" under the other — one field, two
>   incompatible types, discriminated by a sibling. `storageName` is documented as
>   "null for the github backend", so its presence depends on another field's
>   value. Both are the signature of an enum doing two jobs.
>
>   Underneath are two independent questions that `backend` welds together:
>   **where the bytes live** (an object store, addressed by key) and **how the
>   worker obtains them** (fetch a presigned URL, or clone from a third party with
>   its own credentials). The second is not a storage detail — it decides whether
>   the worker needs GitHub access at all, which is a different security posture,
>   not a different bucket.
>
>   [The tarball proposal](#proposal-the-tarball-is-the-payload) removes the field
>   rather than fixing it: if the tar is the payload, it is inline or it is a ref,
>   exactly like every other payload on the wire, and there is nothing left for
>   `backend` to discriminate.

The identity is the triple — `@@unique([namespaceId, remote, commit])`. That is
the dedup key, and the reason a second submit from the same tree uploads
nothing. `branch` is deliberately outside it: the same commit reached from two
branches is one snapshot.

  A remote worker needs your code before it can run your function. A **code
  snapshot** is one captured tree of one repo — tarred, uploaded once, and
  reused by every invocation that shares its commit. You never create one
  explicitly; submitting a `.remote()` call does it for you.

The mechanism is deliberately dull. On submit, the SDK asks git for the current
remote and commit, checks whether that pair is already archived, and uploads a
`git archive` tarball if it isn't. The commit is the cache key, so the second
submit from the same tree costs one lookup and no bytes.

## Coming from a jaynes config

In jaynes, shipping your code **is a mount** — you declare it, and it re-tars on
every launch:

```yaml file=".jaynes.yml"
mounts:
  - !mounts.SSHCode &code_mount
    local_path: .
    host_path: "{secret.JYNS_HOME}/demo/{now:%Y-%m-%d}/{now:%H%M%S.%f}"
    remote_tar: "{secret.JYNS_HOME}/demo/{now:%Y-%m-%d}.tar"
    pypath: true
    excludes: >-
      --exclude='data' --exclude='*.git' --exclude='*__pycache__'
    compress: true
```

Here it is not a mount and not declared at all. Submitting a `.remote()` call
creates the snapshot; there is no entry to write.

| jaynes | What it expresses | Lakeshore |
| --- | --- | --- |
| `!mounts.SSHCode` / `S3Code` / `GSCode` | Which channel carries the code | `backend`, loosely — though it also decides whether an archive exists at all |
| `local_path: .` | Which tree to ship | The git repo you submit from; there is no path to choose |
| `host_path`, `container_path` | Where it lands, where it appears | Worker-managed cache, keyed by commit. **Not configurable.** |
| `local_tar`, `remote_tar` | Where the tarball is staged | `archiveKey` in the [Storage](/lakeshore/mounts.md) named by `storageName` |
| `pypath: true` | Add it to `PYTHONPATH` | Automatic — the worker inserts the extracted tree on `ImportError` |
| `excludes`, `exclude_vcs`, `file_mask` | Tar shaping | `git archive` decides; no exclude knobs are exposed |
| `compress` | Whether to gzip | Not exposed |
| `{now:…}` in paths | Making each launch distinct | `commit` — the content decides identity, not the clock |

Three differences change how you work, not just how you configure:

**Identity is the commit, not the path.** Jaynes gives every launch a fresh
timestamped directory, so the same tree uploads again on every run. Here the key
is `(remote, commit)`, so the second submit from an unchanged tree uploads
nothing at all. The `{now:…}` templating that makes jaynes paths unique has no
equivalent, and needs none.

**It has to be a git repo.** Jaynes tars whatever `local_path` points at. A
snapshot is `git archive` over a real remote and commit, so a directory that is
not a repo has nothing to capture.

**Uncommitted work does not travel.** This is the one that bites when porting.
A jaynes `SSHCode` mount cheerfully tars your working tree, edits and all. Here
a dirty tree currently produces no snapshot **and no error** — see
[Uncommitted changes](#uncommitted-changes) below. A jaynes workflow that
depended on shipping uncommitted edits needs a commit step.

## What the worker actually reads

This is the part worth internalizing, because it explains every other behaviour
on this page. The snapshot **collection is not on the execution path**. At
submit time the control plane stamps four fields into the invocation envelope:

```python
{"remote": ..., "commit": ..., "archiveKey": ..., "storageName": ...}
```

The worker reads that stamp, and fetches the archive **only if the import
fails** — then caches the extracted tree by commit. So a warm worker running
your fifth invocation of the same commit touches neither S3 nor the control
plane. The collection exists for deduplication and for inspection, not for
dispatch.

> **Note:** **Why `ImportError` is the trigger.** A worker built from an image that
>   already contains your package imports it directly and never downloads
>   anything. The archive is the fallback for the case where it can't — which
>   makes baking code into the image and shipping it per-run the same code path,
>   with no flag to set.

## The interface

### Python

```python
from dreamlake.lakeshore import code_archive

code_archive.push_if_needed(
    base_url: str,
    namespace: str,
    token: str | None,
    *,
    storage_name: str = "code-staging",
    allow_dirty: bool = False,
    timeout: float = 60.0,
) -> dict[str, Any] | None
```

Tars the working tree, presigns a `PUT` against `storage_name`, uploads, and
registers the snapshot. Returns the snapshot dict.

Returns `None` — meaning *no snapshot was made* — in two cases: the working
directory is not a git repo, or **the tree is dirty and `allow_dirty` is
false**. See [Uncommitted changes](#uncommitted-changes) below, because the
second case is the one that will surprise you.

Repeat calls within one process short-circuit on an in-memory set keyed
`remote:commit`, so a script submitting a thousand invocations archives once.

### CLI

```bash
lakeshore code push          # archive and register the current tree
lakeshore code list          # list archived code snapshots
```

### HTTP

Four routes under the config plane, bearer-authenticated. The path segment is
`code-repos` for historical reasons — the records are snapshots.

| Verb     | Path                                      | Purpose                                       |
| -------- | ----------------------------------------- | --------------------------------------------- |
| `POST`   | `/v1/namespaces/:ns/code-repos`           | Register an uploaded archive                  |
| `GET`    | `/v1/namespaces/:ns/code-repos`           | List, newest first — `?remote=`, `?limit=`    |
| `GET`    | `/v1/namespaces/:ns/code-repos/lookup`    | Dedup probe — `?remote=&commit=`, 200 or 404  |
| `GET`    | `/v1/namespaces/:ns/code-repos/:id`       | Fetch one                                     |

`limit` defaults to 50 and caps at 200. `remote` is matched lowercase. There is
no delete route — snapshots are append-only.

```ts
// POST body. `remote` and `commit` are required; the rest is optional.
interface CreateCodeSnapshot {
  remote: string          // git remote URL, normalized lowercase
  commit: string          // 40 hex chars, or a synthetic hash for a dirty tree
  branch?: string         // informational — NOT part of the dedup key
  backend?: string        // "s3" | "github", defaults "s3"
  archiveKey?: string     // S3 object key, or a GitHub ref name
  storageName?: string    // which Storage presigns the download; null for GitHub
  sizeBytes?: number
  submodules?: unknown    // [{ path, commit, remote }] at capture time
  dirty?: boolean
}

// Response — the same shape, plus identity and timestamp.
interface CodeSnapshot {
  id: string
  remote: string
  commit: string
  branch: string | null
  backend: string
  archiveKey: string
  storageName: string | null
  sizeBytes: number | null
  submodules: unknown
  dirty: boolean
  createdAt: string
}
```

Snapshots are unique on `(namespace, remote, commit)`. The same commit pushed
twice is one record; the same commit in two namespaces is two.

## Uncommitted changes

> **Warning:** `push_if_needed` returns `None` when the working tree has uncommitted
>   changes, and the submit path treats that the same as an archive-upload
>   failure — deliberately, so that a storage outage doesn't fail your job. The
>   consequence is that **an uncommitted edit and a broken archive channel look
>   identical**, and neither one fails the submit.
>
>   The invocation still runs. It runs against whatever code the worker already
>   has, which is usually the last commit you pushed — not what you are looking
>   at in your editor.

Until this changes, the reliable habit is to commit before a remote submit.
`lakeshore code list` shows what was actually archived, and the `Dirty` column
tells you whether a snapshot captured uncommitted work.

The fix is designed and partially built — `snapshot_dirty_tree()` creates a
detached commit via `write-tree` / `commit-tree` without touching your branch,
and the schema already reserves a synthetic-hash convention and a `dirty` flag
for it. What is missing is the wire between them.

## Where this is going

Two changes are planned. Both are visible in the interface, so they are worth
knowing before you build against it.

**The record splits in two.** One model currently carries both repo identity
(`remote`, `backend`, `storageName`) and per-capture state (`commit`, `branch`,
`dirty`, `archiveKey`, `sizeBytes`). Splitting them gives a `Repo` with a
snapshot history, and gives dirty captures an honest `commit` field — today a
dirty snapshot writes a synthetic hash into a field named `commit`, so *"which
commit did this run use"* is unanswerable for exactly the runs where it matters
most. The key becomes `contentHash`: the commit when clean, a hash of the tar
when dirty.

**Snapshots get a lifecycle.** Today a record is written after upload and never
revisited — nothing verifies that the archive still exists, so a lifecycle-purged
object surfaces as an `ImportError` on a worker mid-job. The planned states:

| State       | Meaning                                                       |
| ----------- | ------------------------------------------------------------- |
| `pending`   | Record written, upload not yet confirmed                      |
| `available` | Archive uploaded and addressable                              |
| `verified`  | Object confirmed present at `verifiedAt`                      |
| `missing`   | Object gone — lifecycle rule, bucket change, manual delete    |
| `failed`    | Upload aborted, or registration raced                         |

Existing records migrate to `available` with `contentHash = commit`. The
envelope keeps its four fields, so nothing you write against the Python or CLI
surface changes shape.

### Proposal: the tarball is the payload

The two porting gaps above — it must be a git repo, and uncommitted work does
not travel — both dissolve if the archive stops being a *consequence* of a
commit and becomes the thing itself.

Invert it: **the tar is the payload; everything else is advisory metadata.**

```ts file="proposed"
interface CodeSnapshot {
  // ── The payload ─────────────────────────────────────────────────────
  tar:      Inline | Ref     // required. base64 under the threshold, else a ref
  patch?:   Inline | Ref     // optional unified diff, applied after unpacking

  contentHash: string        // sha256 of (tar, patch) — the cache key

  // ── Nice-to-have: recorded, never required, never load-bearing ──────
  meta?: {
    remote?:  string
    commit?:  string
    branch?:  string
    dirty?:   boolean
  }
}
```

`remote` and `commit` move into `meta` and stop gating anything. A non-repo
directory produces a snapshot with an empty `meta`; a clean checkout produces
one with all four fields. Both run.

**Why the patch is separate, and worth having.** If the tar carried your working
tree directly, it would differ on every keystroke and dedup would never hit.
Instead let the tar be a **clean base** — `git archive HEAD`, identical across
runs and cached warm on the worker — and let the patch carry only the
uncommitted delta. The tar is big and stable; the patch is small and per-run.
The worker unpacks, applies, imports:

```
unpack tar   →  apply patch (if present)  →  sys.path insert  →  import
```

With no repo there is no base to diff against, so the tar holds the tree and
`patch` is absent. Same path, one step skipped.

Three mechanisms already exist and carry straight over:

- **The inline-or-reference split** is the payload store's, reused verbatim.
  Under `INLINE_THRESHOLD_BYTES` (256 KiB default) it rides in the envelope;
  over it, presign to `payloads/`. Hard cap `MAX_PAYLOAD_BYTES`, 100 MiB. A
  patch is almost always inline; a tar is almost always a ref.
- **The synthetic hash** is already reserved — the schema calls `commit` "a full
  commit hash, or a synthetic hash for dirty snapshots," and `dirty` exists.
  `contentHash` is that idea promoted to the key.
- **The `ImportError` trigger and content-keyed cache** are untouched.

> **Warning:** `backend` accepts `s3` and `github` and is still load-bearing; there is no
>   `tar`, `patch`, or `contentHash` field, and `snapshot_dirty_tree()` — which
>   would produce the base — is still called by nothing.

### What goes in the tar — jaynes has the answer already

A commit defines its own contents. A directory does not, so the tar needs an
include/exclude model, and jaynes already shipped one. It is five knobs feeding a
single `tar` invocation, identical across `SSHCode`, `S3Code`, `GSCode`, and
`TarMount`:

```bash
tar {excludes} {tar_options} -c[z]f {local_tar} -C {local_abs} {file_mask}
```

| Knob | Role | Default |
| --- | --- | --- |
| `file_mask` | **Whitelist** — the tar operand naming what to include | `"."` (everything under the root; may not be empty) |
| `excludes` | **Blacklist** — a raw string of `--exclude=` flags | `--exclude='*__pycache__' --exclude='*.git' --exclude='*.idea' --exclude='*.egg-info'` |
| `exclude_vcs` | Appends `--exclude-vcs` | `True` |
| `exclude_from` | Appends `--exclude-from=<file>`, resolved against `RUN.config_root` | `None` |
| `**tar_options` | Arbitrary passthrough — `key_name=v` becomes `--key-name=v` | none |

The shape is right and worth adopting: a whitelist selects, blacklists prune, and
an ignore file lets a project carry its own rules next to the config. Two
details are worth changing rather than copying:

**`excludes` is a raw shell string.** It is interpolated straight into the
command, so it is both injection-prone and impossible to validate. A list of
patterns that the client renders into flags gets the same expressiveness and can
be checked.

**The defaults overlap, and are still not enough.** `exclude_vcs=True` and the
default `--exclude='*.git'` both drop VCS metadata. Meanwhile nothing excludes
`.venv`, `node_modules`, `data/`, or checkpoints — which is why every
`.jaynes.yml` in the starter kit hand-writes a long exclude line, and why several
of them repeat nearly the same list. A sensible default deny-list would delete
most of that configuration.

The cheapest rule that surprises nobody: **`git archive` when there is a repo**
— it already honours the repo's own ignore rules — **and the tar model above
only when there is not.**

---

Source: https://docs.dreamlake.ai/lakeshore/host-setup

# Host Setup

For enrolling a machine and starting nymph, see [Enroll a host](/lakeshore/hosts/enroll.md).
This page covers runtime environment preparation before or between workloads.

## The type

Setup arrives in two places. The first is on the queue's `daemonTemplate`, read
at launch time:

```ts file="daemonTemplate (setup fields)"
interface DaemonTemplate {
  bootstrap_script?: string     // runs once, at instance creation
  setup_scripts?:    string[]   // seeds the setup-command FIFO
  // …instance_type, image_id, runner — see the Queue model
}
```

The second is the command itself, which is what the daemon actually executes:

```ts file="SetupCommand"
interface SetupCommand {
  script:                string    // required
  sudo?:                 boolean   // default false
  refresh_capabilities?: boolean   // default false — re-report caps after running
  name?:                 string    // optional human label
}
```

`setup_scripts` on the template is mapped into `setup_commands` on the launch
body by the elasticity controller. Both routes below append to the same FIFO.

  A worker is rarely useful the moment it boots. **Host setup** is the ordered
  list of commands it runs before — and, when you append later, between — units
  of work: installing a driver, warming a cache, mounting something by hand.

## Coming from a jaynes config

Jaynes puts setup on the **runner**, and a runner is constructed with the mount
list — `mounts` is the first parameter on every runner class, "reserved by
jaynes to pass in the mount objects". That wiring is what lets the rest of the
config point at it:

```yaml file=".jaynes.yml"
runners:
  - !runners.Tmux &tmux_runner
    setup: >                              # on the host, before the session
      source $HOME/.jaynes_bash;
    startup: >                            # inside the session, before your code
      conda activate torch;
    envs: >
      LANG=utf-8 LC_CTYPE=en_US.UTF-8
    pypath: "{mounts[0].host_path}"       # both derived from the mount
    work_dir: "{mounts[0].host_path}"
    entry_script: "python -u -m jaynes.entry"
    post_script: "tmux list-sessions"
```

### Three phases, not one

The field to be careful about is `setup` versus `startup` — they are different
phases, and only the first is host setup:

| jaynes | Runs | Lakeshore |
| --- | --- | --- |
| `setup` | **On the host**, to prepare the environment | `host_setup` (shipped as `setup_scripts`) / `--setup-script` / the setup FIFO — **this page** |
| `startup` | **Inside the session**, before your code is bootstrapped | **Nothing.** [`run_setup`](#naming-the-phases) is the proposed name for it; the only lever today is baking it into `image_id` |
| `entry_script` | The command that runs your payload | The worker importing `module:qualname`, or `command` on the [exec wire](/lakeshore/command-programs.md) |
| `post_script` | After the run script | **Nothing** — nothing runs after work completes |

Jaynes has three phases where Lakeshore has two, and they do not line up end to
end. Lakeshore's `bootstrap_script` and setup commands are both *host* phases —
one at instance creation, one at any point after. Everything jaynes does
per-session, between the host being ready and the payload starting, has no
Lakeshore equivalent at all.

### The rest

| jaynes | What it expresses | Lakeshore |
| --- | --- | --- |
| `mounts` | The runner is handed the mount objects, so other fields can reference them | **Nothing.** No queue, mode or `RunConfig` field names a mount; [`mounts=` on the decorator](/lakeshore/access.md#mounts) is the proposal that would |
| `work_dir` | Working directory, conventionally `{mounts[0].host_path}` | Fixed at **`/workspace`**; not derived from a mount and not settable per run |
| `pypath` | Add the mount's path to `PYTHONPATH` | Automatic for code — the worker inserts the extracted snapshot on `ImportError`. Nothing for data mounts |
| `envs` | Environment for the session | `RunConfig.env`, per invocation rather than per host |

The `work_dir` and `pypath` rows are the same fact twice: **jaynes derives paths
from mounts; Lakeshore fixes them by convention.** `{mounts[0].host_path}`
interpolation exists because a jaynes mount chooses its own location, so
everything downstream has to ask it where that was. `/workspace` and
`/mounts/<name>` are fixed, so nothing has to be interpolated — and nothing
*can* be, which is the cost.

## Naming the phases

Three phases, and the names should say **what scope they run at**, because that
is the only thing anyone needs to know to place a script correctly:

| Phase | Proposed name | Declared on | Runs |
| --- | --- | --- | --- |
| Instance creation | `bootstrap_script` | `daemonTemplate` | Once per machine, before the daemon exists |
| Host | **`host_setup`** | `daemonTemplate` | On a live worker, at launch or any time after |
| Invocation | **`run_setup`** | `RunConfig` | Before each body, every time |

`host_setup` replaces `setup_scripts`, which named the *type* of the value
rather than the phase — and stopped being accurate once the same list could be
appended to a running worker.

**`run_setup` is the answer to what jaynes calls `startup`.** Three reasons it
beats carrying that name over:

- **`startup` does not say startup of what.** Read cold, it sounds like the
  machine coming up, which is the phase *above* it. `host_setup` / `run_setup`
  name their scope, and the pair reads as one axis.
- **The name says where the field lives.** `RunConfig` is already the
  per-invocation config object — the thing carrying `env`, `image`, `runner`,
  `timeout_s`. A per-invocation script belongs there and nowhere else, and
  `run_setup` puts it there by name. `host_setup` sits on `daemonTemplate` for
  the same reason.
- **It parallels the phase it is most confused with.** The mistake people
  actually make is running a per-host install on every invocation, or expecting a
  per-run tweak to persist. Two names differing in one word make the question
  "per host or per run?" impossible to skip.

There is a sharper argument than any of those three, and it only becomes visible
once the [host key](#the-key-function) exists: **the pair is exactly "in the key"
and "not in the key."** `host_setup` participates in the hash, so declaring
different setup means a different host. `run_setup` cannot, because it runs
before every body by definition and a phase that runs every time can never force
a *different* machine. The two names are not a stylistic pairing — they are the
two sides of one derived predicate.

Rejected alternatives: `warmup` collides with
[preloading](/lakeshore/preloaded.md), which caches *across* invocations rather
than running before each one — the opposite property. `pre_run` says when but
not what. `invocation_setup` is exact but long, and `run` is already the word
this SDK uses for the ambient per-invocation context (`dls.run.read`,
`run_worker`, `RunConfig`).

> **Warning:** `RunConfig.host_setup` and `RunConfig.run_setup` have shipped, and
>   `daemonTemplate.host_setup` is accepted as an *alias* for `setup_scripts`.
>   Nothing was renamed — `setup_scripts` keeps working and stays the written
>   spelling, because `daemonTemplate` is an untyped `Json` column with no schema,
>   written by three separate CLI paths and read by the elasticity controller, so
>   a rename would be an unvalidated data migration across independent release
>   trains. Accepting both spellings costs one fallback.
>
>   What is declared and what runs are still different things. `host_setup` on a
>   `RunConfig` is **hashed into the [host key](#one-config-not-two--and-a-derived-host-key)
>   but never executed** — the daemon runs the `host_setup` in its own config at
>   boot. `run_setup` has no execution path at all yet. So both fields today
>   affect *placement*, not behaviour.

## One config, not two — and a derived host key

The obvious move is to split `RunConfig` into a `HostConfig` and a `RunConfig`,
because the seam is already in the code: the docstring joins two things with the
word "plus" — *"per-machine launcher kwargs (`instance_type`, `partition`, …)
**plus** the runtime-side knobs"* — and `_RUNTIME_FIELDS` is a hand-maintained
set commented "not forwarded to the launcher."

**That is the wrong conclusion, and ephemerality is why.** If a host that does
not match can simply be relaunched, then a host configuration is not a peer of
the run configuration. It is a *consequence* of it. Nobody should be writing one.

So: **one declaration, written by the author. The host requirement is derived
from it.**

| | Written by | What it is |
| --- | --- | --- |
| **Run declaration** | Whoever writes the function — increasingly an agent | `image`, `resources`, `env`, `timeout_s`, `runner`, `host_setup`, `run_setup`, `source` / `target` / `mounts` |
| **Host key** | Nobody — computed | A hash of the subset that affects placement. Two runs with the same key can share a worker; a different key means launch |
| **Fleet policy** | Set once, outside the code being written | `providerRef`, `elasticity`, `min` / `max`, what instance types are permitted at all. Lives on the [queue](/lakeshore/queues/elastic.md) |

The middle row is the whole idea. `host_setup` does not need to live on a
separate object to be shared — it needs to be *part of the key*. Two functions
declaring the same setup hash the same and land on the same warm worker; one
that declares different setup gets its own. The boundary between "host" and
"run" stops being a typing decision and becomes a **caching decision**, which is
what it always was.

That also explains the warm/cold behaviour better than a split does.
[Preloaded functions](/lakeshore/preloaded.md) survive because the worker process
survives; the host key is exactly the predicate for "may this invocation land on
that process."

> **Note:** The classic case for splitting was that operators and authors are different
>   people with different review. When an agent writes the function, they are the
>   same hand — so the split buys no separation and costs a second object to keep
>   consistent.
>
>   That cost is the real one. `daemonTemplate` duplicating part of `RunConfig`
>   is a sync burden today; asking an agent to maintain both, in step, across
>   every generated function, is a class of drift with no upside. A derived key
>   cannot drift from the declaration it is computed from.

### The key function

"A hash of the subset that affects placement" is only useful if the subset is
written down, because three languages have to compute the same string. It is:

```
host_key = "hk1_" + base32-lower-nopad( sha256( canonical_json(subset) )[0..10] )
```

The subset is exactly seven keys, always all seven, in every case:

| Key | Type | Value when absent |
| --- | --- | --- |
| `v` | integer | Always `1` |
| `runner` | string \| null | `null` |
| `image` | string \| null | `null` |
| `resources` | object, string → int \| string | `{}` |
| `host_setup` | array of string | `[]` |
| `provider` | string \| null | `null` |
| `extras` | object | `{}` |

Canonical JSON means UTF-8, no whitespace, and object keys sorted by code point
**recursively**. **Absent, empty and null are the same input** — there is exactly
one representation of "not set," which is what makes the hash stable across three
implementations rather than merely deterministic within one. Floats are a hard
error rather than a silent coercion: `resources` values are `int` or `str`,
because IEEE-754 round-tripping through msgpack and three JSON serializers is not
something to bet a cache key on.

Two things are asymmetric on purpose. **`host_setup` order is significant** — the
array is not sorted, because running `pip install torch` before `apt-get install
ffmpeg` is a different host preparation, and a worker prepared one way must not
serve a job that declared the other. **`resources` key order is not** — it is a
mapping, so it is normalised.

The exclusions each carry a reason:

| Excluded | Why |
| --- | --- |
| `env` | Applied by the runner at exec time, per invocation. It does not change what the machine *is* — and if it did, every distinct variable would be a cold start |
| `run_setup` | Runs per invocation, before each body, by definition. A phase that runs every time cannot force a *different* host |
| `timeout_s` | A longer deadline does not need a different machine |
| `tags` | An operator concern, already matched separately by the pool spec. Folding it in would double-count |

Ten bytes is eighty bits, which is exactly sixteen base32 characters with no
padding — fixed-width, lowercase, URL-safe, and short enough to sit in a table
without wrapping. `hk1_` is a version prefix: changing the subset or the encoding
bumps it to `hk2_`, so an old key never silently means something new.

Two worked values, so an implementation can be checked against something:

```
{}                      →  hk1_ljwqko7vjw2cnyny
{"runner": "process"}   →  hk1_jjml3vzthmtzu76a
```

Python computes the key at submit — that is the only place the declaration
exists, so it is authoritative. The daemon recomputes it from the config it was
launched with and advertises it on hello and every poll. **The control plane
computes nothing**; it stores what the SDK sent, receives what the daemon
advertised, and compares two strings. A hash comparison the control plane does
not participate in cannot drift from the hash function.

Two independent implementations of the same function are the obvious risk, and the
only real mitigation is a shared fixture: one golden-vector file, copied verbatim
into every repo that implements the key, with a test in each that reads it. An
edited copy fails immediately, which turns a certainty of drift into a visible
event.

### What the split got right, and where it still applies

Two objections survive, and both are about hosts that are *not* ephemeral:

**Not every worker can be relaunched.** `providerRef: null` is the
bring-your-own-worker case — a lab machine, a SLURM allocation you already hold,
`fixed` elasticity. There the host predates the run and cannot be re-derived, so
a declaration that does not match is an error rather than a launch. The derived
key still works: it just fails to find a match instead of provisioning one.

**Cost needs a bound.** If the run declares everything, it can ask for a
`p4d.24xlarge` and nothing says no. Splitting into a `HostConfig` does not fix
that, because the same hand writes both — and when that hand is an agent, it
writes both in the same edit.

A bound only works if it lives **outside the file being edited**. That is the
queue: it already carries `providerRef` and `elasticity`, it is set once rather
than per function, and a UDF cannot widen it from the inside. Permitted instance
types belong there, next to the spend limits. The distinction that matters is
not who writes it but *what can rewrite it* — a guardrail inside the generated
artifact is not a guardrail.

> **Note:** The filter does not become a type; it becomes the **key function**. Today it
>   answers "which fields do I hide from the launcher," maintained by hand, with
>   anything unlisted silently forwarded — so a typo becomes a launcher kwarg. As
>   a key function it answers "which fields force a new host," which is a question
>   with an observable right answer: get it wrong and you either over-launch or
>   land a job on a worker that cannot serve it.

> **Warning:** `RunConfig` is one class today, `daemonTemplate` is an untyped `Json` column
>   that duplicates part of it, and there is **no derived host key** — no
>   `host_key()` in the SDK, nothing on the wire, and nothing in the claim query.
>   The elasticity controller builds a launch body from `daemonTemplate` directly.
>   Neither `host_setup` nor `run_setup` exists, and `_RUNTIME_FIELDS` is still the
>   hand-maintained filter described above, with no readers at all.
>
>   The key function, the subset and the two worked values in [The key
>   function](#the-key-function) are the specification the three implementations
>   will be written against, not a description of any of them.

## Two mechanisms, different lifetimes

| | `bootstrap_script` | Setup commands |
| --- | --- | --- |
| When | Once, at instance creation | Any time, including long after join |
| Where declared | `daemonTemplate.bootstrap_script` | `daemonTemplate.setup_scripts`, `--setup-script`, or the HTTP route |
| Re-runnable | No — new instance only | Yes, append whenever |
| Failure blast radius | The instance never joins | One command; the worker stays |

`bootstrap_script` is the cloud-init-shaped one: it belongs to the machine, not
to the queue's ongoing life. Setup commands are the opposite — a durable queue
the daemon drains, which is what makes them appendable.

> **Note:** Setup runs **per worker**, not once per queue. An elastic queue that scales to
>   eight workers runs the same install eight times, and pays it again after every
>   scale-to-zero. Anything stable belongs in `image_id`; setup is for what
>   genuinely varies per launch.

## How the FIFO drains

The queue is fire-and-forget, and the daemon pulls rather than being pushed:

```
POST …/workers/:id/setup   →  append to the worker's pending-setup FIFO
                              worker flips active → setting_up
POST /v1/daemon/poll       →  pops the head of the FIFO, one per poll
                              daemon runs it, reports back via
                              updated_capabilities on the next poll
```

The state flip is conservative. A worker in `active` moves to `setting_up`;
`pending` and `joining` are left alone because they reach `active` naturally and
will pick the commands up then, and the terminal-ish states — `draining`,
`stale`, `gone` — are never flipped silently.

`refresh_capabilities: true` is the flag that matters when the script changes
what the worker can do. Installing CUDA without it leaves the control plane
still believing the worker is CPU-only.

The `setting_up` flip is the only readiness signal a worker has today, and it
only covers setup the **control plane itself queued** — setup the daemon runs on
its own initiative is invisible to it. [Worker
lifecycle](/lakeshore/lifecycle.md#readiness-is-a-claim-not-an-inference) is where
that gap, and the phase field that closes it, are worked out.

## The interface

### Python

There is none. Setup is operator-side — declared on the queue's
`daemonTemplate` or pushed at a worker — and a `@udf` cannot request it.

### CLI

Seed setup at launch:

```bash file="terminal"
lakeshore daemon launch --queue gpu \
    --setup-script ./install-cuda.sh \
    --setup-script ./warm-cache.sh

lakeshore daemon launch --queue gpu --no-setup
```

`--setup-script` is repeatable and takes a path; the file's contents become the
command. Scripts declared in the project config under `daemon.setup_scripts` are
read first and the CLI flags append after them, so config supplies the baseline
and the flag adds to it. `--no-setup` drops both — the config-declared scripts
*and* the flags — which makes it the way to launch a deliberately bare worker.

### HTTP

```json file="POST /v1/namespaces/:ns/workers/:id/setup"
{
  "script": "apt-get install -y ffmpeg",
  "sudo": true,
  "refresh_capabilities": false,
  "name": "install-ffmpeg"
}
```

```json
202 { "commandId": "cmd_01JD2K…" }
```

A malformed body is a 400; an unknown worker id is a 404, and so is a worker in
another namespace — the same posture the daemon GET handler takes, so a probe
cannot distinguish "does not exist" from "not yours".

The companion path is the launch route, which seeds the same FIFO at creation:

```
POST /v1/namespaces/:ns/daemons/launch    { …, setup_commands: SetupCommand[] }
```

    Where `daemonTemplate` lives, and why setup cost is paid per worker.

    The other half of preparing a host — and what a jaynes mount maps onto.

    When a worker is willing to be given work, and how it says so — the phase
    the setup FIFO is really gating.

---

Source: https://docs.dreamlake.ai/lakeshore/lifecycle

# Worker lifecycle

The `phase` field, the `bye` route, the reported in-flight count, `host_key`
matching and setup-result reporting are all **built** — this page describes the
daemon you can run today. Four narrower things are still proposal; the
[Proposal callout](#what-does-not-ship-yet) at the end is the exact list.

  This page is about **workers**, not invocations — an invocation's `queued →
  running → succeeded` machine lives on the [task
  queue](/lakeshore/queues/task-queue.md#the-lifecycle) page and is a different
  thing entirely. Here: how a `nymph` daemon comes up, when it is willing to be
  given work, and what it says on the way out.

## The three machines that already exist

There is no shortage of state. A running fleet already carries three separate
machines, each answering a different question:

| Machine | Where it lives | Values | Who writes it |
| --- | --- | --- | --- |
| `Worker.state` | Control plane | `pending`, `joining`, `active`, `setting_up`, `draining`, `stale`, `gone` | The control plane, from hello, poll and terminate |
| `Worker.hostStatus` | Control plane | `pending`, `running`, `stopped`, `terminated` | The launcher — EC2, GCE, Kube — out of band |
| The daemon's run state | Inside `nymph` | `Starting`, `Polling`, `Backoff`, `Hibernating`, `Draining` | The daemon; visible only on the loopback introspect socket |

`Worker.state` is **computed on read**, not stored for its derived values: a
terminal state is never relabelled, a `hostStatus` of `stopped` or `terminated`
becomes `gone`, and a worker unheard-from for longer than the 60-second stale
window becomes `stale`. The daemon's own run state **never crosses the wire** —
`/status` binds loopback only and refuses a routable address by design, so it can
never be a remote probe.

The problem is not a missing machine. It is that the only thing crossing the wire
is **the absence of a poll**. So this design adds **one field**, and makes the
control-plane machine a projection of it. It does not add a fourth machine.

## The phase field

```ts file="DaemonPhase"
type DaemonPhase =
  | 'booting'      // pre-hello. Never observed by the control plane, by definition
  | 'setup'        // running host_setup or a setup command. Heartbeat yes, claim no
  | 'ready'        // polling and accepting work
  | 'draining'     // shutdown started. No new claims; inflight finishing
  | 'terminating'  // grace expired. About to exit

interface PollRequest {
  // …existing fields…
  phase?:    DaemonPhase   // absent on an old daemon — the CP falls back to inference
  host_key?: string        // see Host Setup → The key function
}
```

Both fields are optional in both directions on purpose. An old daemon sends
neither and behaves exactly as it does today; an old control plane ignores both.

### Projection onto `Worker.state`

| `phase` | `Worker.state` the poll handler writes |
| --- | --- |
| *absent* | Today's behaviour — `joining → active` on the first poll |
| `setup` | `setting_up` |
| `ready` | `active` |
| `draining` | `draining` |
| `terminating` | `draining` — the `bye` that follows writes `gone` |

The projection never widens the conservative state flips documented under [How
the FIFO drains](/lakeshore/host-setup.md#how-the-fifo-drains) — a reported `phase`
can move a worker the existing rules already allow to move, and nothing more.

## Readiness is a claim, not an inference

Today "ready" means "a poll arrived." Locally the daemon flips to `Polling` on
its first successful poll; on the control plane the worker flips `joining →
active` on the first poll received. Both are **liveness**, not readiness — the
daemon reaches that point before it has verified its workdir, before any declared
setup has run, and, under the derived host key, before it even knows which key it
will advertise.

The daemon has no way to say *I am up, keep counting me alive, but do not give me
work.* It cannot withhold the poll, because withholding the poll is how it dies.

`phase: setup` is exactly that sentence: **heartbeat yes, claim no.** The poll
handler skips the claim and returns an empty command list.

This matters the moment `host_setup` is [derived from a
`RunConfig`](/lakeshore/host-setup.md#one-config-not-two--and-a-derived-host-key)
rather than pushed by the control plane. The existing guard short-circuits the
claim loop only when the control plane's *own* pending-setup FIFO is non-empty —
it protects setup the control plane queued. A `host_setup` the daemon runs on its
own initiative is invisible to that guard, so without `phase` the worker is
handed work mid-install.

It is deliberately **not** an authorization boundary. A buggy or hostile daemon
can assert a `ready` it has not earned. That is still strictly better than the
status quo, where nothing is asserted at all and readiness is inferred from a TCP
round-trip.

## The state machine

```
                     (process start)
                            │
                     ┌──────▼──────┐
                     │   booting   │  config load, host detection,
                     └──────┬──────┘  introspect bind — no wire contact
                            │  POST /v1/daemon/hello  (bounded retry)
             ┌──────────────┴──────────────┐
             │ rejected, or retries        │ 200 → worker_id
             ▼ exhausted                   ▼
         (exit 1)                    ┌───────────┐
                                     │   setup   │  host_setup, and the
                     ┌──────────────▶│           │  control-plane setup FIFO
      a setup command│               └─────┬─────┘  CP: setting_up, no claims
      arrives        │                     │  FIFO empty && workdir writable
                     │                     ▼
                     │               ┌───────────┐
                     └───────────────┤   ready   │  claims and runs work
                                     │           │  CP: active
                                     └─────┬─────┘
                                           │
        ┌──────────────────────────────────┼──────────────────────────────┐
        │ SIGTERM / SIGINT                 │ keep_alive_s elapsed         │
        │                                  │            CP drain command  │
        └──────────────────────────────────┼──────────────────────────────┘
                                           ▼
                                     ┌───────────┐
                                     │  draining │  poll loop stopped; inflight
                                     │           │  finishing inside grace_s
                                     └─────┬─────┘  CP: draining
                                           │  grace expired, work still running
                                           ▼
                                   ┌──────────────┐
                                   │ terminating  │  SIGTERM to children, wait
                                   └──────┬───────┘  kill_after_s, then SIGKILL
                                          │  POST /v1/daemon/bye  (best effort)
                                          ▼
                                      (exit 0)       CP: gone
```

`booting` is never observed remotely — by definition, the daemon has not spoken
yet. Everything else is a phase the control plane can read off a poll.

## Termination — four cases, one rule

**The daemon reports every exit it chooses; the control plane infers every exit
that is done to it.**

That one sentence decides the whole matrix. An idle exit, a signal and a
commanded drain all leave the daemon alive enough to speak, so it speaks. A spot
reclaim, a crash and a partition do not, so the control plane is left to notice.

| Case | Who knows first | Daemon reports | Control plane mechanism | Worst-case detection |
| --- | --- | --- | --- | --- |
| Idle exit (`keep_alive_s` elapsed) | The daemon | `bye{reason: "idle"}` | — | Immediate |
| SIGTERM / SIGINT | The OS | `bye{reason: "signal"}` | Falls back to `stale` if the POST fails | Immediate, else 60 s |
| Control-plane drain | The control plane | `phase: draining`, then `bye{reason: "drain"}` | It issued the command | Immediate |
| Launcher terminate / spot reclaim | The launcher | **Nothing.** The power is gone | `hostStatus → terminated` ⇒ `gone` | Next host poll, else 60 s |
| Crash, OOM, kernel panic | Nobody | Nothing | `stale` | 60 s |
| Network partition | Nobody | Nothing — the POSTs fail too | `stale` | 60 s |

The last three rows are why `bye` is **not a reliability mechanism**. The
60-second stale timeout stays exactly as it is and remains the backstop for every
case. `bye` is a **latency** mechanism: it turns a 60-second ambiguity into a
zero-second certainty for the three cases where the daemon is still able to
speak. Nothing here is allowed to depend on the message arriving.

## `POST /v1/daemon/bye`

```json file="POST /v1/daemon/bye"
{
  "worker_id": "wrk_01JD2K…",
  "reason": "signal",
  "inflight_abandoned": 0
}
```

```
204 No Content
```

`reason` is one of `idle`, `signal`, `drain`, `hello_failed`. The control plane
sets `state: "gone"` and `lastSeenAt: now`, and does nothing else.

The constraints on the client side are the interesting part, and they are
non-negotiable:

- **One attempt, two-second timeout.** A failure is logged at `debug` and
  ignored.
- **It never delays exit.** A shutdown that hangs because it was being polite is
  worse than the ambiguity it was trying to remove.
- **It is sent after the drain returns**, so `inflight_abandoned` is a real
  number rather than a guess.

## What crosses the wire

| Call | When | Carries | What it changes |
| --- | --- | --- | --- |
| `POST /v1/daemon/hello` | Once, at boot | `machine_id`, `label`, `tags`, `lanes`, `capabilities`, `versions`, **`host_key`** | Creates or updates the `Worker` row; `state = joining` |
| `POST /v1/daemon/poll` | Every cycle | `worker_id`, `queue`, `timeout_s`, `invocations`, **`phase`**, **`host_key`**, `updated_capabilities` including **`current_invocations`**, **`setup_results`** | Bumps `lastSeenAt`; sets `state` from `phase`; updates capabilities; gates the claim on `phase` and `host_key` |
| `POST /v1/daemon/ack` | Once per run | `invocation_id`, `state`, `result_blob`, `error`, `worker_id` | The invocation reaches a terminal state |
| `POST /v1/daemon/bye` | Once, at exit | `worker_id`, `reason`, `inflight_abandoned` | `state = gone`, `lastSeenAt = now` |

`current_invocations` is the row with a consequence outside this page: it is what
closes the structurally-zero utilization gap described under [Scale to
zero](/lakeshore/queues/elastic.md#scale-to-zero-and-the-cold-start-it-buys).
Sending the count on every poll closes it without a control-plane change,
because the five call sites already read the key.

The same count fixes a second bug for free. The daemon tracks in-flight work in
four different places and only one of them covers `exec` as well as `run`, so a
worker busy with a long `exec` can look idle and time itself out mid-job. One
counter, incremented at both dispatch sites, is what the idle gate should have
been reading all along.

> **Note:** The alternative was a new sibling field on the poll. Reusing
>   `updated_capabilities` needs **zero** control-plane change — that key is already
>   consumed and already written through to the worker row. The price is one
>   redundant field write per poll, on a document that is already written every poll
>   to bump `lastSeenAt`.

## The interface

### Python

The hooks run **on the worker**, not on the submitter — they are the daemon-side
half of the [run declaration](/lakeshore/host-setup.md).

```python file="lifecycle_upload.py"
import dreamlake.lakeshore as dls

MODEL: dict[str, object] = {}

@dls.lifecycle.on_host_setup          # once per worker process, before the first body
def warm() -> None:
    MODEL["weights"] = load("checkpoint.pt")

@dls.lifecycle.on_run_setup           # before every body, in the invocation workdir
def prep() -> None:
    scratch.mkdir(exist_ok=True)

@dls.lifecycle.on_shutdown            # inside the grace window — flush, then return
def flush() -> None:
    dls.run.publish("./out", name="checkpoint")

dls.lifecycle.phase()      # 'setup' | 'ready' | 'draining'
dls.lifecycle.host_key()   # 'hk1_…' — the key this worker was configured with, or None
```

The hooks take **no arguments**. There is no context object: a hook reads and
writes ordinary module state — a global, an open handle — which is exactly the
thing a shell `host_setup` cannot hand to the next body. Environment and working
directory come from the `RunConfig`, not from a parameter.

`phase()` returns a **three-value subset** of the five-value `DaemonPhase` on the
wire. `booting` and `terminating` have no Python spelling by construction: the
interpreter is not running yet during `booting`, and by `terminating` the grace
window has already expired, so no hook is still entitled to run.

`on_host_setup` and `on_run_setup` are the two phases named on the [host
setup](/lakeshore/host-setup.md#naming-the-phases) page, reachable from Python
rather than from a queue template. `on_shutdown` runs inside the grace window and
must return before it expires — a hook that outlives the grace is killed with
everything else, which is the whole reason the escalation ends in SIGKILL. The
runnable version of all three, including the upload, is
`examples/lifecycle_upload.py` in `lakeshore-py`.

## What does not ship yet

> **Warning:** `phase`, `host_key`, `current_invocations`, `setup_results` and
>   `POST /v1/daemon/bye` are all on the wire, and `claimOne` filters on the host
>   key. Four things on or adjacent to this page are still design only:
>
>   - **Nothing launches on an unmatched host key.** Matching ships: a worker
>     advertising a different key is not handed the invocation. But an invocation
>     whose key matches *no* live worker simply stays queued — provisioning one is
>     the next slice.
>   - **A `RunConfig`'s `host_setup` is hashed but never executed.** The daemon
>     runs the `host_setup` in *its own* config at boot, and hashes the one in an
>     incoming run config into the key it matches against — so a declared
>     `host_setup` selects a host that already has it, and never installs it. Only
>     `run_setup` is executed from a run config, per invocation, before the body.
>   - **`ExecBody` carries no `run_config`**, so the `exec` path — what the CLI and
>     SDK drive today — has no host key and no placement story.
>   - **Setup failures are logged, not tabulated.** A non-success is written to the
>     control plane's log and the most recent one is kept on the worker row; there
>     is no per-command status table to read a history out of.

    What runs before a worker takes work, and the derived host key that decides
    which worker it may be.

    Where the utilization number is read, and why it currently understates load.

    Run a daemon on your own machine and watch these phases happen.

---

Source: https://docs.dreamlake.ai/lakeshore/private-runs

# 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.

---

Source: https://docs.dreamlake.ai/pipelines

# Pipeline Functions

  A DreamLake pipeline is a Python module. A static tracer reads its **source**
  and derives a typed DAG from it — it never imports the module and never
  executes a line of it. That is why every UDF body in every example on these
  pages is `...` and traces perfectly well. The graph is the artifact; there is
  no run.

The tracer parses the file, treats each `@ls.udf` function as a node template,
walks the body of the one `@dl.pipeline` function statement by statement, and
tracks the *provenance* of every local variable — the set of nodes its data
descends from. Calling a UDF creates a node and an edge from each argument's
provenance. Method calls, subscripts and operators create no nodes at all; they
pass provenance through. Everything the graph knows, it knows from syntax.

> **Warning:** The authoring API described in this section is not implemented in shipped
>   Python. The `dreamlake` package exports no `pipeline`, no `node`, no `batch`,
>   no `stream`, no `to_dataset` and no `requeue`. The real signature of
>   `lakeshore.udf` is `udf(fn=None, *, queue=None, transport="auto",
>   config=None)` — it takes no `kind=` argument. `kind` is a convention the
>   **tracer** reads out of the decorator's keyword arguments, and it never
>   reaches the runtime. `lakeshore.types` — `Mask`, `String`, `Tensor`, `Tuple` —
>   does not exist, and the canonical import for the real package is
>   `import dreamlake.lakeshore as dls`, not `import lakeshore as ls`.
>
>   The honest conclusion: these `.py` files are a **specification format that
>   happens to be Python syntax**. They trace because the tracer never imports or
>   executes anything. Read every page in this section as the shape the graph
>   takes, not as code you can run today.

Here is the smallest complete pipeline — a source, a transform and a sink —
exactly as the tracer lays it out. The figure below is the real
`` component from `@dreamlake/uikit`, not a picture of one:
drag a card, scroll to pan, hold ⌘ or ctrl and scroll to zoom.

## The node and edge schema

The tracer emits JSON, the server stores it on a `PipelineVersion`, and the
renderer consumes it. These are the server-side wire types, verbatim:

```ts
interface NodeDef {
  id: string
  title: string
  kind: string
  inputs: string[]
  outputs: string[]
  columns: string[]
  code: string
  config: Record<string, unknown>
  pos: { x: number; y: number }
}

interface EdgeDef {
  from: string
  fromPort: string
  to: string
  toPort: string
  kind: 'data' | 'mask'
}

interface GraphObject {
  id: string
  title: string
  subtitle: string
  nodeCount: number
  nodes: Record<string, NodeDef>
  edges: EdgeDef[]
}
```

Read the fields against the Python they come from. `inputs` are the UDF's
parameters, one port each. `outputs` is a *single* port, `['out']`, because a
UDF returns one table and passing that table downstream passes the whole thing
— a sink, which returns nothing, has `[]` instead. `columns` is the schema of
that one output, taken from the return annotation, and is emphatically not a
list of ports. `config` is the decorator's keyword arguments verbatim, which is
where `kind` lives. `pos` comes from a longest-path layering the tracer runs
after the walk, at a pitch of 208 px per layer and 108 px per row.

Two differences separate `GraphObject` from the `PipelineGraphData` the
renderer wants, and both are bridged client-side in `toGraphData()`:

- The server graph has **no top-level `code`**. It is filled in from the
  pipeline's `sourceCode` field, which is stored beside the graph rather than
  inside it.
- Server `NodeDef` has **no `status`**. Runtime state lives in a separate
  `NodeState` record, so the static view is entirely `idle` until a runtime
  overlay is wired in. Every figure in this section is therefore idle, and that
  is not a stylistic choice — it is what a traced graph actually contains.

## Node kinds

`kind` is cosmetic in the renderer — it drives the card's category dot — but it
is load-bearing in the tracer, because two of the kinds change what the node
*is*. Not every kind the renderer paints is a kind the tracer can produce:

| Kind | How it arises | What it changes |
| --- | --- | --- |
| `source` | `@ls.udf(kind="source")` — no parameters, has a return annotation | `inputs: []`, `outputs: ['out']`. Its outgoing edges are excluded from merge inference |
| `sink` | `@ls.udf(kind="sink")` — has parameters, **no** return annotation | `outputs: []`. The graph's terminal |
| `review` | `@ls.udf(kind="review")` returning `Mask[…]` | Nothing structurally, but the result is used as a selector, so its outgoing edge is a dashed **mask** edge |
| `merge` | **Inferred** when a plain UDF has two or more non-source `data` inputs, or set explicitly | Purely cosmetic — fan-in is already visible in the edges |
| `transform` | The default for a plain UDF with fewer than two stage inputs | Nothing |
| `model` | **Renderer-only.** The tracer never emits it today | — |
| `filter` | **Renderer-only.** The tracer never emits it today | — |

Merge inference is narrower than it first looks. Only `data` edges count toward
the fan-in, and inputs drawn from a `source` node are excluded — a side input
such as a prompt table should not turn an ordinary stage into a merge. An
explicit `kind=` on the decorator always wins over inference.

> **Note:** `dreamlake-server`'s own copy of the node type narrows `kind` to
>   `'source' | 'transform' | 'sink'`, dropping `review` and `merge` — both of
>   which the tracer emits and the renderer paints. The values survive the round
>   trip because the field is serialised as JSON, but the server's type is
>   wrong about its own data. Widening it is recorded as a hand-off.

## Two edge kinds

An edge carries no runtime style — its flow animation is derived at render time
from the status of its two endpoint nodes — but it does carry one static tag,
and the tag means something precise:

- **`data`** (solid) — the value flows through. The target receives the
  source's table.
- **`mask`** (dashed) — the source only **gates** or filters the target. It is a
  review veto, a confidence threshold, a boolean selector. No table crosses
  this edge; a decision does.

A mask tag is produced by position, not by declaration. When the tracer
evaluates a subscript such as `labels[consensus]`, it evaluates the *slice*
with the mask role, so everything `consensus` descends from reaches the target
tagged `mask` while `labels` reaches it tagged `data`. That single rule is what
makes review and consensus edges render as dashed gates without anyone
annotating them.

The promotion rule matters when both tags reach the same edge, which happens
whenever one node feeds another twice — once as a value and once as a selector.
**`data` dominates `mask`.** The edge is drawn solid, because a table really is
crossing it, and the gating relationship is already implied. There is exactly
one edge per `(from, fromPort, to, toPort)` key; the second contribution merges
into the first rather than drawing a parallel line.

## Trust the pipeline; fail loudly

Any undecorated function call inside a `@dl.pipeline` body **raises at trace
time**. Not a warning, not a passthrough node, not a silent skip — the trace
fails and the CLI exits non-zero:

```text
pipeline calls undecorated function 'normalize' — every function called in a
@dl.pipeline must be a @ls.udf / @dl.node (wrap framework helpers like
to_dataset/requeue in a udf)
```

This is a deliberate design choice and it is the reason the graph can be
trusted. If unknown calls passed through quietly, the rendered DAG would be a
partial picture of the program, and the one thing worse than no graph is a
graph that silently omits a stage. So there are no hidden framework helpers:
`to_dataset` and `requeue` do not get a special case, they get wrapped in a
`kind="sink"` UDF like everything else.

There is exactly **one** exemption. A `for`-loop's iterator — `batch(src, n=64)`
or `stream(...)` — is evaluated leniently: it adds no node, and it passes the
iterated source's provenance straight to the loop variable. Structural
iteration is not a stage, so it is not required to be a UDF. The loop *body* is
strict again, and UDF calls nested inside it become nodes exactly as they would
outside. See [Batching](/pipelines/batching.md) for what the exemption does and
does not cover.

## How to trace one

Locally, against the source file, with no server involved:

```bash
python -m dl_trace pipelines/image_object_annotation.py --pretty
```

To push it, so the server traces it and stores the graph on a version:

```bash
dreamlake pipeline create <name> --file pipelines/image_object_annotation.py
```

> **Warning:** `dreamlake pipeline create` does not run `dl_trace`. The server dispatches to
>   an external parser at `PIPELINE_PARSER_URL`. If that variable is unset it
>   falls back to a regex mock that matches only a bare `@ls.udf` line — not
>   `@ls.udf(kind="source")`, not `@dl.node` — and returns `inputs: []` and
>   `edges: []`. The result is an empty graph that looks like a successful push.
>   Real graphs require the external `dl_trace` service to be configured.

## The nine constructs

One page per construct, each with its own live node view.

    The one entry point. What the decorator marks, why there is exactly one per
    module, and what the walk does with the body.

    Ports from parameters, columns from the return annotation, and the
    decorator kwargs that end up in `config`.

    Where data enters and leaves — `kind="source"`, `kind="sink"`, and the
    wrapped `to_dataset` / `requeue` helpers.

    The default kind, and the fan-in rule that infers `merge` at two or more
    non-source data inputs.

    Gates, `Mask[…]` returns, and the mask algebra `~ & | ^` as edge tags
    rather than nodes.

    Tapping data off the main stream with a mask subscript — and where the real
    statistical samplers actually live.

    `batch()` and `stream()` — the single exemption from the decoration rule,
    and its exact boundary.

    `if` / `else`, `for`, comprehensions — what the tracer keeps, and the two
    named fidelity losses.

    The canonical model API — a contract the pipelines are written against, not
    working code.

---

Source: https://docs.dreamlake.ai/pipelines/pipeline

# `@dl.pipeline`

  A pipeline file contains many decorated functions, but exactly one of them
  is the pipeline. `@dl.pipeline` marks it. Its signature is fixed — a plain
  `def` that takes no parameters — because everything the graph knows comes
  out of the body, and nothing comes in from the outside.

## The signature

```python
@dl.pipeline
def camera_pose_trajectory():
    ...
```

That is the whole contract. No arguments, no return value that matters, no
configuration object. The function name becomes the pipeline's `id` and
`title`; its first docstring line, if it has one, becomes the `subtitle`.

The zero-argument rule is not a stylistic preference. A pipeline gets its input
by *calling a source* — a UDF declared `kind="source"` — so there is nothing for
a parameter to carry. If the pipeline took an argument, the tracer would have to
invent a synthetic upstream node with no source text behind it, and the graph
would contain a node that corresponds to no line of code.

## How the tracer finds it

The tracer scans the module's top-level statements for function definitions and
looks at each one's decorator list. For every decorator it takes **the attribute
name and nothing else**:

- `@dl.pipeline` → `pipeline`
- `@dreamlake.pipeline` → `pipeline`
- `@anything.pipeline` → `pipeline`
- `@pipeline` → `pipeline`

The recognised set is the single-element set `{"pipeline"}`. All four spellings
above are equally valid, and there is no way to configure a different name.
A decorator written as a call — `@dl.pipeline(...)` — resolves the same way,
and its keyword arguments are collected but currently unused. (The parallel set
for node decorators is `{"udf", "node"}`; see [`@ls.udf`](/pipelines/udf.md).)

Nothing is imported and nothing is resolved. The tracer never asks where `dl`
came from, whether it is a module or a local variable, or whether the attribute
exists. The corollary is the useful part: **a pipeline file does not need a
working `dreamlake` install to trace.** A file whose imports would all fail at
runtime produces exactly the same graph as one whose imports resolve, because
the import lines are never executed and the names in them are never looked up.

Two consequences worth stating outright:

- **The first match wins.** If a file defines two `@dl.pipeline` functions, the
  second one is silently ignored — it is not an error and it does not merge.
- **Top level only.** The scan walks the module body, not nested scopes. A
  `@dl.pipeline` function defined inside another function or inside a class is
  invisible, and the trace fails with *"no `@dl.pipeline` function found in
  source"*.

## No import, no exec

The tracer parses the file's AST. It never imports the module and it never
executes a single line of it.

This is why every UDF body in every shipped example is a bare `...` and the
graph still comes out complete. The body of a stage contributes nothing to the
graph: the input ports come from the parameter list, the output schema comes
from the return annotation, and the edges come from the *call sites* inside the
pipeline body. A stage that has not been written yet traces identically to one
that has, so the graph is available from the first draft of the file.

The consequence for authors runs the other way, and it is worth being blunt
about. A pipeline file is checked by **parsing**, not by running. A syntax error
fails the trace loudly. A type error inside a UDF body, a misspelled attribute,
an import that does not exist, a call that would raise — none of these are
caught here, and none of them will ever be caught here. The trace tells you the
shape of the graph. It tells you nothing about whether the code works.

## A complete pipeline, and the graph it derives

Here is a short pipeline end to end. Four stages, a source and a sink among
them, wrapped in a batching loop:

```python file="pipelines/camera_pose_trajectory.py"
import dreamlake as dl
import lakeshore as ls
from dreamlake import batch, requeue, to_dataset
from lakeshore.types import Tensor, Tuple, Mask


@ls.udf(kind="source")
def load_frames() -> Tuple["frames", "intrinsics"]: ...


@ls.udf
def estimate_pose(frames, intrinsics) -> Tuple["pose", "confidence"]: ...


@ls.udf
def fit_trajectory(poses) -> Tuple["traj", "residual"]: ...


@ls.udf(kind="sink")
def save_trajectory(rows):
    to_dataset(rows)


@dl.pipeline
def camera_pose_trajectory():
    src = load_frames()
    for items in batch(src, n=8):
        poses = estimate_pose(items.frames, items.intrinsics)
        traj = fit_trajectory(poses)
        save_trajectory(traj)
```

      the graph <code>@dl.pipeline</code> above derives — no run required. The{' '}
      <code>for items in batch(src, n=8)</code> line produced no node.
    </>
  }
/>

Drag a card, scroll to pan, ⌘/ctrl-scroll to zoom. This is the real renderer
reading a real trace fixture, not a picture of one.

Four things in that graph are worth reading off deliberately:

- **The `for` loop left no trace.** `batch(src, n=8)` sits in a loop iterator
  position, where the tracer relaxes its decoration rule and passes the
  argument's provenance straight through. `items` inherits whatever `src`
  descended from, and no node appears. Loops never unroll either — the body is
  walked exactly once, so a loop over eight batches still yields one
  `estimate_pose`. See [batching](/pipelines/batching.md) and
  [control flow](/pipelines/control-flow.md).
- **Two edges run into `estimate_pose`, not one.** An edge is keyed on
  `(from, fromPort, to, toPort)`, and the two arguments land on two different
  input ports. `items.frames` and `items.intrinsics` are attribute reads, which
  are not nodes — they carry the provenance of `items` and therefore both point
  back at `load_frames`.
- **`estimate_pose` is still a `transform`.** Two inbound data edges would
  normally infer the `merge` kind, but edges arriving from a `source` node are
  excluded from that count, so a stage fed entirely by its source stays a plain
  transform. See [transform and merge](/pipelines/transform-and-merge.md).
- **`save_trajectory` has no output port.** It has no return annotation, and
  that absence *is* the definition of a terminal — one input port, zero output
  ports, an empty column list.

## One entry point per file

The tracer walks the decorated function and only the decorated function.
Everything else in the file is a *definition* until the pipeline body reaches
for it.

Helper functions defined alongside the pipeline are therefore traced only when
the pipeline body calls them, and calling one is only legal if it carries a node
decorator. Every call the walk encounters must resolve to a `@ls.udf` or
`@dl.node`; an undecorated call raises rather than passing silently through:

> pipeline calls undecorated function `normalise` — every function called in a
> `@dl.pipeline` must be a `@ls.udf` / `@dl.node` (wrap framework helpers like
> `to_dataset`/`requeue` in a udf)

Failing loudly is the deliberate choice. Passing an unknown call through would
produce a graph that is quietly missing a stage, and a derived graph that omits
work is worse than no graph at all. The one exemption is the loop-iterator
position described above, which exists precisely so `batch(...)` and
`stream(...)` do not have to be pretend stages.

Method calls, subscripts, and operators are not calls in this sense — they pass
provenance through without creating a node, which is what makes
`traj[ok]`-style gating render as an edge tag rather than a box.

> **Warning:** `@dl.pipeline` does not exist in shipped Python. The `dreamlake` package exports
> no `pipeline`, `node`, `batch`, `stream`, `to_dataset`, or `requeue`.
>
> `lakeshore.udf`'s real signature is
> `udf(fn=None, *, queue=None, transport="auto", config=None)` — there is **no
> `kind=`** parameter. `kind` is read by the *tracer* out of the decorator's
> keyword arguments and never reaches the runtime. `lakeshore.types` does not
> exist either, and the canonical import for the real package is
> `import dreamlake.lakeshore as dls`, not `import lakeshore as ls`.
>
> None of that stops the example above from tracing, and the reason is the whole
> point of this page: these files are a **specification format that happens to be
> Python syntax**. They trace precisely because nothing is ever imported.

---

Source: https://docs.dreamlake.ai/pipelines/udf

# `@ls.udf`

  `@ls.udf` marks one stage of a pipeline. One decorated function, called once
  in the pipeline body, is one node on the canvas. Everything else about the
  node — its ports, its output schema, its colour — is read off the function's
  signature.

A pipeline module is a flat list of decorated stage functions plus one
`@dl.pipeline` function that calls them. The stage functions are the
vocabulary; the pipeline body is the wiring. Nothing about the node is
configured separately from the `def` — there is no node manifest, no port
declaration, no schema file. The signature **is** the declaration, which is why
a stage whose body is still `...` traces into a complete, correctly-ported node.

## How the tracer finds it

The tracer matches on the **decorator attribute name, and nothing else**. The
recognised set is exactly `{"udf", "node"}`, compared against the last
dotted segment of the decorator expression. So all of these mark a stage:

```python
@ls.udf
@dl.node
@lakeshore.udf
@anything.at.all.udf
```

Nothing is imported and nothing is executed to determine this. The tracer parses
the file with `ast`, reads the decorator list of every top-level `def` (and
`async def` — the two are treated identically), and takes the attribute name. It
never resolves `ls` to a module, so the alias you use is free and the import
line is decoration for the human reader.

That is a deliberate trade. It means an unrelated helper of yours decorated
`@cache.node` is silently picked up as a stage; it also means the tracer works on
a file whose dependencies are not installed, which is the property the whole
"graph before implementation" story rests on.

## Parameters are ports; the return annotation is columns

This is the one rule worth memorising, and it is the one that surprises people.

- **The input ports of a node are exactly the function's parameters, in order.**
  Positional-only, ordinary positional and keyword-only parameters all count, in
  that order, and each port carries its parameter's name. A call site's
  positional arguments bind to ports left to right; keyword arguments bind by
  name. `*args` and `**kwargs` produce no port — a variadic stage has no
  addressable input, so there is nothing for an edge to land on.
- **There is exactly ONE output port, and it is named `out`.** The names in the
  return annotation are *not* extra output ports. They are the `columns` of that
  single output — the schema of the table the stage produces.

The second half is the part that trips readers who arrive from a port-graph
system like Kubeflow or Flyte. A UDF returns **one table**. Passing its result
downstream passes the whole table, not a column of it. Three names in the return
annotation therefore mean *one edge carrying three columns*, never three edges.

How the annotation is read:

| Return annotation | Resulting `columns` |
| --- | --- |
| `Tuple["a", "b"]` | `['a', 'b']` — the string literals, in order |
| `Mask["R", "N"]` | `['mask']` — a single column named after the base type, lowercased |
| `Tensor["N", "H", "W", 3]` | `['tensor']` — likewise, one column |
| *(no return annotation)* | `outputs: []`, `columns: []` |

Only `Tuple` spreads its subscript into column names. Any other subscripted base
collapses to one column named after the base type, lowercased — the subscript is
read as a shape, not as a schema, so `Mask["R", "N"]` is one mask column over an
R×N grid rather than two columns called `R` and `N`.

The last row is a mechanical rule, not a convention:

> A node has an output port **if and only if** the function carries a return
> annotation.

The tracer's test is literally `fn.returns is not None`. Delete the `->` and the
node loses its output port. The presence of the arrow is what is checked, not
what follows it — an annotation the reader cannot turn into names, `-> None`
included, still yields an `out` port, just one with an empty column list. This
is what makes a node terminal, and it is why the sink stages in the example
pipelines are written with no return annotation at all rather than relying on
`kind="sink"` to end the flow.

Both figures are the real `` renderer over hand-written
`PipelineGraphData` in the exact shape the tracer emits. Drag a card; scroll to
pan.

The subtitle line on each card is `kind · inputs→outputs`, and it is worth
reading twice. `detect_objects` annotates three return names and still reads
`2→1`, because the three names are columns of the one output, not outputs. The
card carries at most one dot per face for the same reason — a dot is an edge
anchor, not a port, and every edge leaving a stage leaves from the one `out`
port. `save_dataset` has no right-hand dot at all, because it has no output port
for an edge to start from. The column names live in the node data, where the
inspector and any downstream schema check read them.

## The code

```python
@ls.udf
def detect_objects(images: Tensor["N", "H", "W", 3], prompts: String["N"]) -> Tuple["boxes", "classes", "confidence"]:
    """Detect objects in each image; one row per box."""
    ...

@ls.udf(kind="sink")
def save_dataset(rows):
    to_dataset(rows)
```

The parameter annotations `Tensor[...]` and `String[...]` are read by nobody.
The tracer takes the parameter *names* for the ports and ignores the argument
annotations entirely; only the **return** annotation is parsed. They are there
for the human and for a future type checker.

## The `kind` argument

`kind=` selects the node's role and, on the canvas, its colour. It is read out
of the decorator's keyword arguments by `ast.literal_eval`, so it must be a
literal string.

| `kind=` | Meaning | Colour |
| --- | --- | --- |
| `"source"` | a terminal at the head of the graph — the stage that produces data rather than consuming it | green |
| `"sink"` | a terminal at the tail — writes out, requeues, or otherwise ends the flow | red |
| `"review"` | a human-in-the-loop stage; conventionally returns a `Mask[...]` | purple |
| `"merge"` | fan-in. Rarely written by hand — **inferred** for any untagged stage with two or more distinct data producers feeding it | warm gray |
| `"transform"` | the default. Any untagged stage with fewer than two data producers | blue |

Inference runs only on stages that did **not** pass a `kind=`: an explicit kind
always wins, and `source` / `sink` nodes are never re-classified. The inference
counts only `data` edges, and it ignores inputs drawn from a `source` node — so
a side input such as a prompt list does not turn an ordinary stage into a merge.

`model` and `filter` also exist in the renderer's colour map (purple and amber
respectively), and a `kind="model"` string would be passed through to the card
verbatim. But no canonical example uses either one, and the inference step never
produces them — the only kinds it can assign are `merge` and `transform`. Treat
them as reserved rather than as part of the vocabulary.

See [Sources and sinks](/pipelines/sources-and-sinks.md) for the two terminals,
[Review and masks](/pipelines/review-and-masks.md) for what a `review` stage's
`Mask` return does to the edges leaving it, and
[Transform and merge](/pipelines/transform-and-merge.md) for the inference rule in
full.

## Calling it twice makes two nodes

A UDF is a template, not an instance. Calling it N times in the pipeline body
yields N distinct nodes, each with its own generated id: the first call keeps
the function's name, and every call after that gets a numeric suffix.

```python
@dl.pipeline
def dual_annotate():                     # every stage called here is an @ls.udf
    src = load_clips()
    a = semantic_match(src, prompts_a)   # node id: semantic_match
    b = semantic_match(src, prompts_b)   # node id: semantic_match_2
    reconcile(a, b)                      # node id: reconcile
```

The `title` on every one of those nodes stays `semantic_match` — the suffix
lives only in the id, so the canvas shows two identically-named cards rather
than a card called `semantic_match_2`. Fan-out and fan-in therefore both survive
into the graph as real structure: `src` feeds two nodes, and `reconcile` has two
distinct data producers, which is exactly the condition that makes it an
inferred `merge`. See [Transform and merge](/pipelines/transform-and-merge.md).

## Every call must be decorated

Any undecorated function call inside a pipeline body **raises at trace time**.
There are no hidden framework helpers and no passthrough for unknown names:

```
ValueError: pipeline calls undecorated function 'to_dataset' — every function
called in a @dl.pipeline must be a @ls.udf / @dl.node (wrap framework helpers
like to_dataset/requeue in a udf)
```

The reason is that a silent passthrough would produce a graph that is quietly
wrong — a stage's data would appear to come from its grandparent, with the
missing step invisible. Failing loudly is the only honest option for a tracer
that cannot see inside the functions it is reading.

There is exactly one exemption: the **iterator expression of a `for` loop**.
`for items in batch(src, n=64):` evaluates leniently, so `batch` needs no
decorator; it adds no node and simply passes its arguments' provenance to the
loop variable. The loop *body* is strict again. See
[Batching](/pipelines/batching.md).

The counterexample that trips people is the opposite one — several things that
look like calls are not calls in this sense, and create no node at all:

| Expression | What happens |
| --- | --- |
| `review.all(axis=0)` | a **method** call — provenance of the receiver passes through |
| `labels[mask]` | a subscript — the value's provenance passes through; the *slice's* provenance is tagged `mask` |
| `a & b`, `a \| b`, `a ^ b` | binary operators — both sides' provenance is merged |
| `~m` | a unary operator — the operand's provenance passes through |
| `poses.confidence > 0.5` | a comparison — merged, like a binary operator |

So the mask algebra is edge tagging, not nodes. That is deliberate: a consensus
computed with `review.all(axis=0)` is a property of the review stage's output,
not a separate stage someone has to schedule. See
[Review and masks](/pipelines/review-and-masks.md).

> **Warning:** Everything above describes what the **tracer** reads. It is ahead of the shipped
> Python in three specific ways, and not one of the import lines in the examples
> on this page resolves against a released package today.
>
> The shipped decorator's real signature is
> `udf(fn=None, *, queue=None, transport="auto", config=None)`. It accepts **no
> `kind=` argument**. `kind` is notation the tracer reads out of the decorator's
> keyword arguments during a static parse; it never reaches the runtime, and
> passing it to the real `udf()` is a `TypeError`.
>
> `lakeshore.types` — the module the examples import `Mask`, `String`, `Tensor`
> and `Tuple` from — does not exist. The annotations are parsed as syntax and
> never resolved, which is the only reason the examples trace.
>
> The canonical import for the real package is `import dreamlake.lakeshore as dls`,
> not `import lakeshore as ls`. The `ls` alias in every example on this page is
> chosen for readability, and the tracer's name-only decorator matching is what
> makes it work regardless.
>
> Read the example `.py` files as a specification format that happens to be valid
> Python syntax, not as runnable code.

---

Source: https://docs.dreamlake.ai/pipelines/sources-and-sinks

# Sources and Sinks

  Every pipeline has at least one root and at least one terminal. Neither is a
  special kind of object — both are ordinary UDFs, and the tracer tells them
  apart by their shape alone.

A **root** is a node nothing flows into. A **terminal** is a node nothing flows
out of. In a lot of dataflow frameworks those are separate classes with their
own base types, their own registration, and their own lifecycle hooks. Here they
are not. A root and a terminal are both `@ls.udf` functions, and what makes one
a root and the other a terminal is the *signature* — the parameter list and the
return annotation.

That is why every rule below is a rule about Python syntax rather than a rule
about an API. There is no `Source` class to subclass, no `sink()` builder, and
no registry to add yourself to. The tracer reads the `def` line, and the graph
follows from it.

## Sources

A source is written `@ls.udf(kind="source")`. It takes no parameters, and it
carries a return annotation:

```python
@ls.udf(kind="source")
def load_clips() -> Tuple["clips", "prompts"]:
    """Read the work queue; one row per clip."""
    ...
```

The tracer derives two things from that signature. Input ports are the
function's parameters, and there are none, so `inputs` is `[]`. The return
annotation is present, so the node gets its one output port and `outputs` is
`['out']`. The names inside `Tuple[…]` are not ports — they are the result's
column schema, and they land in `columns` as `['clips', 'prompts']`. A UDF
returns exactly one table; passing it downstream passes the whole table.

The `kind="source"` argument does less than it looks like it does. It sets the
card's kind dot, and it exempts the node from `_infer_kinds`, the pass that
relabels un-annotated nodes as `transform` or `merge` after the walk. What
actually makes `load_clips` a root is the empty parameter list: with no
arguments there is no provenance to draw an edge from, so nothing can point at
it. Delete the `kind=` and the node is still a root; add a parameter and it
stops being one, whatever the label says.

## Sinks

A sink is written `@ls.udf(kind="sink")`. It takes parameters, and it has **no**
return annotation:

```python
@ls.udf(kind="sink")
def save_dataset(rows):
    """Write the accepted rows to the dataset."""
    to_dataset(rows)
```

The mechanical rule, stated once so it is not mistaken for a convention: **a
node has an output port if and only if the function carries a return
annotation.** The tracer's line for it is exactly that literal —
`"outputs": ["out"] if fn.returns is not None else []`. So `kind="sink"` labels
the node, but it is the missing annotation that makes it terminal.

The two are genuinely independent, and the consequence is worth being blunt
about. Write `@ls.udf(kind="sink")` on a function that *does* return something
and the node gets an output port anyway — downstream UDFs will connect to it
and the graph will render those edges without complaint. The label paints the
card; it does not enforce the shape. Drop the annotation on a function you
never labelled and it becomes terminal regardless.

## `to_dataset` and `requeue`

These are the two framework terminals: `to_dataset(rows)` writes rows into a
dataset, and `requeue(rows)` sends them back around for another pass. Both
**must be wrapped inside a `kind="sink"` UDF**. Calling either one directly in
the pipeline body raises at trace time.

This is the rule that trips everyone, so here is why it exists — it is not a
special case for these two names. Every call inside a `@dl.pipeline` body must
resolve to a decorated UDF. When the walk reaches a call it cannot attribute to
an `@ls.udf` / `@dl.node` definition, it fails loudly rather than passing an
unknown call through:

> `pipeline calls undecorated function 'to_dataset' — every function called in a
> @dl.pipeline must be a @ls.udf / @dl.node (wrap framework helpers like
> to_dataset/requeue in a udf)`

`to_dataset` and `requeue` are imported from the framework, not defined as
UDFs in your file, so they hit that check like any other bare helper would.
Wrapping them is the whole fix, and it costs two lines each:

```python
@ls.udf(kind="sink")
def save_dataset(rows):
    to_dataset(rows)          # writes the accepted rows


@ls.udf(kind="sink")
def rework(rows):
    requeue(rows)             # sends the rejected rows back for another pass
```

Look at what is *not* in that graph. There is no `to_dataset` node and no
`requeue` node. The tracer never descends into a UDF body — it reads the `def`
line and stores the whole function's text verbatim in the node's `code` field.
**The sink is the node; the framework call inside it is body text.**
`to_dataset(rows)` is in `save_dataset`'s `code` string, where a source viewer
can show it — but it is never a node of its own, and no edge ever points at it.

The rest of the shape reads straight off the signatures. `load_clips` has no
inbound edge and no input dots, because it has no parameters. `save_dataset` and
`rework` have no outbound edge and no output dot, because neither carries a
return annotation. Nothing about the picture required a special node type.

## Two sinks is the normal shape

One terminal is the exception, not the rule. A pipeline that decides anything
usually has two: one for the rows that passed and one for the rows that did not.

```python
@dl.pipeline
def image_object_annotation():
    src = load_clips()
    for items in batch(src, n=64):
        labels = annotate(items.clips, items.prompts)
        consensus = review_boxes(labels)
        save_dataset(labels[consensus])   # accepted
        rework(labels[~consensus])        # rejected → another pass
```

The figure above is that pipeline with the review step elided, and its edges
drawn solid. In the full pipeline they would be **dashed**. `labels[consensus]`
puts a mask in a subscript's slice, which taints that argument's whole
provenance to `mask`, and a `mask` edge renders dashed — the visual claim being
that `review_boxes` does not contribute data to the sink, it only gates which
rows reach it. That gating is the subject of
[Review and masks](/pipelines/review-and-masks.md), and the mask subscript as a way
of tapping rows off the main stream is the subject of
[Sampling](/pipelines/sampling.md). This page keeps its edges solid on purpose: the
terminals themselves are the point here, ungated.

Note also that `rework` closes a loop conceptually — rejected rows go back to
the queue `load_clips` reads — but it does not close one in the graph. The
tracer is static and the queue is outside it, so the round trip is invisible. A
traced pipeline graph is always acyclic.

> **Warning:** `to_dataset`, `requeue`, `batch`, `stream`, `pipeline`, and `node` are not
>   exported by the shipped `dreamlake` package, and `lakeshore.udf` accepts no
>   `kind=` argument — its real signature is
>   `udf(fn=None, *, queue=None, transport="auto", config=None)`. `kind` is a
>   convention the tracer reads and the runtime never sees. These files are a
>   specification format that happens to be Python syntax: they trace because the
>   tracer parses them and never imports or executes anything.

---

Source: https://docs.dreamlake.ai/pipelines/transform-and-merge

# Transform and Merge

  `transform` is what a plain `@ls.udf` becomes when nothing else applies —
  the default, and by count the most common node in any pipeline. `merge` is
  the **same decorator with a different arity**. You do not declare it; the
  tracer infers it from how many upstream stages you happened to pass in.

Every other node kind on this site is something you ask for. `source` and
`sink` come from `kind=`, `review` comes from `kind=`, `model` and `filter`
come from `kind=`. `transform` and `merge` are the two the tracer decides for
you, and they are decided by the same rule, which is why they are one page.

## The inference rule

Stated once, exactly:

> A plain UDF whose inputs include **two or more non-source data inputs** is
> typed `merge`. Anything with fewer is `transform`.

Three qualifications are load-bearing, and all three come straight from
`_infer_kinds` in the tracer:

- **Only `data` edges count.** A `mask` edge — the dashed kind a `review` UDF
  produces — does not contribute to the count. A stage that takes one table and
  two masks is a `transform`, because it has one data input. See
  [Review and masks](/pipelines/review-and-masks.md).
- **Inputs drawn from a `source` node do not count.** This is deliberate: a
  side input such as a prompt column, loaded by the same source as the data,
  should not make a stage a merge. Otherwise almost every first-layer stage
  would be one.
- **An explicit `kind=` wins.** If you write `kind="merge"` on the decorator,
  the tracer preserves it verbatim and skips the inference entirely — the same
  way it skips `source`, `sink` and `review`. Inference only ever fills in a
  blank.

The consequence that matters more than the rule: **you never write
`merge(...)`.** There is no merge function, no merge node type to reach for, no
combinator. A merge is just a UDF you happened to call with several upstream
results. If you write a three-argument function and pass it three stage
outputs, you have written a merge, whether or not you meant to.

## Fan-out is calling the same UDF N times

The tracer gives each call its own node. A UDF called N times yields N distinct
nodes with generated ids — `semantic_match`, `semantic_match_2`,
`semantic_match_3` — so both the fan-out and the later fan-in survive in the
graph rather than collapsing onto one card with three inbound edges. Three
calls to three *different* UDFs behave identically; the generated-id case
matters only when you reuse one function.

Then the caveat that matters, and it is the one that catches people:
**fan-out width is structural, not dynamic.** The tracer does no loop
unrolling. It walks the body once. So

```python
for i in range(3):
    x = refine(x)
```

yields **one** `refine` node, not three, and the iteration count is lost —
there is nowhere in the graph schema to record it. If you want three nodes,
write three calls. See [Control flow](/pipelines/control-flow.md) for the full
list of what the walk keeps and what it discards.

## A comprehension is a map

A comprehension is not a fan-out either, and for a different reason. The tracer
binds the loop target to the iterable's provenance and traces the **element
expression once**, so

```python
captions = [caption(c) for c in items.clips]
```

yields **one** `caption` node — a map over the stream, which is what a UDF
already is. This is the right answer rather than a limitation: a UDF operates
on a column, so mapping it over the elements of that column is the identity.
List and tuple *literals*, by contrast, are traced element by element, so
`[f(a), f(b)]` really is two nodes. Again,
[Control flow](/pipelines/control-flow.md) has the table.

## The worked example

Three captioners with the same signature, and one plain UDF that takes all
three of their results:

```python
@ls.udf
def caption_model_a(clips, prompts: String["N"]) -> Tuple["caption", "confidence"]: ...

@ls.udf
def caption_model_b(clips, prompts: String["N"]) -> Tuple["caption", "confidence"]: ...

@ls.udf
def caption_model_c(clips, prompts: String["N"]) -> Tuple["caption", "confidence"]: ...

@ls.udf
def merge_captions(a, b, c) -> Tuple["labels"]:
    """Quotient three captionings into one label set."""
    ...


@dl.pipeline
def video_task_annotation():
    src = load_clips()
    for items in batch(src, n=32):
        a = caption_model_a(items.clips, items.prompts)
        b = caption_model_b(items.clips, items.prompts)
        c = caption_model_c(items.clips, items.prompts)
        labels = merge_captions(a, b, c)
```

Look at `merge_captions`. It was declared with a plain `@ls.udf` and **no
`kind=`** — the decorator is byte-identical to the three captioners above it —
yet it is painted as a merge, because it received three stage inputs. The three
captioners were declared the same way and stayed `transform`, because each one
received a single data input from a `source`, which the rule does not count.
Nothing in the source text distinguishes the four functions. The topology does.

Note also what the source nodes contribute. `items.clips` and `items.prompts`
are two columns off one upstream stage, not two upstream stages, so they are
one input for counting purposes even before the source exemption applies. The
`.clips` attribute access creates no node — which is the next section.

## What passes through without becoming a node

Only a call to a decorated function creates a node. Everything else in a
pipeline body moves provenance around without appearing on the canvas:

| Expression | Traced as |
| --- | --- |
| `review.all(axis=0)` | a method call — provenance of `review`, passed through |
| `labels[mask]` | a subscript — `labels` as `data`, `mask` as `mask` |
| `a & b`, `a \| b`, `a ^ b` | a binary operator — the union of both operands |
| `~m` | a unary operator — the provenance of `m`, unchanged |
| `items.clips` | an attribute — the provenance of `items` |

This is why a merge is always a real function call and never an operator.
Writing `a & b & c` combines three provenance sets into one variable and adds
**zero** nodes to the graph; whatever consumes that variable sees a single
input, not three. If you want the reconciliation to be a stage — schedulable,
inspectable, versioned, with its own card — it has to be a UDF you call. The
mask algebra is documented in full at
[Review and masks](/pipelines/review-and-masks.md).

> **Warning:** Everything on this page is real behaviour of the `dl_trace` tracer, and the
>   example above traces exactly as shown. The *imports* do not resolve. The
>   shipped `dreamlake` package exports no `pipeline`, `batch`, `to_dataset` or
>   `requeue`; `lakeshore.udf`'s real signature is
>   `udf(fn=None, *, queue=None, transport="auto", config=None)` — it accepts
>   **no `kind=` argument**, so `kind` is tracer-only notation today; and
>   `lakeshore.types` does not exist at all. These files are a specification
>   format that happens to be Python syntax. The tracer never imports or runs
>   them, which is why they trace anyway.

---

Source: https://docs.dreamlake.ai/pipelines/review-and-masks

# Review and Masks

  A review is a UDF that returns a boolean mask instead of data. The mask is
  not a table you pass along — it is a gate. The tracer marks every edge the
  mask touches, and the renderer draws those edges dashed.

That distinction is the whole page. Every other UDF in a pipeline answers the
question *what is the value?*; a review answers *which rows survive?* The two
answers travel along the same graph, but they are not the same kind of thing,
and a graph that drew them identically would be lying about what the pipeline
does.

## The review node

A review is declared with `kind="review"` and returns a `Mask[…]`:

```python
@ls.udf(kind="review")
def review_boxes(labels) -> Mask["R", "N"]:
    """R reviewers × N rows of accept/reject."""
    ...


@ls.udf(kind="review")
def semantic_match(labels, reference) -> Mask["N"]: ...
```

The `kind` is preserved verbatim. The tracer reads the decorator's keyword
arguments, copies them into the node's `config`, and uses `kind` as the node's
`kind` field — so `kind="review"` is what paints the card's review dot, and any
other keyword you pass survives on `config` untouched. Nothing validates the
string; `kind` is a label the tracer forwards, not an enum it enforces.

Note the annotation rule, because it surprises people. The return annotation
sets the result's **column schema**, and only `Tuple[…]` spreads its arguments
into separate columns. Every other subscripted type collapses to a single
column named after the base type, lowercased. So `Mask["R", "N"]` yields
`columns: ['mask']` — one column, not two. `"R"` and `"N"` are dimensions of
that one mask, not names of two of them. The same rule governs
`Tensor["N", "H", "W", 3]`, which is one `tensor` column. See
[UDF](/pipelines/udf.md) for the full annotation table.

A review node is otherwise an ordinary node: its parameters are its input
ports, and it has exactly one output port carrying that one `mask` column.

## The algebra is edges, not nodes

Here is the part worth reading twice. A pipeline manipulates masks with
ordinary Python operators, and **none of the following creates a node**. Each
one passes its operands' provenance through and tags it:

| Expression | What it means |
| --- | --- |
| `~a` | complement — the rows the mask rejects |
| `a & b` | intersection |
| `a \| b` | union |
| `a ^ b` | symmetric difference |
| `a & ~b` | difference |
| `labels[mask]` | SELECT the subset — this is where a mask **enters** |
| `poses.confidence > 0.5` | threshold — a comparison yields a mask |
| `review.all(axis=0)` | reduce R reviewers to one verdict |
| `review.mean(axis=0) > 0.5` | majority instead of unanimity |

The tracer treats subscripts, unary and binary operators, comparisons, boolean
operators, attribute access and method calls as pure provenance plumbing. They
have no node template to instantiate — there is no `@ls.udf` behind `&` — so
there is nothing to draw. Only a call to a decorated function becomes a node.

Now the precise mechanic, which is worth stating exactly because it is the one
rule that explains every dashed edge you will ever see:

> A mask is introduced at a **subscript's slice** — the thing inside the
> brackets — or at an **`if` test**. From there it taints its whole provenance:
> every node the mask descended from becomes a `mask` contributor to that edge.

Two consequences follow. First, the taint is transitive and total. In
`labels[review.all(axis=0)]` the slice is a method call on `review`, whose
provenance is the `review_boxes` node — so `review_boxes` is tagged `mask`, and
so is anything `review_boxes` itself descended from, all the way back. Second,
a mask only becomes a mask *at the point of use*. `review = review_boxes(labels)`
by itself is a plain data assignment; it is `labels[consensus]` that decides
`consensus` is a selector. Write a review's output into a sink directly and it
is data, because nothing ever put it in gate position.

## Data dominates mask

When the same pair of nodes is reached by both a data path and a mask path, the
edge is `data`. The tracer keys edges on `(from, fromPort, to, toPort)` and
resolves collisions in one direction only: `data` wins, always, no matter which
tag arrived first.

The rule is not arbitrary — it is what makes a dashed edge *mean* something.
Read it as a guarantee about the graph:

**A dashed edge means the source only gates the target, and never carries a
value into it.** A solid edge means at least one value flows. Because `data`
dominates, an edge that is still dashed at render time has had no data path
found on any traced branch — so the dashes are a negative claim you can rely
on, not a stylistic hint.

That is exactly why, in the figure below, the dashed edges come from
`review_boxes` and the solid ones come from `annotate`.

## The worked example

```python
@dl.pipeline
def image_object_annotation():
    src = load_images()
    for items in batch(src, n=64):
        labels = annotate(items.images)
        review = review_boxes(labels)          # -> Mask[R, N]
        consensus = review.all(axis=0)         # R reviewers must agree
        save_dataset(labels[consensus])        # the mask GATES what is written
        rework(labels[~consensus])             # the complement goes back
```

Read the graph against the source and notice what is *missing*. There are four
nodes for four UDF calls. `review.all(axis=0)` and `~consensus` produced no
nodes at all — they are edge tags. The consensus reduction over R reviewers and
the complement that routes the rejects to `rework` are both invisible as
geometry and entirely visible as line style.

Notice also where each sink's rows actually come from. `save_dataset` and
`rework` are each reached by two edges, and in both cases the solid one starts
at `annotate`. That is the honest reading of `labels[consensus]`: the value
being written is `labels`, and `consensus` only chose a subset of it. If the
graph drew a single edge from `review_boxes` to `save_dataset`, it would be
claiming the sink writes the mask — which is not what the code says.

The two sinks are also the same subset split two ways: `consensus` and
`~consensus` partition the rows, so every row lands in exactly one of them. The
graph cannot show that — the complement is not a node — which is a real
fidelity loss and the reason the mask expression stays in the source pane.

## Where masks come from and where they go

- [Sampling](/pipelines/sampling.md) — the subscript is the tap. Taking a subset
  off the main stream is a mask subscript, not a sampler function, and that
  page says what does and does not exist for it.
- [UDF](/pipelines/udf.md) — the annotation rules that turn `Mask[…]` into one
  column and `Tuple[…]` into several.
- [Control flow](/pipelines/control-flow.md) — an `if` test is the other place a
  mask enters. The tracer evaluates the condition in mask position, then
  discards the condition itself and walks both branches.

> **Warning:** Everything on this page is notation the tracer reads statically. None of it
>   runs.
>
>   `lakeshore.types` does not exist as a module — `Mask`, `String`, `Tensor` and
>   `Tuple` are names the tracer matches in an annotation, and
>   `from lakeshore.types import Mask` fails on a real interpreter.
>   `lakeshore.udf` accepts no `kind=` argument; its shipped signature is
>   `udf(fn=None, *, queue=None, transport="auto", config=None)`, so `kind` is
>   notation the tracer reads and the runtime never sees. The shipped `dreamlake`
>   package exports no `pipeline`, `batch`, `to_dataset`, or `requeue`.
>
>   The example files trace because the tracer parses them and never imports or
>   executes anything. Treat this page as a specification of the graph the tracer
>   derives, not as an API you can call today.

---

Source: https://docs.dreamlake.ai/pipelines/sampling

# Sampling

  The pipeline model has no sampler function. There is no `sample`, no `tap`,
  no `take`, no `head`. What it has instead is a **subscript**: `stream[mask]`
  is the branch you keep and `stream[~mask]` is the branch you divert. That
  single mechanism is the whole of "tapping data off the main stream" in a
  Python pipeline, and this page is about what it can and cannot express.

That is the honest answer, and it is worth stating before anything else,
because the obvious guess — that there is a `pipeline.sample(0.1)` somewhere —
is wrong in a way that costs a reader an afternoon. Real strategy samplers do
exist in DreamLake. They are **workflow** nodes, not pipeline functions, and
they are hand-authored in a different model entirely. The last two sections of
this page say where they are and why the two models diverge.

## The tap

A mask is a boolean selector over rows. Subscripting a table by one selects a
subset:

```python
save_trajectory(traj[ok])      # the rows where ok is true
requeue_bad(traj[~ok])         # the complement
```

The mechanic worth stating precisely is *where in the expression* the mask
enters. A subscript has two parts, and the tracer treats them differently:

- the **value** — the thing being subscripted, `traj` — keeps the role it
  already had, which is `data`;
- the **slice** — the expression inside the brackets, `ok` — is evaluated in
  mask position, which downgrades its entire provenance to `mask`.

That asymmetry is the entire reason the renderer draws two different lines into
the same sink. The solid edge is the table whose rows are travelling; the
dashed edge is the table that only decided which rows travel. Neither the
subscript nor the `~` creates a node — both are pure provenance plumbing.

One consequence catches people out: when a node contributes to *both* the value
and the mask, `data` wins. An edge carries one role, and a node that is already
shipping rows down an edge does not also get a dashed gate edge alongside it.
The dashed edges in a real trace are therefore only the nodes that touch the
mask **and nothing else**.

## Three ways to build the mask

None of these creates a node. They are expressions over columns, and the tracer
evaluates them for provenance only:

```python
ok        = poses.confidence > 0.5                              # a threshold on a column
ok        = (poses.confidence > 0.5) & (traj.residual < 1.0)    # the conjunction of two
consensus = review.all(axis=0)                                  # a reviewer reduction
```

A comparison merges the provenance of both sides. `&`, `|` and `^` merge the
provenance of both operands. `~` passes provenance straight through — the
complement of a mask descends from exactly the same nodes the mask does, which
is why `traj[ok]` and `traj[~ok]` produce identical edge topology and differ
only in the rows that actually flow at run time. The full algebra is at
[Review and Masks](/pipelines/review-and-masks.md).

## The worked example

```python
@dl.pipeline
def camera_pose_trajectory():
    src = load_frames()
    for items in batch(src, n=8):
        poses = estimate_pose(items.frames)
        traj = fit_trajectory(poses)

        ok = (poses.confidence > 0.5) & (traj.residual < 1.0)
        save_trajectory(traj[ok])      # the kept tap
        requeue_bad(traj[~ok])         # the diverted tap
```

The figure is the real `` component, not a picture of one: drag
a card, scroll to pan, hold ⌘ or ctrl and scroll to zoom. It trims the source
and the batch loop, neither of which adds a tap.

Read what it shows. **Two sinks are fed by the same upstream table.** Nothing
in the graph distinguishes the kept branch from the diverted one — not the node
kind, not the port, not the column set. `fit_trajectory` reaches both sinks on
a solid `data` edge, identically. The only structural difference is the dashed
`mask` edge from `estimate_pose`, and even that is symmetric: the complement
gets one too.

That is a real limit, not an oversight. The tracer reads the source and never runs
it, so it cannot know that `ok` and `~ok` partition the stream rather than
duplicating it. The graph is an over-approximation of the dataflow — it records
that the mask reached both sinks and stops there.

`estimate_pose` is the only node on a dashed edge even though `ok` reads a
column from `traj` as well. `fit_trajectory` is already sending rows down a
solid edge into both sinks, and `data` dominates `mask`, so its mask
contribution is absorbed. What survives as a visible gate is precisely the node
whose *only* contribution was to the predicate.

## What the pipeline model cannot express

The mask subscript is a filter, not a sampler, and the difference is not
cosmetic. Four things a sampling API would give you have no expression here:

**There is no fractional or random sampling.** `bernoulli(0.1)` has no
equivalent. A mask is a predicate over rows — deterministic, evaluated from
column values — not a coin flip, and the tracer has no notion of randomness at
all. Nothing in the graph could record "keep about a tenth of these".

**There is no `first_n` or `head`.** The tracer does not unroll loops and has
no counting construct, so "take the first 100" cannot be expressed in the
graph. A `for` body traces once regardless of how many times it would run; see
[Control Flow](/pipelines/control-flow.md).

**There is no stratified sampling.** There is no notion of a stratify-by key,
no per-stratum fraction, and no place in the node or edge schema to put one.

**The batch size is not sampling.** `batch(src, n=32)` is a chunking hint for
the run: it says the stream should be processed 32 rows at a time. It adds no
node, it changes no edge, and it does not reduce the stream — every row still
goes through. Reading `n=32` as a sample size is an easy mistake to make, and
it is wrong in both directions — it neither selects rows nor bounds them. See
[Batching](/pipelines/batching.md).

## Where the real samplers live

> **Note:** DreamLake does have proper samplers, with the statistically correct names and
>   parameters — `bernoulli` (`fraction`, `min_size`, `seed`), `random_n`
>   (`size`, `with_replacement`, `seed`), `stratified` (`stratify_by`, `fraction`
>   or per-stratum `fractions`, `min_size`, `seed`) and `first_n` (`size`). They
>   are **node types in the hand-authored WorkflowSpec model**, not Python, and
>   they are documented in full at
>   [Workflow Node Types](/workflows/node-types.md#sampler). Do not duplicate their
>   schema into a pipeline file; there is nothing there to receive it.

The split is a consequence of how each graph comes to exist. A pipeline graph
is **derived statically from source** — the tracer reads the `.py` file and can
only describe what the syntax structurally says, and Python syntax has no way
to say "sample 10% with seed 7" that a parser could recognise without running
the program. A workflow spec is **authored directly** as a typed node graph, so
it can simply name a strategy and its parameters as fields, and the runtime
reads them. One model can only report what the code looks like; the other can
be told what to do.

> **Warning:** The authoring API on this page is not implemented in shipped Python.
>   `@dl.pipeline`, `batch`, `to_dataset` and `requeue` are not exported by the
>   `dreamlake` package; `lakeshore.udf` accepts no `kind=` argument; and
>   `lakeshore.types` does not exist. These `.py` files are a specification
>   format that happens to be Python syntax — they trace because the tracer
>   parses the source and never imports or executes it.

---

Source: https://docs.dreamlake.ai/pipelines/batching

# batch() and stream()

  The pipeline model has exactly one absolute rule: every function a
  `@dl.pipeline` body calls must be decorated. `batch()` is the single
  exemption, and it earns the exemption by not being a stage at all.

The rule is enforced, not advisory. When the tracer walks a pipeline body and
reaches a call it cannot resolve to a `@ls.udf` or a `@dl.node`, it does not
shrug and pass the value through — it **raises**:

```text
pipeline calls undecorated function 'to_dataset' — every function called in a
@dl.pipeline must be a @ls.udf / @dl.node (wrap framework helpers like
to_dataset/requeue in a udf)
```

That strictness is the reason the derived graph can be trusted. If an
undecorated helper were allowed anywhere, it could consume a table and produce
another one, and the graph would be missing an edge with nothing to indicate
the gap. Failing loudly is the only way a *static* tracer can promise that the
picture is complete.

There is exactly one position where the tracer relaxes this: the iterator
expression of a `for` statement. That is where `batch()` lives.

## The shape

```python
@dl.pipeline
def image_object_annotation():
    src = load_clips()
    for items in batch(src, n=64):
        labels = annotate(items.clips)
        save_dataset(labels)
```

Only the iterator is lenient. The loop **body** is strict again — `annotate`
and `save_dataset` are ordinary UDFs and an undecorated call between them would
raise exactly as it would outside the loop.

## What it does to the graph: nothing

`batch(src, n=64)` adds no node. The tracer evaluates the iterator expression
in lenient mode, which means: resolve the arguments' provenance, merge it, and
return that — do not register a stage. The loop variable is then bound to the
merged result, so `items` **is** `src` as far as the graph is concerned.

`items.clips` is an attribute access, and attribute access is not a node
either; it selects a column name off a value whose provenance is already
`load_clips`. So the edge `annotate` draws for its `clips` parameter runs all
the way back to the source's single output port.

Two cards, one solid `data` edge. The figure drops the loop body's
`save_dataset` sink so the only thing left to look at is the gap in the middle
— the place where a reader coming from Airflow or Beam expects a chunking
operator to appear, and where the derived graph has nothing.

## Why the exemption exists

A chunking hint is a property of the **run**, not of the dataflow. Whether the
runtime feeds `annotate` sixty-four rows at a time or all of them at once, the
same data reaches the same stage from the same source. Drawing a card for it
would put an execution-strategy knob into a diagram that otherwise means
exactly one thing — where values come from and where they go.

So the iterator position is the one place the tracer relaxes, and the price is
paid honestly:

**`n` does not appear in the derived graph at all.** Not as a node, not as a
node config value, not as an edge annotation. Nothing downstream can read it.
Round-trip a pipeline through the tracer and `n=64` survives only inside the
`code` string that carries the original source.

**`batch()` is not a sampler.** It does not reduce the stream, drop rows, or
select a subset. Every row still reaches every stage in the loop body; the only
claim it makes is about grouping. If you want to tap a subset of the data off
the main stream, that is a different mechanism entirely — see
[Sampling](/pipelines/sampling.md), which also explains why the real samplers
(`bernoulli`, `random_n`, `stratified`, `first_n`) live on the workflow side
rather than here.

## stream()

`stream()` is documented as the streaming sibling of `batch()` and is accepted
in the same iterator position — the tracer's leniency is positional, so any
call there passes, whatever it is named.

> **Warning:** `stream()` appears in **zero** example pipelines and has **zero** tests. It is
>   named in the tracer's comments and in the authoring rules, and nowhere else.
>   Its exact signature is therefore unspecified — including whether it takes an
>   `n=` argument at all, and what it would mean if it did. This page will not
>   guess one. Use `batch()` until `stream()` has an example that pins it down.

The one thing that *is* certain is the graph consequence, because it follows
from the position rather than the function: whatever `stream()` turns out to
be, it adds no node and passes its arguments' provenance to the loop variable,
exactly as `batch()` does.

## Async form

An `async for` inside an `async def` pipeline traces identically to the
synchronous form:

```python
@dl.pipeline
async def image_object_annotation():
    src = load_clips()
    async for items in batch(src, n=64):
        labels = await annotate(items.clips)
        save_dataset(labels)
```

The tracer treats an async stage and an async pipeline the same as their
blocking equivalents. `async def` still registers a UDF as a node, `await`
unwraps to the awaited expression's provenance, and `async for` takes the same
lenient-iterator path as `for`. The two pipelines above produce the same nodes
and the same edges — the graph cannot tell them apart, because concurrency is a
runtime concern and this graph is derived without a runtime.

## The rule this page is an exception to

The model to leave with matters more than the name `batch`:

**Any other undecorated call raises.** The exemption is scoped to the iterator
expression of a `for` or `async for`, and to nothing else. It is not a general
"framework helpers are fine" escape hatch.

**`to_dataset(rows)` and `requeue(rows)` are not exempt.** Called directly from
a pipeline body they raise, exactly like any other undecorated function. They
have to be wrapped inside a `kind="sink"` UDF, which is what every example
pipeline does — see [Sources and sinks](/pipelines/sources-and-sinks.md).

**The loop itself is a separate subject.** `batch()` explains why the iterator
is invisible; it does not explain what the tracer does with the loop around it.
The short version is that the body is traced **once** and the iteration count
is lost — a loop never unrolls, so a pipeline that runs a stage a thousand
times draws one card. [Control flow](/pipelines/control-flow.md) covers that,
along with `if`/`else`, comprehensions, `while`, and `with`.

> **Warning:** `batch` and `stream` are not exported by the shipped `dreamlake` package.
>   Neither is `pipeline`, `node`, `to_dataset`, or `requeue`, and
>   `lakeshore.udf` accepts no `kind=` argument. The `.py` files on this page are
>   a **specification format that happens to be Python syntax** — they trace
>   precisely because nothing in them is ever imported or executed. Run one as a
>   script and it fails at its `from dreamlake import batch, requeue, to_dataset`
>   line, long before any pipeline body is reached.

---

Source: https://docs.dreamlake.ai/pipelines/control-flow

# Control Flow

  A pipeline's graph is derived from its source by a static tracer that never
  imports and never executes anything. It walks the syntax tree once. That
  single fact decides everything on this page: the graph **over-approximates**
  — it draws every path the code could take — and it cannot draw anything that
  only exists at run time.

Both halves of that sentence cost something, and the cost is worth stating
plainly rather than discovering later. Over-approximation means a graph with
four nodes may describe a run that touched two of them. "Nothing that exists
only at run time" means the predicate that chose between those two — the thing
you most want to see when you are reading the picture — is absent.

## There is no control-flow node

The first surprise is that there is nothing to look for. `condition`, `switch`,
`loop` and `approval` are node types, but they belong to the **WorkflowSpec**
model — hand-authored JSON, a different artifact, documented at
[Workflow Node Types](/workflows/node-types.md). A Python pipeline has no
equivalent and does not want one.

In a pipeline, control flow is ordinary Python. It is not declared, not typed,
and not addressable. It shows up in the derived graph as **shape** — which
nodes exist, and which edges join them — and never as a node of its own. If you
are looking for the box labelled "if", there isn't one, and its absence is the
design rather than a gap in the renderer.

## The summary

| Construct | What the tracer does |
| --- | --- |
| `if` / `else` | both branches traced; the resulting provenance is the **union**; the condition is not drawn |
| `for` | the body is traced **once**; the iteration count is lost |
| `for … in batch(…)` | the iterator is exempt from the decoration rule; adds no node |
| `[f(x) for x in xs]` | a **map** — the element expression is traced once, so one node |
| `[a(), b()]` / `(a(), b())` | a literal **fan-out** — one node per element expression |
| `while` / `with` | the body is traced once, like a `for` |

Each row below.

## if / else

```python
@dl.pipeline
def image_object_annotation():
    src = load_images()
    for items in batch(src, n=64):
        labels = detect(items.images)
        if fast_mode:
            labels = refine_fast(labels)
        else:
            labels = refine_slow(labels)
        save_dataset(labels)
```

Read the figure literally. Both `refine_fast` and `refine_slow` are in the
graph, and **both feed the sink**. That is not a rendering artefact: the tracer
walks the `if` body and the `else` body from the same pre-`if` bindings, then
merges the two results, so after the branch the name `labels` carries the
**union** of the two provenances. `save_dataset(labels)` therefore draws one
edge per contributing node. The alternative — trace one branch, drop the other
— would leave a real node dangling with no path to the sink, which is worse.

`fast_mode` appears nowhere. There is no node for it, no port, no label on
either edge. The tracer reads the test, uses it (see below), and discards it.

The second-order consequence is the one that bites. **The graph shows what the
pipeline could do, not what one run did.** A four-node picture of a two-node
execution is correct as a description of the program and wrong as a description
of the run. When runtime status is painted onto the graph, the branch that
never fired stays `idle` — which is the only honest thing an over-approximated
graph can say, and is not the same as "this node is not part of the pipeline".

There is a related mechanic worth knowing, because it is the one place the
condition leaves a trace. An `if` test is evaluated in **mask role** — one of
exactly two places a mask enters provenance, the other being a subscript's
slice, `labels[mask]`. So a conditional written on a mask column taints
everything downstream of it: the edges that carry that provenance are tagged
`mask` and render dashed. The predicate is still not a node, but its influence
is visible in the edge tags. See
[Review and Masks](/pipelines/review-and-masks.md) for the tagging rules and the
`data`-dominates-`mask` merge.

## Loops do not unroll

```python
    for i in range(3):
        x = refine(x)          # ONE refine node, not three
```

Flatly: the iteration count is lost. The body is walked once, `refine` becomes
one node, and nothing in the emitted JSON records that it runs three times. The
`3` is not stored as a property, an annotation, or a badge — the tracer never
evaluates `range(3)`, because evaluating it would mean running the code.

This is not a bug to route around; it is the direct consequence of a
single-pass walk. If you want three stages in the graph, **write three calls**.
Calling one UDF N times is the documented way to get N nodes — the tracer
disambiguates them (`refine`, `refine_2`, `refine_3`) and both the fan-out and
the fan-in survive. See
[Transform and Merge](/pipelines/transform-and-merge.md).

The loop that is idiomatic in a pipeline body is the batching loop,
`for items in batch(src, n=64)`. Its iterator is the single exemption from the
rule that every call in a pipeline body must be decorated: `batch` may be
undecorated, adds no node, and the loop variable simply inherits the iterated
source's provenance. The body is strict again. See
[Batching](/pipelines/batching.md).

## A comprehension is a map

```python
    captions = [caption(c) for c in items.clips]
```

The element expression is traced once, with the loop target bound to the
iterable's provenance, so this yields exactly **one** `caption` node. That is
the right reading: a comprehension over a stream is a map, and a map is one
stage applied to every row, not one stage per row. The same holds for set
comprehensions, dict comprehensions and generator expressions.

A list or tuple **literal** is a different construct and traces differently:

```python
    scored = [model_a(x), model_b(x)]
```

Here each element is a separate expression, each is traced, and each becomes
its own node. This is a genuine fan-out — two nodes, two edges — and it is the
compact way to write one. The distinction is syntactic and worth internalising:
a comprehension has one element expression and yields one node; a literal has
N element expressions and yields N.

`while` and `with` bodies are traced once, exactly like a `for`. A `while`'s
test is evaluated in data role rather than mask role, but it is likewise not
drawn.

## The open gap

> **Warning:** **Data-dependent routing has no representation.** Because the `if` condition
>   is discarded, a traced graph cannot distinguish "route rows to A or B by a
>   predicate" from "send everything to both A and B". Both produce the same four
>   nodes and the same four edges. This is tracked upstream as an open
>   tracer-fidelity question — DreamLake issue #50 — and there is no annotation,
>   edge tag, or node property that carries the answer today.

One thing does express routing, and it is worth reaching for when the routing
matters: the **mask subscript**. `rows[mask]` and `rows[~mask]` split a stream
into two disjoint halves, and because a mask is *data* it survives tracing —
the split appears as two dashed `mask` edges from the node that produced the
mask. A predicate held in a Python `if` is invisible; the same predicate held
in a mask column is in the graph. See [Sampling](/pipelines/sampling.md) for the
subscript form and where it stops being enough.

The practical rule that follows from all of the above: keep the pipeline body
straight-line dataflow, and move data-dependent control **inside** a UDF, where
the tracer treats the whole thing as one stage and makes no claim about its
internals. A branch the graph cannot see is better hidden than half-drawn.

> **Warning:** The Python on this page is a **specification format that happens to be Python
>   syntax**. The shipped `dreamlake` package exports no `pipeline`, `batch`,
>   `to_dataset` or `requeue`; `lakeshore.udf` accepts no `kind=` argument; and
>   `lakeshore.types` does not exist at all. These files trace precisely because
>   the tracer never imports or executes them. Do not expect them to run.

---

Source: https://docs.dreamlake.ai/pipelines/model-functions

# Model Functions

  `dl_pipelines` describes itself, in its own module docstring, as "the
  canonical node functional API for DreamLake pipelines — the contract." It is
  a naming layer over model inference: one function per task, so a pipeline
  names <em>what</em> it wants done rather than which checkpoint does it.

The argument for a naming layer is the same one that motivates the graph. A
pipeline that says `detect_objects(images)` still means the same thing after the
checkpoint behind it is swapped, the serving stack is rewritten, or the work
moves from a local GPU to a queue. A pipeline that says
`DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50")` means one
particular thing on one particular day. The contract fixes the vocabulary at the
level of the task, and leaves the model choice to whatever resolves it.

That is the whole of the design. What follows is the vocabulary — and an honest
account of how much of it runs.

> **Warning:** Every one of these thirty-three functions is an `async def` whose body is a
>   single `raise NotImplementedError`. A blocking mirror of each is generated
>   automatically at import time, so there is a synchronous twin of every entry
>   point — and it raises too, because it calls the async original. The Hugging
>   Face adaptor that maps task names onto these functions raises in all three of
>   its `resolve`, `run` and `wrap_pipeline` paths; only its lookup tables are
>   real data.
>
>   None of these functions appears in any shipped example pipeline. The example
>   UDF named `detect_objects` in `pipelines/image_object_annotation.py` is a
>   **local stage** that merely shares a name with the canonical
>   `detect_objects`. The two are unrelated: the example's body is `...`, and it
>   imports nothing from `dl_pipelines`.

## The five domains

Thirty-three functions across five modules. Names are given exactly as they are
exported; the intent line is the function's own docstring intent, not an
invented signature.

### Vision — twelve

| Function | Intent |
| --- | --- |
| `caption_image` | caption each image, optionally prompt-guided |
| `generate_image` | generate images from prompts, or unconditionally |
| `image_to_image` | transform each image, optionally text-guided |
| `classify_image` | classify each image against the model's own label set |
| `zero_shot_classify_image` | classify each image against caller-provided labels |
| `detect_objects` | detect objects in each image |
| `zero_shot_detect_objects` | detect caller-specified object classes |
| `segment_image` | semantic or instance segmentation per image |
| `generate_masks` | promptable mask generation, SAM-style |
| `estimate_depth` | per-pixel depth map per image |
| `detect_keypoints` | keypoints — pose, landmarks — per image |
| `embed_image` | one embedding vector per image |

### Text — ten

| Function | Intent |
| --- | --- |
| `generate_text` | continue or complete each prompt |
| `classify_text` | classify each text against the model's own label set |
| `zero_shot_classify_text` | classify each text against caller-provided labels |
| `classify_tokens` | tag spans — NER, POS — in each text |
| `summarize` | summarize each text |
| `translate` | translate each text |
| `answer_question` | extract the answer span for each question/context pair |
| `fill_mask` | fill the mask token with ranked candidates |
| `embed_text` | one embedding vector per text |
| `rank_texts` | relevance score of each text for one query |

### Audio — four

| Function | Intent |
| --- | --- |
| `transcribe` | speech to text, per clip |
| `synthesize_speech` | text to speech, per text |
| `classify_audio` | classify each clip |
| `audio_to_audio` | transform each clip — denoise, separate, enhance |

### Video — four

| Function | Intent |
| --- | --- |
| `generate_video` | generate video from text and/or a conditioning image |
| `classify_video` | classify each video |
| `caption_video` | describe or answer questions about each video |
| `video_to_video` | transform each video, optionally text-guided |

### Multimodal — three

| Function | Intent |
| --- | --- |
| `visual_question_answer` | answer a question about each image |
| `document_question_answer` | answer a question about each document — a scan, a PDF |
| `table_question_answer` | answer a question about each table |

## Why the count is thirty-three

The number is not arbitrary, and it is the strongest evidence that this set was
derived rather than brainstormed. The Hugging Face adaptor carries a mapping
from **every one of the forty-seven Hugging Face task types** onto exactly this
set of names, and that mapping has two properties worth stating.

**Every canonical function is reachable.** All thirty-three appear as the target
of at least one task. There is no name in the API that the task taxonomy does
not justify.

**Thirty-nine tasks map to a function; eight map to `None`.** Those eight are
the tasks the contract has decided not to cover yet:

`any-to-any` · `audio-text-to-text` · `image-to-3d` · `reinforcement-learning` ·
`tabular-classification` · `tabular-regression` · `text-to-3d` ·
`visual-document-retrieval`

Thirty-nine tasks landing on thirty-three functions means six collapses, and
each one is a deliberate judgement that Hugging Face's split is about the
*input arity* rather than the task:

| Canonical function | Hugging Face tasks it absorbs |
| --- | --- |
| `generate_video` | `text-to-video`, `image-to-video`, `image-text-to-video` |
| `generate_image` | `text-to-image`, `unconditional-image-generation` |
| `image_to_image` | `image-to-image`, `image-text-to-image` |
| `embed_text` | `feature-extraction`, `sentence-similarity` |
| `visual_question_answer` | `visual-question-answering`, `image-text-to-text` |

`generate_video` is the clearest case: text-to-video and image-to-video are one
function with two optional arguments, not two functions. The signature reflects
that — `prompts` and `images` are both optional, and passing either or both is
the same call.

> **Warning:** The task list was crawled from `huggingface.co/api/tasks` and is pinned in a
>   comment as accurate on 2026-07-02. Nothing re-crawls it, and nothing tests
>   that it is still complete. Treat the forty-seven as a snapshot.

## Output records

The return types are small dataclasses in `dl_pipelines.types`. These are the
only part of the module that is fully implemented, because a dataclass has no
body to leave unwritten.

| Record | Fields | Returned by |
| --- | --- | --- |
| `Caption` | `text`, `confidence?` | `caption_image`, `caption_video` |
| `Label` | `name`, `score` | every `classify_*`, plus `fill_mask` and `rank_texts` |
| `Box` | `xyxy`, `label?`, `score?` | `detect_objects`, `zero_shot_detect_objects` |
| `Mask` | `mask` (HxW boolean array), `label?`, `score?` | `segment_image`, `generate_masks` |
| `Keypoints` | `points` (Kx2 array), `label?`, `score?` | `detect_keypoints` |
| `Span` | `text`, `start`, `end`, `label?`, `score?` | `classify_tokens`, `answer_question`, `document_question_answer` |
| `Transcript` | `text`, `segments: list[Span]` | `transcribe` |

`Embedding` is not a record — it is `list[float]`, and `embed_image` /
`embed_text` return one per input.

The nesting matters when you read a signature. A per-item classifier returns
`list[list[Label]]`: the outer list is the batch, the inner list is that item's
ranked labels. `answer_question` returns a flat `list[Span]`, because there is
exactly one answer per question. Nothing about this is enforced today, but it is
what the annotations say.

### The input aliases constrain nothing

`Image`, `Audio`, `Video`, `Document` and `Table` are all declared as
`TypeAlias = Any`, with a comment saying inputs are "intentionally loose for now
— an array, a PIL/AV object, a path, or a URL." So a signature reading
`detect_objects(images: list[Image])` is, to a type checker, `list[Any]`.

These aliases are documentation that happens to be written in the type
language. They tell a reader what kind of thing belongs in that slot, and they
will reject nothing at all if the reader is wrong. Do not mistake a green type
check for a validated input.

## Async and sync

Every canonical function is defined `async def`. The blocking mirrors are not
written by hand — `dl_pipelines/sync/__init__.py` walks `dl_pipelines.__all__`
at import time, and for each coroutine function installs a wrapper that calls
`asyncio.run` on it. Both calling conventions therefore exist for every entry
point, and stay in step by construction: a new function added to `__all__` gets
its synchronous twin for free.

```python
import dl_pipelines
from dl_pipelines import sync

captions = await dl_pipelines.caption_image(images)   # async
captions = sync.caption_image(images)                 # blocking twin
```

Two consequences of generating the mirror this way. The wrapper carries
`__wrapped_async__`, so the original coroutine function is still reachable from
its twin. And because it is `asyncio.run` underneath, a `sync.*` call made from
inside a running event loop will fail — the mirrors are for synchronous
programs, not for escaping an `await` you would rather not write.

**The tracer does not care which one you use.** It reads the pipeline's source
as an AST and never imports or executes anything, so an `async def` stage and a
blocking one derive precisely the same graph. The one place the distinction
becomes visible to the graph is the `async for` batching form, covered at
[Batching and streaming](/pipelines/batching.md).

Everything shipped in `dreamlake-pipeline-examples` is synchronous, and the
pipeline-generator skill instructs authors to stay that way. Prefer the `sync.`
mirrors unless you have a reason not to.

## How you would use one

The teaching point of this page in one sentence: **a canonical model function is
called inside a UDF body, and is not itself a node.**

The tracer trusts only decorated functions. It walks the `@dl.pipeline` body and
refuses any undecorated call it finds there; it does not descend into UDF
bodies at all. So a model function called directly in the pipeline body is a
trace error, and the same call one level down — inside a `@ls.udf` — is
invisible to the graph. That is exactly the treatment `to_dataset` gets inside a
sink, and it is the same rule for the same reason.

```python
import lakeshore as ls
from lakeshore.types import Tuple
from dl_pipelines import sync


@ls.udf(kind="model")
def detect(images) -> Tuple["boxes", "scores", "labels"]:
    """Detect objects in each image; one row per box."""
    return sync.detect_objects(images)
```

The graph has two nodes and one edge. `sync.detect_objects` is not one of them.
The stage's ports come entirely from the decorated wrapper: `images` is an input
port because it is a parameter, and `boxes` / `scores` / `labels` are columns on
the single `out` port because they are the return annotation's names. See
[The UDF](/pipelines/udf.md) for that derivation in full.

Note what the wrapper is responsible for. `detect_objects` returns
`list[list[Box]]` — one list of `Box` records per image — and the UDF above
declares three columns. Flattening the records into those columns is the
author's job, inside the body, where the graph cannot see it. The return
annotation is a **declaration of the stage's schema**, not something derived
from the canonical function's return type.

Note also what the signature does *not* have. `detect_objects` takes exactly one
argument today: `images`. There is no `threshold`, no `model`, no `device`. If
you want to write a call with tuning parameters, you are writing against a
surface that does not exist yet.

### `model` is a kind the renderer paints and the tracer has never produced

The figure above uses `kind: 'model'` deliberately, and it is showing an
intended state rather than a graph anyone has traced.

`NodeKind` in `@dreamlake/uikit` admits seven values — `source`, `transform`,
`model`, `filter`, `merge`, `sink`, `review` — and the renderer gives each its
own kind-dot colour. The tracer's behaviour is narrower. It copies an explicit
`kind=` off the decorator verbatim, and when there is none it infers exactly two
values: `merge` when a stage has two or more upstream data inputs, `transform`
otherwise. The kinds that actually appear in shipped example pipelines are
`source`, `sink` and `review` — written by hand — plus inferred `merge` and
`transform`. **No shipped pipeline writes `kind="model"` or `kind="filter"`, so
neither has ever appeared in a real traced graph.** Both are renderer
vocabulary waiting for an author.

> **Warning:** Two things stand between `kind="model"` and working code. Lakeshore's real
>   decorator is `udf(fn=None, *, queue=None, transport="auto", config=None)` — it
>   accepts no `kind=` at all, so `kind` is a **tracer-only annotation** that the
>   tracer reads out of the decorator's AST without ever importing Lakeshore. And
>   `dreamlake-server` types a node's `kind` as `'source' | 'transform' | 'sink'`,
>   narrower than what the tracer already emits and much narrower than what the
>   renderer paints. A `model` node would not survive the round trip today.
>   `lakeshore.types`, the source of the `Tuple[…]` return annotation, does not
>   exist in shipped Lakeshore either — the example `.py` files are a
>   specification format that happens to be Python syntax, and they trace because
>   the tracer never imports them.

## Where this leaves you

This page documents an intended surface, and says so at the top rather than at
the bottom. The vocabulary is real and it is well derived — thirty-three names
that cover thirty-nine of forty-seven public task types, with a record type for
every output and a synchronous twin for every entry point. The inference is not
there. Every body raises.

Writing a pipeline against these names today buys you two real things: the
naming, so that the intent survives whatever eventually implements it, and the
graph, because the tracer never runs a line of it and traces a placeholder body
exactly as it traces a real one. It does not buy you a prediction. Until the
bodies land, a pipeline that calls `sync.detect_objects` renders beautifully and
raises `NotImplementedError` the moment anything tries to run it.

For the node and edge schema underneath all of this, and for what the tracer can
and cannot emit, start at [Pipeline Functions](/pipelines.md).

---

Source: https://docs.dreamlake.ai/lakeshore/queues

# Queue model

  A Lakeshore queue is one record carrying two jobs. It is a **task queue** —
  the thing invocations line up in and workers pull from — and it is a **launch
  queue** — the policy deciding how many workers should exist. They are one
  model because the depth of the first is the input to the second.

The queue name you write in `@udf(queue="gpu")` is denormalized onto every
invocation, and the control plane reads that one string twice: once to route a
claim to a worker, and once to count how many invocations are still waiting.
Counting the backlog is how the autoscaler knows whether to grow the pool.
Splitting scheduling and provisioning into separate objects would mean keeping
that number in sync across both.

Read the two halves separately:

- [Task queue](/lakeshore/queues/task-queue.md) — the behaviors: submit, claim,
  complete, retry, stream.
- [Elastic queues](/lakeshore/queues/elastic.md) — what attaching a provider adds.

## The type

```ts file="Queue"
interface Queue {
  id:            string
  namespaceId:   string          // the prefix — see below
  name:          string          // unique within namespaceId
  description?:  string

  // ── Scheduling surface ────────────────────────────────────────────
  kind:          'fifo' | 'priority' | 'boltzmann' | 'filo'   // default 'fifo'
  kindParams?:   { temperature?: number; priority_field?: string }
  admission?:    {
    max_depth?:          number
    on_full?:            'reject' | 'block'
    rate_limit?:         number
    deadline_cutoff_s?:  number
  }
  reservedSlots?: number         // advisory slots held back
  authPolicy?:    unknown        // opaque blob; consumer is the auth gate

  // ── Launch policy ─────────────────────────────────────────────────
  providerRef?:   string | null  // provider name; null = bring your own worker
  elasticity?:    {
    kind:        'fixed' | 'fully_elastic' | 'pool_with_threshold' | 'max_count'
    min?:        number
    max?:        number
    threshold?:  number
  }
  daemonTemplate?: {
    instance_type?:  string
    image_id?:       string
    runner?:         string
    setup_scripts?:  string[]
  }
  customScalerUdf?: string       // optional UDF overriding the built-in scaler

  // ── Lifecycle ─────────────────────────────────────────────────────
  state:         'active' | 'draining' | 'paused' | 'archived'   // default 'active'
  serverNodeId?: string | null   // owning queue-server tier; null = central

  createdAt:     Date
  updatedAt:     Date
}
```

## Naming and the prefix

**A queue name is never global.** The record carries a `namespaceId`, and the
uniqueness constraint is on the pair:

```
@@unique([namespaceId, name])
```

So the namespace *is* the prefix. Two namespaces can both own a queue called
`gpu` and they are different queues; within one namespace the name is the
identity, which is what lets `@udf(queue="gpu")` be a bare string in user code —
the namespace comes from the caller's credentials, not from the literal.

Everything keyed off a queue inherits that scoping. The idempotency key on a
submit (`_key=`) is unique per **namespace + queue**, not per queue name alone,
so the same key in two namespaces is two distinct invocations.

> **Note:** There is no separate prefix field, and `name` is a flat string — Lakeshore
>   does not parse `team/gpu` into a hierarchy today. If you want grouping inside
>   a namespace, it lives in the name by convention and nothing enforces it.
>
>   This differs from a Redis-backed queue like
>   [zaku](https://github.com/geyang/zaku), where the prefix is a literal key
>   prefix (`Zaku-task-queues:{queue}:pending`) chosen at client construction. In
>   Lakeshore the equivalent partitioning is a control-plane relation, not a
>   string you assemble.

## Creating one

```bash file="terminal"
lakeshore queues add gpu-train \
  --kind priority \
  --provider aws-east \
  --elasticity fully-elastic --min 0 --max 4
```

You rarely have to: submitting to a queue name that does not exist creates it,
with `kind` defaulting to `fifo`. Reach for `queues add` when you want a
non-default discipline or a launch policy.

> **Warning:** The CLI takes the dashed forms above (`fully-elastic`); the REST API and
>   compose files take underscores (`fully_elastic`). The CLI translates between
>   them.

## Stored ahead of enforced

Several fields above are persisted and validated but not yet acted on, and the
gaps are not visible from the field names:

| Field | Reality today |
| --- | --- |
| `kind` | The hosted control plane dispatches by priority then oldest-first regardless of the value. The four disciplines are implemented in the SDK's local plane. |
| `admission` | Validated and persisted, not applied at submit time. |
| `reservedSlots` | Carried over from the collapsed `Lane` model; no scheduler reads it. |
| `customScalerUdf` | Reserved for a later phase; the built-in scaler is the only one that runs. |

Check the reference before designing around any single field.

    The behaviors: submit, claim, complete, retry, stream — and the state a
    task moves through.

    What `providerRef` adds: scaling policies, the controller tick, and the
    event feed.

    The full CLI surface and the current state of each field.

    What `providerRef` points at, and which provider types can launch today.

---

Source: https://docs.dreamlake.ai/lakeshore/queues/task-queue

# Task queue

  Strip the launch policy away and a Lakeshore queue is an ordinary task queue:
  producers submit work, workers claim it, results come back by id. This page is
  that half on its own — everything here holds whether or not a provider is
  attached.

Set `providerRef: null` and the queue *is* only this. Nothing autoscales,
nothing is provisioned, and the queue runs on whatever workers you attached
yourself — a lab machine, an allocation you already hold, your laptop. Adding a
provider is covered in [Elastic queues](/lakeshore/queues/elastic.md); it changes
who supplies the workers, not the behaviors below.

## Ids, not futures

`submit` returns a **durable string id** — a ULID — not a handle bound to your
process:

```python
inv = f.submit(x=1)          # -> "01JD2K7Q...": a string, persist it anywhere
result = q.result(inv)       # poll from this process, or any other, later
```

That is the load-bearing choice. There is no Future type in the SDK, no
`gather`, no `as_completed`. A submitting process can exit; another can pick the
id up and read the result. Reconnection is the default case rather than a
recovery path.

## The lifecycle

An invocation moves through a small state machine:

```
              submit()
                 │
                 ▼
            [ queued ]  ──── a worker claims it
                 │
                 ▼
            [ running ]
           ┌─────┼─────┬──────────┐
           ▼     ▼     ▼          ▼
     [succeeded] [failed] [killed] [timeout]
```

`queued` and `running` are the live states; the other four are terminal. The
terminal state is what `q.result(inv)` resolves against — a `failed` invocation
carries its error rather than raising at submit time.

> **Note:** The shape is the same one [zaku](https://github.com/geyang/zaku) uses —
>   `created → in_progress → completed | failed` — with two extra terminal states
>   for the cases a remote worker adds: `killed` when the invocation is cancelled
>   out from under the worker, and `timeout` when it exceeds `timeout_s`. The
>   practical difference is where the payload lives: zaku puts it in S3 under
>   `zaku/{queue}/{job_id}` and the client deletes it on completion, while
>   Lakeshore keeps small payloads inline as msgpack on the invocation and spills
>   larger ones to a storage reference.

## Idempotent submits

Pass `_key=` and the submit becomes idempotent:

```python
inv = f.submit(x=1, _key="nightly-2026-08-06")
```

Resubmitting the same key returns the **existing** invocation id rather than
creating a second one. The key is unique per **namespace + queue**, so the same
key against a different queue is a different job. This is the retry-safe path
for anything a scheduler might fire twice.

## Streaming results

A generator body does not have to finish before you can read from it. Yields
become `VALUE` frames in a journal, terminated by an `END` frame, and the
stream replays from a cursor:

```python
for frame in q.stream(inv, since=cursor):
    ...
```

`since` is a 0-based sequence cursor, so a consumer that drops off can resume
from where it stopped instead of re-reading the whole stream. `Topic` is the
same journal spelled as pub/sub.

## Back-pressure

The `admission` block on the queue is where depth limits are declared —
`max_depth`, `on_full: reject | block`, `rate_limit`, `deadline_cutoff_s`.

> **Warning:** These fields are validated and persisted, but nothing applies them at submit
>   time. A queue with `max_depth: 100` will accept the 101st invocation today.
>   Treat the block as declared intent until the reference says otherwise.

## Running a worker

The whole plane fits in one process when you want to test:

```python
import dreamlake.lakeshore as dls

q = dls.Dispatch(":memory:")      # a full plane, in-process
dls.run_worker(q, once=True)      # drain exactly one job and return
```

`once=True` drains a single job, which is what makes a test deterministic. Drop
it for a worker that keeps pulling.

## Bodies and I/O

One decorator covers four body kinds — sync, generator, async, and
async-generator. `inspect` picks the shape once at decoration; there is no mode
flag and no second decorator. See [Simple functions](/lakeshore/patterns.md) for the decorator
itself and [UDF patterns](/lakeshore/patterns.md) for the shapes side by side.

File bytes never ride the wire. Bodies read and write through `dls.run.read` /
`dls.run.write` under a `dls.scope(prefix)` and return the **keys** they wrote,
so the payload on the invocation stays small and the data stays in storage.

    Attach a provider and the same queue starts supplying its own workers.

    The record behind all of this, field by field.

---

Source: https://docs.dreamlake.ai/lakeshore/queues/elastic

# Elastic queues

  A [task queue](/lakeshore/queues/task-queue.md) runs on workers you attached. Set
  `providerRef` and the same record becomes a **launch queue**: the control
  plane watches its backlog and provisions workers to drain it.

Nothing about the task-queue half changes. Submit, claim, complete, and stream
behave identically — the queue simply stops depending on you to supply capacity.

## The three fields

| Field | What it sets |
| --- | --- |
| `providerRef` | The [provider](/lakeshore/providers.md) to launch through, by name. `null` means bring your own worker. |
| `elasticity` | The scaling rule — `fixed`, `fully_elastic`, `pool_with_threshold`, or `max_count`, plus `min` / `max` / `threshold`. |
| `daemonTemplate` | What a launched worker looks like: `instance_type`, `image_id`, `runner`, `setup_scripts`. Arguably [derivable from the run declaration](/lakeshore/host-setup.md#one-config-not-two--and-a-derived-host-key) rather than written by hand. |

## The four policies

- **`fixed`** never launches or retires anything. The pool is whatever you
  attached — this is the task-queue case with a provider recorded but unused.
- **`fully_elastic`** tracks the backlog directly, bounded by `min` and `max`.
  With `min: 0` it scales to zero, which is what you want for bursty GPU work
  that can absorb a cold start.
- **`pool_with_threshold`** scales on utilization with hysteresis — a high and
  a low watermark, and a run of consecutive ticks before it acts either way. Use
  it when you want warm capacity and no flapping.
- **`max_count`** is demand-driven with a required ceiling.

> **Note:** A fast lane and a heavy lane are two `Queue` rows differing in
>   `daemonTemplate` and `elasticity` — `fast` as `pool_with_threshold` with a
>   small warm minimum, `heavy` as `fully_elastic` from zero on GPU instances.
>   Routing is caller-side: `@udf(queue="heavy")`. There is no automatic
>   classification.

## How the controller decides

The elasticity controller ticks on a fixed interval. On each tick it joins
pending invocations to their queue by name, compares the backlog against the
policy, and launches or retires daemons through the queue's provider.

Every decision is written as an `ElasticityEvent` — **including the ones where
it decided to do nothing.** That is the useful part. "Why did my cluster not
scale up" is answerable from the event feed, because a noop is a logged decision
with a reason rather than an absence of evidence.

```bash file="terminal"
lakeshore queues events gpu-train     # the decision feed, noops included
lakeshore queues stats gpu-train      # daemon count, utilization, pending
```

## What a provider must support

`providerRef` names a provider, but not every provider kind can be launched
into. Only **EC2**, **GCE**, and **Kube** are accepted by the launch routes;
SSH and SLURM providers can be registered and are rejected at launch, so a queue
pointing at one cannot grow workers.

See [Providers](/lakeshore/providers.md) for the current status of each kind and
what the `[ dev ]` marker means.

## Scale to zero, and the cold start it buys

`fully_elastic` with `min: 0` retires the last worker when the backlog clears.
The next submit then pays a full provision — instance launch, image pull, setup
scripts — before anything runs. That is the trade the policy exists to make. If
the latency matters more than the idle cost, `pool_with_threshold` with a
non-zero minimum keeps one worker warm.

`daemonTemplate.setup_scripts` runs on each launched worker, so a heavy setup is
paid per worker, not once per queue. Bake what you can into `image_id` instead.

> **Warning:** `/queues/:name/stats` computes utilization from the daemon-reported invocation
>   counts. The daemon reports its maximum capacity but not its current in-flight
>   count, so the utilization figure can be structurally zero even on a busy
>   queue. The controller itself does not depend on this — it counts pending
>   invocations directly — but a dashboard reading the stats endpoint will
>   understate load.

    The behaviors that do not change when a provider is attached.

    The record behind both halves, field by field.

    Scaling policies, pools, and how the controller ticks.

    Thresholds, hysteresis, and the signals the autoscaler reads.

---

Source: https://docs.dreamlake.ai/lakeshore/providers

# Providers

  A provider is the account or connection Lakeshore launches compute through — a
  cloud credential, a cluster endpoint, a machine you already own. A queue points
  at one via `providerRef` when it should grow its own workers.

Each provider picks exactly one **launcher**, and the control plane accepts
exactly five, spelled exactly like this. Entries carry a marker when they are not
yet finished: **`[ draft ]`** means designed but nothing built, **`[ dev ]`**
means you can configure it but it will not carry a workload end to end.

| Launcher            | Launches onto                                     | Server-side launch |
| ------------------- | ------------------------------------------------- | ------------------ |
| [EC2](/lakeshore/providers/ec2.md)     | An AWS instance it provisions      | yes                |
| [GCE](/lakeshore/providers/gce.md)     | A Google Cloud VM it provisions    | yes                |
| [Kube](/lakeshore/providers/kube.md)   | A Pod on a cluster you already run | yes                |
| [SSH](/lakeshore/providers/ssh.md) `[ dev ]`     | A host that already exists | no — CLI only |
| [SLURM](/lakeshore/providers/slurm.md) `[ dev ]` | A cluster login node       | no — stub     |

EC2, GCE and Kube are the three a queue can grow workers on. SSH registers and
runs from the CLI but has no server-side launch route; SLURM's `sbatch` submit
path is still a stub. A half-supported provider can exist at all because
`Provider.kind` is a free-form `String` rather than a constrained enum, and the
two lists in front of it disagree — registration accepts all five names, the
launch routes accept only three, and answer 422 for the other two.

Credentials never sit in the row as plaintext: kwargs reference them with a
`{ "$secret": "<name>" }` marker, and the secret is decrypted in memory inside
the launch handler only.

Each launcher's own fields, routes and setup live on its page above. The rest of
this page is the cross-cutting machinery — how providers are registered, stored,
merged and scoped, whichever launcher you picked.

## Dispatch

**Dispatch** picks how work reaches the host:

- `direct` — the launch is initiated per call from outside: an SSH session, an
  `sbatch` submission, a `kubectl apply`. Nothing long-lived runs on the host.
- `daemon` — a `nymph` daemon on the host long-polls the control plane and pulls
  work. The daemon always initiates the connection, so this works behind NAT with
  no inbound port.

`EC2` and `GCE` default to `daemon`; `Kube`, `SSH` and `SLURM` default to
`direct`. Set `dispatch` explicitly on a provider to override its default.

## Registering a provider

Providers live on the control plane. Register them with the CLI:

```bash
lakeshore providers add aws-us-east --launcher EC2 \
  --kwarg region=us-east-1 \
  --kwarg key_name=lakeshore-ops \
  --kwarg security_group=sg-0123abc \
  --kwarg iam_instance_profile_arn='arn:aws:iam::123456789012:instance-profile/lakeshore-worker'
```

Names must match `^[a-z0-9][a-z0-9-]*$`. `--kwarg` is repeatable and dotted keys
nest (`--kwarg aws_credentials.accessKeyId=AKIA…` builds a nested object).
`--kwargs-file <path>` loads a YAML or JSON base that `--kwarg` then layers on
top.

All five launchers register through this one command shape — an SSH or SLURM
provider is accepted and stored exactly like a cloud one. It is the launch side
that is not there yet for those two.

### Wire shape

The API body is `{ name, launcher, kwargs, dispatch? }`. The database column
names differ, which matters when reading the Prisma schema:

| API field  | DB column                  |
| ---------- | -------------------------- |
| `launcher` | `Provider.kind`            |
| `kwargs`   | `Provider.config`          |
| `dispatch` | `Provider.config.dispatch` |

Reads split `dispatch` back out and fill in the launcher default when it was
never set, so a `GET` always reports a concrete value.

Kwargs are an open bag — the control plane validates only that
`{ "$secret": "<name>" }` markers name a secret that exists in the namespace
(422 otherwise). Everything else round-trips verbatim, so a new launcher field
works without a schema change.

### Editing

```bash
lakeshore providers update aws-us-east --kwarg region=us-west-2
lakeshore providers update aws-us-east --dispatch daemon
lakeshore providers update aws-us-east --tunnel wg-lab     # "" clears it
```

`--kwarg` deep-merges (`key=null` deletes a key); `--kwargs-file` replaces kwargs
wholesale. `--launcher` is **immutable** — supplying it is an error, so changing
launcher means remove and re-add.

## The `.dreamrc` fallback

For solo dev the CLI also reads a local `.dreamrc`, resolving providers without a
control-plane round trip. Entries are YAML-tagged mappings and the tag names the
launcher class. Only `!providers.SSH`, `!providers.SLURM`, `!providers.EC2`,
`!providers.GCE`, and `!providers.Kube` are known tags — anything else is a hard
parse error.

`.dreamrc` is resolved first-hit-wins in this order: `--dreamrc <path>`,
`$DREAMRC`, `./.dreamrc` walked up from cwd, `$HOME/.dreamrc`, a server pull
(needs auth or `LAKESHORE_URL`), the on-disk cache of a previous pull, then an
empty config. The server pull composes a `DreamRc` from the namespace's
`providers` and `modes` endpoints, so the two forms converge.

Credentials in a local `.dreamrc` are inline. Treat the file like a `.env` and
never commit it.

## Referencing a provider from a mode

A **mode** is a stored `RunConfig`. It carries the per-machine fields and names
its provider by string:

```bash
lakeshore modes add h100 \
  --field provider=aws-us-east \
  --field instance_type=g5.xlarge \
  --field image_id=ami-0abcdef1234567890 \
  --field runner=docker \
  --field image=ghcr.io/lakeshore-py/cuda12.4-pytorch:2.4 \
  --field resources.gpu=1
```

> **Warning:** The override flag is `--field` on `modes add` / `modes update` and `--kwarg` on
> `providers add` / `providers update`. Both are repeatable and both nest on dotted
> keys, but the names are not interchangeable.

The mode's recognised fields are `backend`, `runner`, `image`, `tags`,
`resources`, `env`, `timeout_s`, and `provider`. Anything else is stashed under
`resources.__extras` and folded back in on read, so unknown keys survive a round
trip. Neither `backend` nor `runner` is validated by the API: the create handler
defaults them to `fabric` and `process` and otherwise accepts any string.

In a local `.dreamrc`, the root of the file *is* the default `RunConfig` and
named alternatives live under `modes:` (alias `mode:`).

## What happens at launch

Merge rules are the same wherever the merge happens:

1. Resolve `provider` on the `RunConfig` to the provider row.
2. **Deep-merge** the provider kwargs with the `RunConfig`'s launcher-shaped
   kwargs. Nested objects merge recursively, arrays concatenate and dedupe, and
   on a scalar conflict the `RunConfig` wins.
3. Runner-side config (`runner`, `image`, `resources`, `env`, `tags`,
   `timeout_s`) stays on the `RunConfig` — the runtime layer consumes it, not the
   launcher.
4. Resolve `{ "$secret": "<name>" }` markers by decrypting the named `Secret` in
   memory. An `aws_keypair` secret is stored as
   `<access_key_id>:<secret_access_key>` and expands to
   `{ accessKeyId, secretAccessKey }`; every other kind substitutes its UTF-8
   plaintext. Plaintext never leaves the handler and is never serialized back to
   the wire. See
   [Secrets](https://lakeshore.dreamlake.ai/api/auth-and-secrets#secrets).
5. Call the cloud API, or open the SSH session.

The control plane holds the SDK clients and the decrypted credentials; the CLI
never talks to AWS, Google, or the apiserver directly. Every launched instance is
tagged or labelled with `lakeshore=true`, the namespace, and the provider name,
so `instances` listings filter cleanly.

## Visibility and lifecycle

`remove` is a **soft delete**. The row keeps its history and gets a tombstone
suffix (`<name> [deleted <iso>]`) appended so the `(namespace, name)` unique
index stays intact and a later `providers add <name>` does not collide.
Responses strip the suffix, so callers always see the original name.

| State       | Set by                                              | Effect on listings |
| ----------- | --------------------------------------------------- | ------------------ |
| `hidden`    | `PATCH .../providers/:name` with `{ hidden: true }` | Excluded by default; `--hidden` opts back in. |
| `deletedAt` | `DELETE .../providers/:name`                        | Excluded by default; `--deleted` opts back in. Restore with `POST .../providers/:name/restore`. |

```bash
lakeshore providers list              # active + visible
lakeshore providers list --hidden     # also hidden
lakeshore providers list --deleted    # also soft-deleted
lakeshore providers list --all        # everything
lakeshore providers list --json
```

The table prints `NAME`, `LAUNCHER`, `DISPATCH`, `KWARGS`. Hidden rows render as
`name  [H]` and soft-deleted rows as `name  [D <iso>]`, with the bare name still
first so `grep` by name keeps working.

### Interactive editor

```bash
lakeshore providers edit
```

Two steps. First a picker over the listing — the first entry is a synthetic
toggle that flips the hidden + deleted filter without leaving the editor, the
second is quit. Then an action menu that adapts to the row: an active row offers
hide and delete, a hidden row offers unhide and delete, a soft-deleted row offers
restore. The list refetches between iterations, so each action shows up in the
next frame. Ctrl-C exits cleanly.

## Namespace and org scoping

Providers belong to a namespace. What you see depends on whether that namespace
has an `orgId`:

- **With an `orgId`** — listings, name lookups, and duplicate-name checks span
  every namespace sharing that `orgId`. Provider names must be unique across the
  org, and a token scoped to one member namespace works against its siblings.
- **Without an `orgId`** — the listing is *unscoped*: the namespace sees every
  provider on the control plane.

Give tenant namespaces an `orgId` if you want provider isolation between teams.
See [Admin setup](https://lakeshore.dreamlake.ai/admin/setup) for how to set one.

## Not built yet

- **SLURM launch.** The launch routes support only `EC2`, `GCE`, and `Kube`, and
  `providers test` on a SLURM provider prints a stub message. Clearing that is
  what clears its `[ dev ]` marker.
- **SSH through the server.** The CLI drives SSH directly, but no server-side
  route does, so a queue cannot grow workers on an SSH provider.
- **Hybrid dispatch** — go direct on the first call, leave a daemon behind for
  later ones. Pick one mode for now.
- **Cross-provider scheduling** — listing, claiming, and leasing capacity across
  providers. Design only.

---

Source: https://docs.dreamlake.ai/lakeshore/providers/ec2

# EC2 Provider

`--launcher EC2` provisions AWS instances. The control plane owns the
AWS SDK client and the decrypted credentials — the CLI never talks to
EC2 directly. The default `dispatch` is `daemon`: the instance's userdata
installs a `nymph` daemon that long-polls for work.

| Phase | What happens |
| ----- | ------------ |
| Provision | `RunInstances` via `@aws-sdk/client-ec2`, with your script base64-encoded into `UserData`. |
| Launch | Whatever the userdata script does — normally install and start the daemon. |
| Default dispatch | `daemon` |

## Where the launch happens

There are **two** launches here, and only the first one touches credentials.

| | Who acts | Credentials |
| --- | --- | --- |
| 1. Provision the box | control plane calls `RunInstances` | AWS keys, held by the control plane |
| 2. Get work to it | the nymph long-polls outbound | none — the daemon's own bearer token |

Step 2 is the same on every launcher. Step 1 is where EC2 differs from
SLURM and Kube: on those two a nymph can do the submitting itself
(`runner/slurm.rs`, `runner/kube.rs`), so the credential stays inside the
cluster. **There is no `ec2` runner in nymph** — `runner/mod.rs` registers
`process`, `docker`, `gvisor`, `slurm`, `kube`, `exec`, and `mock`, and
nothing else. So provisioning an instance is something only the control
plane can do.

> **Warning:** `aws_credentials` resolves from the Secret store into an `{ accessKeyId,
> secretAccessKey }` pair inside the control-plane process. The CLI genuinely
> never sees them — but "the CLI never sees them" is a weaker claim than
> "they never leave your account," and only the first one is true today.
> Scope the IAM user narrowly; see [Setting up a dedicated IAM
> user](#setting-up-a-dedicated-iam-user).

## Kwargs

These are the keys the EC2 launcher reads out of the merged
provider + `RunConfig` kwargs. Everything else round-trips on the row but
does not reach the SDK call.

| Field | Where it usually lives | Meaning |
| ----- | ---------------------- | ------- |
| `region` | provider | AWS region for the SDK client. |
| `aws_credentials` | provider | `{ accessKeyId, secretAccessKey }`. Omit to fall back to the SDK's default credential chain on the server. |
| `key_name` | provider | EC2 key-pair name → `KeyName`. |
| `security_group` | provider | One security group id → `SecurityGroupIds`. Use `security_group_ids` for a list. |
| `subnet_id` | provider | → `SubnetId`. |
| `iam_instance_profile_arn` | provider | → `IamInstanceProfile.Arn`. |
| `image_id` (or `ami`, or `ImageId`) | mode | **Required.** The launch throws without it. |
| `instance_type` (or `InstanceType`) | mode | Defaults to `t3.micro`. |

> **Warning:** The launcher builds a fixed `RunInstances` parameter set. There is no
> `spot_price`, no `availability_zone`, and no `dry` handling — setting
> those kwargs stores them on the row and changes nothing about the call.

Every instance is tagged `lakeshore=true`, `namespace=<ns>`, and
`provider=<name>`, plus any `tags` you pass on the launch body. User tags
that collide with those three reserved keys are dropped rather than
duplicated, which EC2 would reject.

## Seeding from an AWS profile

If the credentials already live in `~/.aws/credentials` +
`~/.aws/config`, skip the typing:

```bash
lakeshore aws discover                # what the CLI can see locally
lakeshore providers add aws-dev --from-aws-profile sandbox
```

`--from-aws-profile <name>` seeds `aws_credentials.accessKeyId`,
`aws_credentials.secretAccessKey`, `aws_credentials.sessionToken` (when
present), and `region` (when the profile or its config section sets one),
and infers `--launcher EC2`. Layer `--kwarg` on top for the rest:

```bash
lakeshore providers add aws-dev \
  --from-aws-profile sandbox \
  --kwarg key_name=lakeshore-ops \
  --kwarg security_group=sg-0a1b2c3d4e5f \
  --kwarg iam_instance_profile_arn='arn:aws:iam::…:instance-profile/lakeshore-worker'
```

**SSO profiles are rejected.** Any `sso_*` key in either file flags the
profile, and the launcher needs static keys. Run
`aws configure --profile <name>`, or pass the pair explicitly with
`--kwarg aws_credentials.accessKeyId=… --kwarg aws_credentials.secretAccessKey=…`.

Tab completion on `--from-aws-profile ` lists the local profile
names — see [Completion](https://lakeshore.dreamlake.ai/cli/completion).

> **Warning:** `--from-aws-profile` writes the keys straight into the provider kwargs.
> Fine for a scratch provider; move them into a Secret before the provider
> is shared.
>
> ```bash
> # The aws_keypair plaintext format is exactly `<access_key_id>:<secret_access_key>`.
> printf '%s:%s' AKIA… wJal… | lakeshore secrets add aws-dev-keys --kind aws_keypair
> lakeshore providers update aws-dev --kwarg aws_credentials='{"$secret":"aws-dev-keys"}'
> ```
>
> The launcher recognises `aws_keypair` secrets specially: it splits the
> plaintext on the first `:` and substitutes
> `{ accessKeyId, secretAccessKey }`. See
> [Secrets](https://lakeshore.dreamlake.ai/api/auth-and-secrets#secrets).

## Example

**.dreamrc tab:** The same shape in a local `.dreamrc`:

**CLI**

```bash
lakeshore providers add aws-us-east --launcher EC2 \
  --kwarg region=us-east-1 \
  --kwarg key_name=lakeshore-ops \
  --kwarg security_group=sg-0a1b2c3d4e5f \
  --kwarg iam_instance_profile_arn='arn:aws:iam::123456789012:instance-profile/lakeshore-worker'

lakeshore modes add gpu \
  --field provider=aws-us-east \
  --field instance_type=g5.xlarge \
  --field image_id=ami-0abcdef1234567890 \
  --field runner=docker \
  --field image=ghcr.io/lakeshore-py/cuda12.4-pytorch:2.4 \
  --field resources.gpu=1
```

**.dreamrc**

```yaml file=".dreamrc"
providers:
  aws-us-east: !providers.EC2
    region: us-east-1
    key_name: lakeshore-ops
    security_group: sg-0a1b2c3d4e5f
    iam_instance_profile_arn: arn:aws:iam::123456789012:instance-profile/lakeshore-worker

modes:
  gpu:
    provider: aws-us-east
    instance_type: g5.xlarge
    image_id: ami-0abcdef1234567890
    runner: docker
    image: ghcr.io/lakeshore-py/cuda12.4-pytorch:2.4
    resources: { gpu: 1 }
```

## Server-side routes

| Verb | Path | Result |
| ---- | ---- | ------ |
| `POST` | `/v1/namespaces/:ns/providers/:name/launch` | 202 `{ instanceId, state, providerName, launchedAt }` |
| `GET` | `/v1/namespaces/:ns/providers/:name/instances` | Instances tagged `lakeshore=true` for this namespace + provider |
| `DELETE` | `/v1/namespaces/:ns/providers/:name/instances/:id` | 204 |

`launch` requires a non-empty `script` (a complete bash userdata blob,
capped at 256 KiB) and takes optional `runConfigKwargs` and `tags`. The
launcher base64-encodes the script and hands it to `RunInstances`
verbatim — it never templates or interprets it.

`instanceId` is the EC2 instance id (`i-0abc1234`). `state` is normalized
from the SDK's `State.Name`: `pending → starting`, `running → running`,
`shutting-down`/`stopping → stopping`, `stopped`/`terminated`/`terminating
→ stopped`, anything else `unknown`. At launch time it is almost always
`starting` — poll `instances` to watch it become `running`.

AWS errors on a known list (`UnauthorizedOperation`, `AccessDenied`,
`InvalidAMIID.NotFound`, `InsufficientInstanceCapacity`, and friends)
come back as 502 with `{ error, awsCode, message }`; anything else is a
500, on the theory that it is our bug.

## Launching a daemon

For the `daemon` dispatch path you normally do not call `/launch`
yourself. `POST /v1/namespaces/:ns/daemons/launch` — the route behind
`lakeshore daemon launch` — renders the nymph bootstrap script (download
the binary, drop the unit, start it, point it at the control plane) and
passes it to this same launcher as the userdata:

```bash
lakeshore daemon launch --provider aws-us-east --name gpu --count 4 \
  --queue training --runner docker --keep-alive 1800 --wait
```

The bootstrap script's control-plane URL comes from
`LAKESHORE_PUBLIC_URL` on the server (falling back to
`LAKESHORE_SERVER_URL`, then `LAKESHORE_URL`, then localhost), so set
that on a deployed control plane or the daemons will try to reach
`http://localhost:8080`.

## Smoke test

```bash
lakeshore providers test aws-us-east
lakeshore providers instances aws-us-east
```

`providers test` posts a launch through the control plane. Streaming
stdout from the instance back to the CLI is not implemented — check the
instance over SSH, via `lakeshore daemon launch-log <id>` (EC2 serial
console), or by polling `instances`.

## Setting up a dedicated IAM user

For a fresh AWS account, the one-time path is: sign in as root → IAM →
create a programmatic user → attach a policy → create an access key →
wire it locally → register with Lakeshore.

1. Sign in as root at `https://signin.aws.amazon.com/` (with MFA).
2. **IAM → Users → Create user.** Leave console access unchecked —
   programmatic only.
3. **Permissions → Attach policies directly.** `AdministratorAccess` is
   the blunt option and covers everything the launchers touch. The
   minimum for EC2 alone is `ec2:RunInstances`, `ec2:Describe*`,
   `ec2:CreateTags`, `ec2:TerminateInstances`, plus `iam:PassRole` if you
   attach an instance profile.
4. **Security credentials → Create access key → Command Line Interface.**
5. On the success page, wire it up before navigating away — the secret is
   shown exactly once.

```bash
aws configure --profile lakeshore-dev
aws sts get-caller-identity --profile lakeshore-dev    # should print the IAM ARN

lakeshore providers add aws-us-east --from-aws-profile lakeshore-dev

# Then move the inline credentials into a Secret (see the callout above).
```

### Rotation

Static IAM keys never expire on their own. Rotate roughly every 90 days:

1. Create a **second** access key for the same user — AWS allows two
   active keys precisely so you can roll without downtime.
2. `aws configure --profile lakeshore-dev` with the new pair.
3. `printf '%s:%s' <new-id> <new-secret> | lakeshore secrets rotate <secret-name>`.
   Plaintext comes from `--from-file <path>` or piped stdin; there is no
   `--from-file -` form, so pipe it.
4. Smoke test: `lakeshore providers test aws-us-east`.
5. **Only then** deactivate the old key in the console, wait a day for
   stragglers to surface, and delete it.

Deactivate-then-delete is the point: a straggler on a deactivated key
fails visibly and reversibly. Deleting outright makes it fail
permanently and anonymously.

## OIDC federation — not built

Static keys in the control-plane database do not scale to "run in the
customer's AWS account." The clean answer is OIDC federation, the model
GitHub Actions uses: the control plane becomes an identity provider, the
customer creates an IAM role trusting it with `sub`/`aud` pinned to a
namespace, and each launch calls `sts:AssumeRoleWithWebIdentity` for
short-lived credentials. No keys at rest, per-launch audit.

None of that exists yet. It would need a JWKS + discovery endpoint on
the control plane with signing-key rotation, a `aws_role_arn` kwarg
mutually exclusive with `aws_credentials`, and an `AssumeRoleWithWebIdentity`
call in the EC2 launcher instead of the current credential passthrough.

AWS IAM Identity Center is not an alternative: SSO refresh is
fundamentally interactive, and a server has no browser session to renew
from. OIDC sidesteps that by making the control plane the issuer rather
than a consumer.

---

Source: https://docs.dreamlake.ai/lakeshore/providers/gce

# GCE Provider

`--launcher GCE` provisions Google Compute Engine VMs. The control plane
owns the `@google-cloud/compute` client and the decrypted credentials —
the CLI never calls Google APIs directly. The default `dispatch` is
`daemon`: the VM's startup script installs a `nymph` daemon that
long-polls for work.

| Phase | What happens |
| ----- | ------------ |
| Provision | `instances.insert`, with your script attached verbatim as the `startup-script` metadata key. |
| Launch | Whatever the startup script does — normally install and start the daemon. |
| Default dispatch | `daemon` |

## Where the launch happens

Structurally identical to [EC2](/lakeshore/providers/ec2.md#where-the-launch-happens):
two launches, and only the first touches credentials.

| | Who acts | Credentials |
| --- | --- | --- |
| 1. Provision the VM | control plane calls `instances.insert` | GCP service-account key, held by the control plane |
| 2. Get work to it | the nymph long-polls outbound | none — the daemon's own bearer token |

There is no `gce` runner in nymph, so — as with EC2 — provisioning is
something only the control plane can do. Once the VM is up, the daemon on
it behaves exactly like any other.

> **Warning:** `dreamlake provider create` ships templates for `ssh`, `slurm`, `docker`
> (adopt an existing host) and `kube`, `ec2` (terraform to provision new
> infrastructure). **GCE has neither.** Register the provider against a VM you
> made yourself until a template lands.

## Kwargs

Required for a launch to succeed at all:

| Field | Where it usually lives | Meaning |
| ----- | ---------------------- | ------- |
| `project_id` | provider | GCP project. |
| `zone` | provider | e.g. `us-central1-a`. Also used to qualify machine and accelerator types. |
| `instance_type` | mode | Machine type, e.g. `n1-standard-8`, `a2-highgpu-1g`. |
| `image_id` **or** (`image_project` + `image_family`) | mode | The boot image. `image_project` + `image_family` expand to `projects/<p>/global/images/family/<f>`. |

Optional:

| Field | Meaning |
| ----- | ------- |
| `gcp_sa_json` | Service-account JSON for the SDK client. Omit to use the server's Application Default Credentials. |
| `name` | Instance name. Defaults to an auto-generated `lakeshore-<8 hex>` slug. |
| `boot_size` | Boot disk size in GB (number or string). |
| `accelerator_type` + `accelerator_count` | Attaches guest accelerators. Both are required together; setting them also forces `onHostMaintenance: TERMINATE`, which GCE requires. |
| `preemptible` | Exactly `true` sets `scheduling.preemptible`. |
| `tags` | A **list of strings** → network tags (firewall targeting). Not to be confused with the launch body's `tags`, which become labels. |
| `labels` | An object of label key/values, merged under the reserved ones. |

Every VM comes up on the `default` network with an ephemeral external IP
— the same shape `gcloud` produces with no flags — and with
`autoDelete: true` on the boot disk.

Labels always include `lakeshore=true`, `namespace=<ns>`, and
`provider=<name>`; user labels colliding with those three are dropped.
The `instances` listing filters on exactly those labels.

## Seeding from a gcloud configuration

```bash
lakeshore gcp discover                          # what the CLI can see locally
lakeshore providers add gcp-dev --from-gcloud-config research
```

`--from-gcloud-config <name>` seeds `project_id` (from `core/project`),
`region` (from `compute/region`), `zone` (from `compute/zone`), and
`gcp_sa_json` from the Application Default Credentials JSON at
`~/.config/gcloud/application_default_credentials.json` when it exists.
It also infers `--launcher GCE`.

`gcp discover` uses `gcloud config configurations list` when the `gcloud`
CLI is installed and otherwise walks `~/.config/gcloud/` directly. Tab
completion on `--from-gcloud-config ` lists the configuration names
— see [Completion](https://lakeshore.dreamlake.ai/cli/completion).

> **Warning:** `gcp_sa_json` lands verbatim in the provider kwargs. Move it into a
> Secret before the provider is shared:
>
> ```bash
> lakeshore secrets add gcp-dev-sa --kind gcp_sa_json --from-file ~/.config/gcloud/application_default_credentials.json
> lakeshore providers update gcp-dev --kwarg gcp_sa_json='{"$secret":"gcp-dev-sa"}'
> ```
>
> With no ADC file present the seeding skips that field and warns. Run
> `gcloud auth application-default login` first, or reference a stored
> secret directly. Note that `GOOGLE_APPLICATION_CREDENTIALS` is **not**
> consulted by the seeding path — only the ADC file.

## Example

**.dreamrc tab:** The same shape in a local `.dreamrc`:

**CLI**

```bash
lakeshore providers add gcp-us-central --launcher GCE \
  --kwarg project_id=my-project \
  --kwarg zone=us-central1-a

lakeshore modes add a100 \
  --field provider=gcp-us-central \
  --field instance_type=a2-highgpu-1g \
  --field image_project=deeplearning-platform-release \
  --field image_family=pytorch-latest-gpu \
  --field accelerator_type=nvidia-tesla-a100 \
  --field accelerator_count=1 \
  --field preemptible=true \
  --field runner=docker \
  --field image=ghcr.io/lakeshore-py/cuda12.4-pytorch:2.4 \
  --field resources.gpu=1
```

**.dreamrc**

```yaml file=".dreamrc"
providers:
  gcp-us-central: !providers.GCE
    project_id: my-project
    zone: us-central1-a

modes:
  a100:
    provider: gcp-us-central
    instance_type: a2-highgpu-1g
    image_project: deeplearning-platform-release
    image_family: pytorch-latest-gpu
    accelerator_type: nvidia-tesla-a100
    accelerator_count: 1
    preemptible: true
    runner: docker
    image: ghcr.io/lakeshore-py/cuda12.4-pytorch:2.4
    resources: { gpu: 1 }
```

## Server-side routes

| Verb | Path | Result |
| ---- | ---- | ------ |
| `POST` | `/v1/namespaces/:ns/providers/:name/launch` | 202 `{ instanceId, state, providerName, launchedAt }` |
| `GET` | `/v1/namespaces/:ns/providers/:name/instances` | VMs labelled `lakeshore=true` for this namespace + provider |
| `DELETE` | `/v1/namespaces/:ns/providers/:name/instances/:id` | 204 |

`instanceId` is the instance **name** — the auto-generated
`lakeshore-<hex>` slug or the `name` you set in kwargs — not a numeric
id. `launch` always returns `state: "starting"`, because
`instances.insert` is an async operation and the SDK returns before the
VM has a real status. Poll `instances` to see it reach `running`.

The listing uses GCE filter syntax on the reserved labels and prefers the
aggregated (cross-zone) list, falling back to a single-zone list when
`zone` is set.

## Launching a daemon

As with EC2, the `daemon` dispatch path normally goes through
`POST /v1/namespaces/:ns/daemons/launch` (`lakeshore daemon launch`),
which renders the nymph bootstrap script and hands it to this launcher as
the startup script. Set `LAKESHORE_PUBLIC_URL` on the control plane so
the script points daemons at the right host.

## Smoke test

```bash
lakeshore providers test gcp-us-central
lakeshore providers instances gcp-us-central
gcloud compute instances list
```

Streaming stdout from the VM back to the CLI is not implemented.

## Setting up a dedicated service account

GCP's default org policies actively block service-account key creation,
so this is heavier than the AWS equivalent. Step 1 needs the console once
per organization; the rest is `gcloud`.

### 1. Claim Organization Administrator (once per org)

A fresh Workspace org has an *unclaimed* GCP organization — nobody holds
`roles/resourcemanager.organizationAdmin`, so nobody can change org
policies. As Workspace super admin:

1. Open `https://console.cloud.google.com/iam-admin/iam?organizationId=`
   (find the id with `gcloud organizations list`).
2. Confirm the resource selector at the top reads your domain, not a
   project.
3. **+ GRANT ACCESS**, principal = your user, grant both
   `Organization Administrator` and `Organization Policy Administrator`.

Google honours your super-admin status as the implicit grantor here even
though no IAM binding gives you the permission.

### 2. Link billing

```bash
PROJECT=my-project
gcloud billing accounts list                       # find one with OPEN = True
gcloud billing projects link $PROJECT --billing-account=<ACCOUNT_ID>
```

A new project has no billing link even when the org has billing
accounts, and compute APIs refuse to enable without one
(`UREQ_PROJECT_BILLING_NOT_FOUND`).

### 3. Enable APIs

```bash
gcloud services enable \
  compute.googleapis.com \
  iam.googleapis.com \
  iamcredentials.googleapis.com \
  orgpolicy.googleapis.com \
  --project=$PROJECT
```

`orgpolicy.googleapis.com` is what makes step 4 possible from the CLI.

### 4. Override the SA-key policy for this project only

```bash
cat > /tmp/sa-key-policy.yaml <<'EOF'
constraint: constraints/iam.disableServiceAccountKeyCreation
booleanPolicy:
  enforced: false
EOF

gcloud resource-manager org-policies set-policy /tmp/sa-key-policy.yaml \
  --project=$PROJECT
rm /tmp/sa-key-policy.yaml
```

Wait 20–60 seconds for propagation, or the next step still fails on the
constraint. Every other project under the org stays protected.

### 5. Create the service account and a key

```bash
SA_NAME=lakeshore-dev
SA_EMAIL=${SA_NAME}@${PROJECT}.iam.gserviceaccount.com
KEY_PATH=~/.config/gcloud/${SA_NAME}.json

gcloud iam service-accounts create $SA_NAME \
  --display-name="lakeshore CLI" --project=$PROJECT

# Retry after ~10s if this reports the account does not exist (IAM propagation).
gcloud projects add-iam-policy-binding $PROJECT \
  --member="serviceAccount:$SA_EMAIL" --role="roles/owner"

mkdir -p ~/.config/gcloud
gcloud iam service-accounts keys create $KEY_PATH --iam-account=$SA_EMAIL
chmod 600 $KEY_PATH
```

`roles/owner` is the blunt option. A narrower equivalent is
`roles/editor` + `roles/compute.admin` + `roles/storage.admin` +
`roles/secretmanager.admin` + `roles/iam.serviceAccountAdmin` +
`roles/compute.networkAdmin`.

### 6. Point ADC at it, set the zone

```bash
gcloud auth activate-service-account --key-file=$KEY_PATH

# The CLI's --from-gcloud-config reads the ADC file, not
# GOOGLE_APPLICATION_CREDENTIALS.
cp $KEY_PATH ~/.config/gcloud/application_default_credentials.json
chmod 600 ~/.config/gcloud/application_default_credentials.json

gcloud config set project $PROJECT
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

gcloud auth list                # the SA should be active
gcloud compute instances list   # 200, possibly empty
```

### 7. Register

```bash
lakeshore providers add gcp-us-central --from-gcloud-config default

lakeshore secrets add gcp-research-sa --kind gcp_sa_json --from-file $KEY_PATH
lakeshore providers update gcp-us-central \
  --kwarg gcp_sa_json='{"$secret":"gcp-research-sa"}'
```

### Rotation

Service-account JSON keys never expire on their own. Rotate roughly every
90 days:

1. Console → the SA → **Keys → Add key → Create new key → JSON**. GCP
   allows up to ten keys per SA, so rolling is easy.
2. Replace the local JSON and the ADC copy.
3. `lakeshore secrets rotate gcp-research-sa --from-file <new.json>`.
4. Smoke test: `lakeshore providers test gcp-us-central`.
5. Only then delete the old key. GCP has no deactivate step — deletion is
   immediate on confirm — so wait a day first and watch the audit logs
   for stragglers.

---

Source: https://docs.dreamlake.ai/lakeshore/providers/kube

# Kube Provider

`--launcher Kube` submits Pods to an existing Kubernetes cluster. Nothing
is provisioned — the cluster is assumed to be there. The default
`dispatch` is `direct`: creating the Pod *is* the launch.

| Phase | What happens |
| ----- | ------------ |
| Provision | None. |
| Launch | One Pod created through `@kubernetes/client-node`, `restartPolicy: Never`. |
| Default dispatch | `direct` |

## Where the launch happens

Kube is the one launcher with **two working paths**, and they differ in who
holds the kubeconfig.

| | Who creates the Pod | Kubeconfig lives |
| --- | --- | --- |
| Control plane (default) | `@kubernetes/client-node`, server-side | in the control plane's Secret store |
| A nymph in the cluster | `kubectl apply`, from `runner/kube.rs` | on the box the nymph runs on |

The second path is the same shape SLURM uses: a nymph that can reach the
scheduler does the submitting itself, so the credential never leaves the
cluster. See [Running a daemon in-cluster](#running-a-daemon-in-cluster) for
when to prefer it — and for the `hostPath` constraint that limits it to
single-node clusters today.

> **Warning:** The spelling is enforced. `k8s`, `K8S`, and `local` are all rejected with a
> 400 — some of those appear in stale comments in the Prisma schema. The launcher
> name is exactly `Kube`.

## Kwargs

Connection (usually on the provider):

| Field | Default | Meaning |
| ----- | ------- | ------- |
| `kubeconfig` | — | A filesystem path, or inline kubeconfig content, or a `{ "$secret": … }` ref. Omit to use the server's `KUBECONFIG` / `~/.kube/config`. |
| `context` | — | Switches the active context after loading. |
| `namespace` | `default` | The Kubernetes namespace the Pod is created in. |

Pod shape (usually on the mode):

| Field | Required | Meaning |
| ----- | -------- | ------- |
| `image` | **yes** | Container image. Missing or empty fails the launch immediately. |
| `resources` | no | Passed straight through as the container's `resources` block — so it takes the real Kubernetes shape, `{ requests: {...}, limits: {...} }`. |
| `env` | no | Object of name → value. Numbers and booleans are stringified; anything else is skipped. |
| `node_selector` | no | → `spec.nodeSelector`. |
| `tolerations` | no | → `spec.tolerations`, verbatim list. |
| `service_account` | no | → `spec.serviceAccountName`. |
| `image_pull_secrets` | no | List of names → `spec.imagePullSecrets`. |

The Pod runs a single container named `user` with
`command: ["/bin/sh", "-c"]`.

> **Warning:** EC2 and GCE take the launch `script` as a bash userdata blob. The Kube
> launcher instead heredocs it into `/tmp/u.py` inside the container and
> runs `python3 /tmp/u.py`, so the image needs a `python3` on `PATH`. This
> is the one launcher where the `script` contract differs.

Labels always include `lakeshore=true`, `lakeshore.namespace=<ns>`, and
`lakeshore.provider=<name>` (slugified). Launch-body `tags` become extra
labels; anything colliding with the three reserved keys is dropped. The
`instances` listing selects on exactly those three.

Pod names are always auto-generated as `lakeshore-<8 hex>` — a `name`
kwarg is not read by this launcher.

## Example

**.dreamrc tab:** The same shape in a local `.dreamrc`:

**CLI**

```bash
lakeshore providers add my-cluster --launcher Kube \
  --kwarg context=prod-east \
  --kwarg namespace=lakeshore

lakeshore modes add k8s-gpu \
  --field provider=my-cluster \
  --field image=ghcr.io/lakeshore-py/cuda12.4-pytorch:2.4 \
  --field resources='{"limits":{"nvidia.com/gpu":1,"cpu":"4"}}' \
  --field node_selector='{"cloud.google.com/gke-accelerator":"nvidia-tesla-a100"}'
```

**.dreamrc**

```yaml file=".dreamrc"
providers:
  my-cluster: !providers.Kube
    context: prod-east
    namespace: lakeshore

modes:
  k8s-gpu:
    provider: my-cluster
    image: ghcr.io/lakeshore-py/cuda12.4-pytorch:2.4
    resources:
      limits: { nvidia.com/gpu: 1, cpu: "4" }
    node_selector: { "cloud.google.com/gke-accelerator": nvidia-tesla-a100 }
```

## Credentials

Same as `kubectl`. With no `kubeconfig` kwarg the server loads its
default config (`KUBECONFIG` or `~/.kube/config`). A `kubeconfig` string
that looks like a path (starts with `/`, `./`, or `~` and has no
newlines) is loaded from disk; anything else is treated as inline
kubeconfig content and staged to a temp file. A `{ "$secret": … }` ref
resolves to plaintext, gets written to a chmod-600 temp file for the
duration of the SDK call, and is cleaned up in a `finally`. See
[Secrets](https://lakeshore.dreamlake.ai/api/auth-and-secrets#secrets).

## Server-side routes

| Verb | Path | Result |
| ---- | ---- | ------ |
| `POST` | `/v1/namespaces/:ns/providers/:name/launch` | 202 `{ instanceId, state, providerName, launchedAt }` |
| `GET` | `/v1/namespaces/:ns/providers/:name/instances` | Pods matching the three reserved labels |
| `DELETE` | `/v1/namespaces/:ns/providers/:name/instances/:id` | 204 — deleting an already-gone Pod is idempotent |

`instanceId` is the Pod name. `state` comes from the Pod at create time:
a `deletionTimestamp` means `stopping` regardless of phase, otherwise
`Pending → starting`, `Running → running`, `Succeeded`/`Failed →
stopped`, anything else `unknown`. At create time it is normally
`starting`; poll `instances` to watch it become `running`.

## Running a daemon in-cluster

Set `dispatch: daemon` when the cluster cannot reach the control plane,
when you want every launch to flow through one in-cluster service you can
audit, or when you would rather not hand the control plane a kubeconfig
with broad permissions.

Note that `nymph` also has its own `kube` runner, which is a different
thing: a daemon *already running* can render a Pod manifest and
`kubectl apply` it per invocation. That runner mounts the daemon's
workdir into the Pod with a `hostPath` volume, so it only works when the
daemon and the Pod land on the same node — a single-node kind / minikube
/ k3d cluster, or a DaemonSet. Multi-node needs an RWX volume, which is
not built.

## Smoke test

```bash
lakeshore providers test my-cluster
lakeshore providers instances my-cluster
kubectl get pods -n lakeshore
```

Streaming stdout from the Pod back to the CLI is not implemented — read
it with `kubectl logs`.

---

Source: https://docs.dreamlake.ai/lakeshore/providers/ssh

# SSH Provider

**`[ dev ]`** — you can register an SSH provider and drive it from the CLI, but
no server-side launch route accepts one, so a [queue](/lakeshore/queues.md) cannot
grow workers on it. See [Providers](/lakeshore/providers.md) for what the marker
means.

`--launcher SSH` means "connect to a host that is already running."
Nothing is provisioned. The default `dispatch` is `direct`: the CLI opens
an SSH session per call and runs the script. Use it for lab boxes, dev
machines, and any server you keep around by hand.

| Phase | What happens |
| ----- | ------------ |
| Provision | Nothing. The host is expected to be up and reachable. |
| Launch | An `ssh` session runs the script. |
| Default dispatch | `direct` |

SSH providers are the one launcher the CLI drives itself — the control
plane's `/providers/:name/launch` routes support only `EC2`, `GCE`, and
`Kube`, and answer 422 for an SSH provider. `lakeshore providers test`
and `lakeshore providers instances` both shell out to the local `ssh`
binary.

## Kwargs

These are the keys the CLI's SSH paths actually read:

| Field | Type | Default | Meaning |
| ----- | ---- | ------- | ------- |
| `ip` (or `host`) | string | — | **Required.** Host IP or DNS name. |
| `username` (or `user`) | string | `ubuntu` | SSH user. |
| `port` | int | 22 | SSH port. |
| `pem` | string | — | Path to a private key on the *local* machine. `~` is expanded. |

`lakeshore ssh upload` writes a few more keys that survive on the row and
are handed to whatever consumes them later: `proxy_jump`,
`proxy_command`, `ssh_options` (a bag of leftover `ssh_config`
directives), and `_meta.sshFingerprint`.

Kwargs are an open bag, so any other key you set round-trips
untouched — but only the four above change how the CLI dials the host
today.

> **Warning:** `lakeshore ssh upload --with-key` stores the private key as an `ssh_key`
> Secret and writes `ssh_key: { "$secret": "<name>" }` into the kwargs. The
> CLI's own `ssh` invocation reads only `pem` — a local file path — so a
> provider whose key lives in a Secret has no key for `providers test` to
> pass to `ssh -i`. Keep a local `pem` path as well if you want the direct
> path to work.

## RunConfig fields

None. An SSH host is fixed, so there is no per-machine choice to make at
call time and a mode pointing at an SSH provider adds no
launcher-shaped fields.

Hardware on an SSH box is not declarative either. A daemon on the host
detects CPU / GPU / kernel / distro at registration and advertises them
as capabilities and tags; match on those from a mode if you want to
target specific boxes in a pool.

## Example

**CLI tab:** `--field` values that start with `[`, `{`, or `"` are parsed as JSON;
`true` / `false` / `null` and anything number-shaped are converted;
everything else is a verbatim string. Dotted keys nest into objects, so
build lists with JSON rather than an index.

**.dreamrc tab:** The same shape in a local `.dreamrc`:

**CLI**

```bash
lakeshore secrets add my-dev-key --kind ssh_key --from-file ~/.ssh/id_ed25519

lakeshore providers add my-dev-box --launcher SSH \
  --kwarg ip=192.168.1.42 \
  --kwarg username=gyang \
  --kwarg pem=~/.ssh/id_ed25519

lakeshore modes add dev \
  --field provider=my-dev-box \
  --field runner=process \
  --field tags='["dev"]'
```

**.dreamrc**

```yaml file=".dreamrc"
providers:
  my-dev-box: !providers.SSH
    ip: 192.168.1.42
    username: gyang
    pem: ~/.ssh/id_ed25519

modes:
  dev:
    provider: my-dev-box
    runner: process
    tags: [dev]
```

## Smoke test

```bash
lakeshore providers test my-dev-box                      # built-in hello.py
lakeshore providers test my-dev-box --script ./mine.py   # your own
lakeshore providers instances my-dev-box                 # one row: running / unknown
```

`providers test` accepts `--timeout <seconds>` (default 600) and
`--dreamrc <path>`. `providers instances` pings the host with a fast
`ssh … echo ok` and reports `running` on success, `unknown` otherwise;
its `--timeout` defaults to 10 and is clamped to at most 5 seconds for
the ping itself.

If a test hangs, take Lakeshore out of the picture first:

```bash
ssh -i <pem> <user>@<ip> echo ok
```

## Enroll a host

Host enrollment and daemon bootstrap documentation now lives under Hosts:

- [Enroll a host](/lakeshore/hosts/enroll.md) — planned names, SSH transport, JSON configuration, and readiness.

## Importing from `~/.ssh/config`

You probably already have the hosts. `lakeshore ssh discover` reads
`~/.ssh/config` and shows which aliases exist locally and which are
already Providers; `lakeshore ssh upload` registers the ones you pick.

### `ssh discover`

```bash
lakeshore ssh discover                       # every entry
lakeshore ssh discover --filter new          # not yet on the server
lakeshore ssh discover --filter existing     # already a Provider
lakeshore ssh discover --show-stripped       # per-entry stripped-directive detail
```

Rows print `ALIAS`, `TARGET`, `KEY`, `TAGS`. Two tags appear in the
`TAGS` column:

| Tag | Meaning |
| --- | ------- |
| `#stripped` | The entry carries local-only directives that will be dropped on upload. |
| `#exists` | The alias is already a Provider on the control plane. |

A footer explains whichever tags actually appeared. Any bad `--filter`
value exits 2.

Entries that resolve to the same target collapse into one row. The
dedup fingerprint is a short hash of `(host, user, port, expanded key
path, ProxyJump, ProxyCommand)` — so two aliases differing only in
comment or `RemoteCommand` are one entry.

### `ssh upload`

```bash
lakeshore ssh upload my-dev-box                   # one alias
lakeshore ssh upload --all                        # every dedup-group head, non-interactive
lakeshore ssh upload                              # no alias → interactive multi-select
lakeshore ssh upload --interactive my-dev-box     # force the picker anyway
```

`--all` wins and never prompts (CI-friendly). Otherwise `--interactive`
or a missing alias opens a checkbox picker; **Space** toggles, **Enter**
confirms. Overrides for a single upload: `--name` (provider name,
defaults to the alias), `--user`, `--host`, `--port`, `--pem`, and
`--dispatch` (silently ignored unless it is exactly `direct` or
`daemon`).

`--with-key` reads the `IdentityFile` and uploads its bytes as an
`ssh_key` Secret named `ssh-<alias>` (override with
`--key-secret <name>`), then references it from the provider. The
default records the local path instead and leaves the key on disk —
uploading a private key crosses a real trust boundary, so it is opt-in.

### Stripped directives

These exist for the local user's interactive convenience and mean
nothing to a different machine dialing the same host, so they are
dropped before the kwargs reach the server:

```text
RemoteCommand, RequestTTY, ForwardAgent, ForwardX11, ForwardX11Trusted,
LocalCommand, PermitLocalCommand, SendEnv, SetEnv,
ControlMaster, ControlPath, ControlPersist, Compression,
Tunnel, TunnelDevice, StreamLocalBindUnlink, StreamLocalBindMask,
LogLevel, VisualHostKey, Include
```

It is a denylist: anything not on it survives — `ProxyJump`,
`ProxyCommand`, hostname / port / user / `IdentityFile`, and any other
option, which lands in the `ssh_options` bag. Over-sending beats silently
dropping something the server needed.

## Probing and status

```bash
lakeshore ssh probe my-dev-box --timeout 5   # or `--all` for every alias
lakeshore ssh status --history 3
```

`probe` attempts a connection and records the outcome in a local cache
(`~/.config/dreamlake/ssh-status.json` unless `DREAMLAKE_STATE_DIR` says
otherwise); `status` prints the last few results per alias.

---

Source: https://docs.dreamlake.ai/lakeshore/providers/slurm

# SLURM Provider

**`[ dev ]`** — you can register a SLURM provider and list its jobs, but the
`sbatch` submit path is still a stub, so nothing you launch reaches the cluster.
See [Providers](/lakeshore/providers.md) for what the marker means.

`--launcher SLURM` describes a Slurm cluster reached through its login
node. The provider row carries the login-node connection; the per-job
choices (partition, walltime, CPU/GPU counts) live on the mode.

> **Warning:** `lakeshore providers test <slurm-provider>` prints
> `providers.SLURM is not yet implemented in this build (sbatch path stub)`
> and exits 3. The control plane's `/providers/:name/launch` route supports
> only `EC2`, `GCE`, and `Kube`, so a SLURM provider gets a 422 there too.
>
> What *does* work today: registering the provider, and
> `lakeshore providers instances <name>`, which SSHes to the login node
> and reports your running jobs.

## Kwargs

The login-node connection reuses the SSH keys — `providers instances`
builds its `ssh` argv from the same fields the SSH launcher uses.

| Field | Type | Default | Meaning |
| ----- | ---- | ------- | ------- |
| `host` (or `ip`, or `login_node`) | string | — | **Required.** Login-node DNS or IP. |
| `user` (or `username`) | string | `ubuntu` | SSH user on the login node. |
| `port` | int | 22 | SSH port. |
| `pem` | string | — | Local path to the SSH key. |

Kwargs are an open bag, so account-scoped extras such as `account`,
`qos`, or `launch_dir` round-trip on the row for the submit path to
consume once it lands — they are not read by anything today.

## Mode fields

Per-job choices belong on the mode, not the provider. The daemon's Slurm
runner (the `slurm` runner inside `nymph`) reads these keys from
`run_config.slurm` when it renders an sbatch script:

| Key | Default | Maps to |
| --- | ------- | ------- |
| `partition` | — | `--partition` |
| `time` | `01:00:00` | `--time` |
| `gres` | — | `--gres` |
| `nodes` | — | `--nodes` |
| `ntasks-per-node` | — | `--ntasks-per-node` |
| `cpus-per-task` | — | `--cpus-per-task` |
| `mem` | — | `--mem` |
| `poll_interval_s` | 5 | How often the daemon polls `squeue` |

That runner submits `job.sbatch`, parses the job id out of
`Submitted batch job <n>`, polls `squeue -j <id> -h -o '%T'`, and runs
`scancel` on cancellation. It maps `CD` to success and `F` / `CA` / `TO`
to failure.

## Example

**.dreamrc tab:** The same shape in a local `.dreamrc`:

**CLI**

```bash
lakeshore providers add bos14 --launcher SLURM \
  --kwarg host=bos14.mit.edu \
  --kwarg user=gyang \
  --kwarg pem=~/.ssh/id_ed25519 \
  --kwarg account=lakeshore \
  --kwarg launch_dir=/home/gyang/lakeshore

lakeshore modes add bos14 \
  --field provider=bos14 \
  --field runner=slurm \
  --field slurm.partition=xeon-g6-volta \
  --field slurm.time='"04:00:00"' \
  --field slurm.cpus-per-task=8 \
  --field slurm.gres=gpu:1 \
  --field tags='["bos14","gpu"]'
```

**.dreamrc**

```yaml file=".dreamrc"
providers:
  bos14: !providers.SLURM
    host: bos14.mit.edu
    user: gyang
    account: lakeshore
    launch_dir: /home/gyang/lakeshore

modes:
  bos14:
    provider: bos14
    runner: slurm
    slurm:
      partition: xeon-g6-volta
      time: "04:00:00"
      cpus-per-task: 8
      gres: gpu:1
    tags: [bos14, gpu]
```

## Listing jobs

```bash
lakeshore providers instances bos14 --timeout 15
```

The CLI SSHes to the login node and tries `squeue --me --json` first,
falling back to `squeue --me --noheader -o "%i,%T,%P,%V,%j,%a"` when the
cluster's Slurm has no JSON support. Each job becomes one row: the id,
the partition in the type column, the submit time, and the account as a
tag. States map `RUNNING → running`, `PENDING → starting`,
`COMPLETING`/`STOPPING` → `stopping`, everything else `unknown`.

Without `host` / `ip` / `login_node` in the kwargs the command errors
out rather than returning an empty list.

## Credentials

SSH to the login node, exactly as for the
[SSH provider](/lakeshore/providers/ssh.md): `pem` is a local key path, and the
agent is the fallback when it is absent. Slurm itself trusts the SSH
session, so there is nothing further to configure.

## Running a daemon under an allocation

The alternative to per-call `sbatch` is a long-lived daemon inside one
allocation, pulling work for as long as the walltime lasts. Install it
with the SSH-alias path and the `--slurm` flag, which wraps the launch in
an `sbatch` heredoc instead of `setsid nohup`:

```bash
lakeshore daemon install bos14-login --slurm --slurm-partition xeon-g6-volta
```

The daemon long-polls the control plane for the life of the allocation
and disappears when it ends.

## Where the nymph sits — the one decision

`--slurm` is not the only placement, and it is not the default one. A nymph on
the **login node** is a *manager*: it does not run your code, it submits your
code to the scheduler and babysits the job.

| | Login node (no flag) | Inside a job (`--slurm`) |
| --- | --- | --- |
| Role | manager — submits work | worker — runs work locally |
| Lifetime | **unbounded** | dies at the sbatch wall-clock |
| Renewal | not needed | manual, on you |
| `hostFacts.backend` | `local` | `slurm` |

Prefer the login node. Under `--slurm` nothing renews the allocation — when the
wall-clock expires the daemon silently vanishes, and the CLI warns about
exactly this at install time.

Install it with the plain SSH-alias path and no flag. The nymph probes the
host, finds `sbatch`, and advertises `runners: ["process", "slurm"]` without
being told to:

```bash
lakeshore daemon install bos14-login      # no --slurm
```

A login node reports `backend: local` on purpose. It is tagged `host=slurm`
and carries the `slurm` runner because `sbatch` is on its PATH — but it is not
itself inside a job. Conflating "can submit" with "is running under SLURM"
would make every exit reason on that row read wrong.

## Match a launch to its worker and logs

The unique-launch installer assigns one ULID per `lakeshore daemon install`,
including installs without `--slurm`. It appends that ID to the worker label
and prints the log path. Under `--slurm`, the same ID appears in the job name:

| Surface | Name |
| --- | --- |
| Worker label | `<alias-or-label>-<launchId>` |
| Slurm job name | `lakeshore-nymph-<launchId>` |
| Log | `~/.local/share/nymph-<launchId>.log` |
| Binary, config, token | `~/.local/share/nymph/launches/<launchId>/` |

```bash
# On the cluster; replace this with the ID printed by the installer.
launch_id=01K4G8AX000000000000000001
squeue --name="lakeshore-nymph-$launch_id" -o '%.18i %.48j %.10T'
tail -f "$HOME/.local/share/nymph-$launch_id.log"

# On the machine with CLI auth:
lakeshore daemon list | grep "$launch_id"
```

Each launch keeps a private config and token, so two queued jobs cannot read
the last install's label when they eventually start. Nymph receives the
sectioned config with `--config`; the installer sets its working directory so
`server.token_file = "token"` resolves to that launch's token.

A fresh install starts another daemon. It does not stop an existing one.
Launch directories and logs remain for inspection after exit; remove them
only after the corresponding process or Slurm job has stopped.

> **Warning:** If your installer prints no launch ID, it still uses the shared
> `nymph.log` and fixed `lakeshore-nymph` job name. Upgrade to a release containing
> [the unique-launch fix](https://github.com/dreamlake-ai/lakeshore/pull/25)
> before running multiple installs against the same host.
> This fixes the SSH daemon installer; the provider submission stub described
> above is unchanged.

## Kill

```bash
lakeshore daemon kill <worker-id>

# For an inside-allocation daemon, cancel its specific job:
ssh bos14-login scancel <slurm-job-id>
```

SIGTERM is caught and reported: the worker row records
`exitReason: sigterm` and moves to `gone`. A `scancel` on an inside-a-job
nymph does the same thing, and `SIGKILL` leaves `exitReason` null — the
control plane infers `stale` after 60s of silence rather than inventing a
cause.

In-flight sbatch jobs are **not** cancelled when the manager stops. Cancel
those with `scancel` directly.

---

Source: https://docs.dreamlake.ai/lakeshore/providers/registration

# 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](https://cli.dreamlake.ai/installation/).

## 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:

**CLI**

```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**

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

**CLI**

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

**Python**

```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:

**CLI**

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

**Python**

```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:

**CLI**

```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**

```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](https://github.com/dreamlake-ai/dreamlake-workspace/blob/main/dreamlake-server/src/providers/README.md) for request shapes and limits.

---

Source: https://docs.dreamlake.ai/lakeshore/providers/resource-setup

# Resource setup examples

Enrollment adopts an existing machine. Terraform is optional infrastructure
preparation when you need to create resources first; it neither enrolls nymph nor
implements the planned host API. The examples below live in the CLI implementation
branch and must be adapted to your AWS account before any real infrastructure
plan or apply. No cloud resources were created by the documentation checks.

| Starting resource | Example or adoption path |
| --- | --- |
| Existing workstation or server | Verify SSH access, then follow [Enroll a host](/lakeshore/hosts/enroll.md); no Terraform required. |
| New AWS SSH machine | `examples/terraform/aws-ssh-host/` creates one EC2 host in an existing subnet using an existing EC2 key pair and restricted SSH source CIDRs. |
| Existing bos14 cluster | Adopt `fortyfive/bos14/bos14-ctrl` using your existing Unix/SSH access; configure its Slurm runner separately. Do not provision a replacement Slurm cluster. |
| New AWS Kubernetes cluster | `examples/terraform/aws-eks/` wraps the existing kube-provider Terraform template; review private endpoint access, node pools, and costs. |

## Prepare an AWS example

From the CLI repository checkout, copy the example variables and replace every
account-specific placeholder:

```shell
cd examples/terraform/aws-ssh-host
cp terraform.tfvars.example terraform.tfvars
terraform init -backend=false
terraform validate
terraform test
```

Use `examples/terraform/aws-eks` for the EKS example with the same preparation
steps. The test suites use mocked providers and do not prove AWS credentials,
quotas, permissions, routes, or actual provisioning. Only run a real Terraform
plan after choosing the region, existing network/key resources, access boundaries,
and intended capacity. Applying infrastructure is separate from these checks.

For an SSH host, `public_ip = false` requires private network or bastion access;
setting it true still requires a subnet with a suitable route. The example uses
an existing EC2 key-pair name; it does not upload your private key or store
credentials in the DreamLake vault. Choose the AMI's corresponding SSH user and
configure your local alias after provisioning, then use the enrollment guide.

For EKS, the API endpoint and workload nodes are separate from the host running
nymph. A submission host must already be able to reach and authenticate to the
cluster API. Provisioning EKS does not create a verified Kubernetes runner,
configure code/data staging, or establish a nymph connection. Existing EC2/k3s
infrastructure is a different setup and must not be treated as EKS.

## Related documentation

- **[Terraform example collection](https://github.com/dreamlake-ai/dreamlake-cli/tree/feat/218-host-enrollment/examples/terraform)** — Account-adaptable resource examples and their offline validation instructions.
- **[AWS SSH host example](https://github.com/dreamlake-ai/dreamlake-cli/tree/feat/218-host-enrollment/examples/terraform/aws-ssh-host)** — A single SSH-accessible EC2 resource with explicit network and key-pair inputs.
- **[AWS EKS example](https://github.com/dreamlake-ai/dreamlake-cli/tree/feat/218-host-enrollment/examples/terraform/aws-eks)** — Example values and tests using the existing kube template as the infrastructure source.
- **[Existing EC2 provider template](https://github.com/dreamlake-ai/dreamlake-cli/tree/feat/218-host-enrollment/src/cli/provider/templates/ec2)** — A separate SSM-managed head/worker cluster; its private head is not the single-SSH-host example.
- **[Enroll a host](/lakeshore/hosts/enroll.md)** — Host naming, bootstrap, consent, and readiness after infrastructure is available.
- **[Python API requirements](/dev/plans/hosts-python-api)** — SDK documentation and example-test requirements; resource provisioning remains a separate API scope.

---

Source: https://docs.dreamlake.ai/billing

# Billing and credits

  Subscriptions provide an allowance. Managed resource usage consumes credits at a separate,
  published rate.

> **Note:** Paid subscriptions, credit purchases, and account billing controls are not available yet. This
>   guide describes the proposed model; rates and terms may change before launch.

## Plans and usage are separate

Compare plans at [dreamlake.ai/pricing](https://dreamlake.ai/pricing):

- **Starter:** $0 platform fee, plus managed usage. Trial credit limits are pending.
- **Pro:** $20 per month, including $10 of usage (2,000 credits).
- **Team:** $250 per workspace per month, including $100 of usage (20,000 pooled credits). Additional usage consumes purchased credits at the published resource rates.
- **Enterprise:** individually agreed terms and allowances.

Seat limits, feature entitlements, and support commitments remain to be finalized.

One credit represents **$0.005 of retail usage**. Included and purchased credits consume resources at the same rates. Usage covered by credits is not charged a second time.

For the current proposed resource prices, use the [usage rate sheet](https://dreamlake.ai/pricing#usage). The [calculator](https://dreamlake.ai/pricing/calculator) separates total usage value from the additional credits needed after your subscription allowance.

## What counts as usage

The rate sheet covers DreamLake-managed storage, additional backup copies, internet egress, storage requests, CPU, memory, and AI inference or tools. Storage and bandwidth GB follow the AWS binary convention: 1 GB is 2³⁰ bytes. Storage is prorated over time.

Ingress bandwidth is free. Storage and requests associated with uploads still count. CPU and memory are separate resource charges. GPU bundle prices are included in the rate sheet and calculator as previews; availability is coming soon. Bundles include host CPU and RAM, so those resources should not be counted a second time.

AI inference and tools use **2× upstream provider-billed USD**, including input, output, cache, and tool charges where applicable. ChatGPT and Claude consumer subscriptions do not convert into credits.

Your own buckets, hardware, and provider API bills are not charged again as DreamLake-managed resources. Pricing for orchestration with your own API keys is still being determined.

## Credit lifecycle

The proposed model resets subscription credits monthly. Purchased top-up credits would roll over while subscribed. Credit pack sizes, expiry, and treatment after cancellation are not finalized.

Automatic top-up is planned to be **off by default**. Its controls will include a balance threshold, purchase amount, and monthly cap. These controls are not available yet; this guide does not enable automatic charges.

## Billing settings

Account billing is planned under `dreamlake.ai/:org/settings/billing`. The intended controls include plan management, usage, credit balance and purchases, automatic top-up, invoices, and payment details. These pages will be introduced as their backend workflows become available.

Public pricing remains on `dreamlake.ai`. Billing documentation lives here at `docs.dreamlake.ai/billing`.

## Taxes and invoices

Published prices are in USD and exclude applicable taxes. Tax handling and invoice workflows will be verified before paid checkout opens. Enterprise terms and purchasing requirements are agreed individually.

## Rollout

1. Publish pricing previews and the usage estimator.
2. Connect organization accounts, credit balances, and verified payment events.
3. Add metering as managed resources and Lakeshore features become available.
4. Verify sandbox purchases, usage, invoices, tax, refunds, and failure handling.
5. Enable paid production billing after those workflows pass acceptance checks.

## Reading the rate controls

The resource panel on the pricing page switches between hourly and per-second display for CPU, memory, and GPU bundles. This is a unit conversion, not a promise of a particular minimum billing duration; final metering granularity will be specified before launch. Storage, transfer, requests, and AI rates retain their own units.

“Bring your own compute” in the calculator excludes DreamLake-managed CPU, memory, and GPU costs. Managed storage, transfer, requests, and AI remain in the estimate because using your own compute does not automatically replace those services. Your own hardware and provider bills remain yours.

For example, the sample calculator workload has a $389.50 retail usage value. Team includes $100 of that usage, leaving $289.50 of additional usage value. The $250 workspace fee is separate; this example represents $539.50 in combined value before tax and final credit-pack terms.

---

Source: https://docs.dreamlake.ai/dev/declaration-collections

# Declarations vs. execution

> **Warning:** This page is the design of record as of **2026-08-06** — argued in
> `plans/2026-08-06_dreamlake-declaration-collections/README.md`, with the Prisma
> blocks verbatim in that directory's `schema.md`. The five models, the twelve
> permission keys, the host-key helper and the collection routes are now **in the
> `dreamlake-server` tree**, and the left-nav rows are wired.
>
> They are **not live on any shared server**. `prisma db push` is a deliberate,
> out-of-band, human step against a shared Atlas cluster, and this work did not run
> it — so the collections exist in source and not yet as documents. Read the shapes
> below as settled and the availability as pending. Parts that are further out still
> carry their own **Proposal** callout.

## The rule

**DreamLake owns declarations. The lakeshore controlplane owns execution.** A
declaration is a thing an author writes down once and then names — a provider, a
storage connection, a UDF, an agent, the environment a UDF runs inside, the git
tree it imports from. It is durable, editable, and it belongs to a namespace.
Execution is everything that happens because somebody submitted work — a queue,
an invocation, a worker, an event, a live channel. It is ephemeral, it is
high-churn, and it belongs to the controlplane that is actually running it. Every
placement question below resolves against that one sentence.

Ge, 2026-08-06:

> those configs live on dreamlake server. lakeshore cp is responsible for the
> runtime / ephemeral states and the queue.

| DreamLake (declarations) | Lakeshore controlplane (execution) |
|---|---|
| Tenancy — `Namespace`, users, orgs, teams | Queues — including fleet policy and elasticity |
| Credentials — the AES-256-GCM secret blobs | Invocations — one row per submitted run |
| `LakeshoreProvider` — launcher credentials + placement | Workers / daemons — the live fleet |
| `Source` — data and storage connectors | Events — the run log |
| `Repo` / `RepoSnapshot` — registered git trees | Sessions and live channels |
| `Runnable` / `RunnableVersion` — UDFs, sessions, agents | `Invocation.runConfigRef` + `Invocation.resolvedConfig` |
| `RunConfig` — the named environment template | |

The last row is the one worth staring at. `RunConfig` is the **template**: a
named, reusable, namespace-scoped record that a human edits. The **instance** —
the merged snapshot of what a particular run actually got — is
`Invocation.resolvedConfig`, and an invocation is execution, so it stays on the
controlplane. Splitting the two is what keeps `RunConfig` from naming two
different things.

Fleet policy stays with the queue for the same reason it always has: a guardrail
that lives inside a generated artifact is not a guardrail. The permitted instance
types, the elasticity bounds and `providerRef` are the controlplane's to enforce.

---

## The four collections

Ge named the set as **provider / storage / UDF / agents**. They cohere as a set,
but not because they share a landing page — there is deliberately no
`/:ns/declarations` index. They cohere in two concrete ways.

**One URL grammar and one authorization root.** Every collection sits at
`/namespaces/:slug/<collection>` and behaves identically: the same response
envelope, the same `{ items, page, pageSize, total, totalPages }` list shape, the
same id-or-name resolution (24-hex reads as an id, anything else as a name), the
same soft delete via `deletedAt`, the same 409 on a duplicate name, and the same
`authorize(userId, '<x>:<verb>', { kind: 'lakeshore', namespaceId }, prisma)`
call. Reusing `ctx.kind: 'lakeshore'` is a choice, not an accident — `AuthContext`
is a closed union, and a new arm would need a role mapper byte-identical to
`resolveLakeshoreRole`. The consequence is that these collections inherit exactly
the ADMIN/READ derivation that lakeshore connections already have.

**One left-nav group.** The `lakeshore` section of `DreamLakeLeftPanel` is the
index. It already ships dead rows for "UDFs" and "Providers" with no `onClick`;
wiring them is one line each.

| Collection | Route | Model | Status |
|---|---|---|---|
| Providers | `/namespaces/:slug/lakeshore-providers` | `LakeshoreProvider` | routes exist, no UI |
| Storage | `/namespaces/:slug/lakeshore-storages` | `LakeshoreStorage` | routes exist, collapsing into `Source` |
| Sources | `/namespaces/:slug/sources` | `Source` | ships today, UI at `/source/:ns` |
| Runnables | `/namespaces/:slug/runnables` | `Runnable` + `RunnableVersion` | **new** |
| RunConfigs | `/namespaces/:slug/runconfigs` | `RunConfig` | **new** |
| Repos | `/namespaces/:slug/repos` | `Repo` + `RepoSnapshot` | **new** |

Two sub-resources hang off the two-layer collections:
`/namespaces/:slug/runnables/:idOrName/versions` and
`/namespaces/:slug/repos/:idOrName/snapshots`. Both are list / get / register.
Registration is idempotent by content: re-registering an existing
`(runnableId, version)` or `(repoId, commit)` returns **200 with the existing
row** and rewrites nothing, because there the key *is* the content.

The left-nav rows the set produces:

| Row | Route |
|---|---|
| Overview | `/:ns/lakeshore` |
| Sources | `/source/:ns` |
| Providers | `/:ns/providers` |
| RunConfigs | `/:ns/runconfigs` |
| UDFs & Agents | `/:ns/runnables` |
| Repos | `/:ns/repos` |

---

## `Runnable` — one model, three lifetimes

`Runnable` is a single model with a free-string `kind ∈ udf | session | agent`.
The `kind` distinguishes **lifetime, not substance** — all three are named code
you invoke. The ladder, plainly:

- **`udf`** — one-shot. You submit, you get a result back, it is over.
- **`session`** — long-lived, with a bidirectional pipe attached.
- **`agent`** — a session, plus a policy driving it.

Each rung adds to the one below it; nothing is taken away. `kind` is a plain
`String` rather than a Prisma enum, matching `Source.kind` and
`LakeshoreProvider.kind`, so a fourth lifetime never needs a schema change.

### An Agent is a UDF plus exactly two fields

Ge, 2026-08-06:

> For the agents, start the definition with stuff from the UDF, plus a channel
> and a markdown. channel does not need to be configed at real time I think but
> we can include it.

Checked field by field against the controlplane's `Function`, that holds up.
An agent is decorated code, so it has a `module` and a `qualname`; it has a
source and therefore a `version`; its `signature` is the entrypoint's parameters,
which is degenerate but not meaningless. Nothing on the UDF side is empty for an
agent. Only the reverse holds, and only twice — `markdown` and `channel`. A
definition stated as "X plus two fields" is a discriminator, not a second shape,
so there is no `Agent` model.

`markdown` is read as **behaviour** — the agent's instructions, authored as
Markdown and rendered on the detail page. It is not a description card;
`description String?` already covers documentation.

Both fields live on the mutable `Runnable` head, not on `RunnableVersion`,
because `RunnableVersion.version` is `sha256(source)` and must stay
byte-identical to the controlplane's `Function.version`. Folding prose into that
hash forks the identity for nothing. **The accepted cost is that an agent's prose
has no version history**, so "which prompt was this invocation run with" is
currently unanswerable. That is the design's largest known compromise, and it is
recorded rather than hidden.

`channel` is a small typed object in a `Json?` column, documented shape
`{ kind, target?, config? }` — a stored declaration of where the agent's pipe
attaches, never a live connection:

```json file="Runnable.channel"
{
  "kind": "slack",
  "target": "#eng-alerts",
  "config": { "sourceRef": "slack-eng" }
}
```

`kind` is a free string (`stdio`, `http-sse`, `websocket`, `slack`, …), following
the same discriminator-plus-open-blob shape `Source.config` and
`LakeshoreProvider.config` already use. A bare string like `"slack:#eng"` was
rejected: it forces a parser and has nowhere to put an SSE path, a Slack channel
id, or a reference to the credential that opens the pipe.

> **Warning:** `channel.config` may hold a **reference** to a credential and never the
> credential itself. A Slack token belongs on a `Source` or a `LakeshoreProvider`,
> both of which already carry the AES-256-GCM blob and the never-return-ciphertext
> machinery. Point at one by name — `{ "sourceRef": "slack-eng" }` — and let the
> server resolve it. The route enforces this: any key under `channel.config`
> matching `/token|secret|password|api_?key/i` is a **400**, with the response
> naming the model the field should have gone to instead.

### The split tripwire

Written down so nobody re-argues it. Split `Agent` into its own model — with a
foreign key back to a shared `Runnable`, never by duplication — the first time
any one of these holds:

1. **Agent-only fields exceed three, or any agent-only field becomes required.**
   A column that is required for one `kind` and forbidden for another is a lie
   the schema cannot express.
2. **`markdown` or `channel` must be version-addressed** — i.e. the answer to
   "which prompt ran" becomes load-bearing. This is the likeliest trigger, and it
   is exactly the cost accepted above.
3. **Agents acquire a relation UDFs must not have** — the moment
   `Runnable.sessions` would be meaningless for `kind="udf"`.

Until one of those fires: one model, one `kind`.

---

## Two-layer identity

Two of the three new collections split into a mutable head plus an immutable,
content-addressed child. The third does not.

| Model | Key | Mutability |
|---|---|---|
| `Runnable` | `@@unique([namespaceId, name, deletedAt])`, `name = "<module>.<qualname>"` | mutable head |
| `RunnableVersion` | `@@unique([runnableId, version])`, `version = sha256(source)` | immutable, append-only |
| `Repo` | `@@unique([namespaceId, name, deletedAt])` | mutable head |
| `RepoSnapshot` | `@@unique([repoId, commit])` | immutable, append-only |
| `RunConfig` | `@@unique([namespaceId, name, deletedAt])` | **mutable, no versions** |

**Why `Runnable` and `Repo` split.** The controlplane's `Function` is flat, keyed
`(namespaceId, module, qualname, version)`, so it accumulates one row per source
edit with no head — and "list my UDFs" degrades into a `distinct` plus a
`max(createdAt)` group-by. The two-layer form hands the UI a name list and a
history for free, and it is the house's own answer twice over
(`Pipeline`/`PipelineVersion`, `Workflow`/`WorkflowVersion`).

**Why `RunConfig` does not.** It is a hand-edited operator declaration, and every
reference to it is by *name* on purpose. Content-addressing it would mean editing
`gpu-a100` mints `gpu-a100@v2` and every reference has to be repointed. Where
content-addressing is genuinely needed — placement — the derived `hostKey`
supplies it without freezing the record.

**Why `deletedAt` is in the unique key.** All three heads use the
Pipeline/Workflow form `@@unique([namespaceId, name, deletedAt])`, not the
`Source` form `@@unique([namespaceId, name])`. The latter covers tombstones, so
deleting a provider named `ec2` burns that name forever. These rows target the
production server; delete-and-recreate has to work.

Append-only rows carry `createdAt` and deliberately have **no** `updatedAt` and
**no** `deletedAt`. Versions and snapshots are never deleted by any endpoint;
they become invisible when their parent head is soft-deleted.

---

## `RunConfig` serves two audiences

A `RunConfig` is read by two consumers that do not talk to each other, so it
stores them in two columns rather than one bag:

- **`runtime`** — read by the runtime layer: `backend`, `server`, `runner`,
  `image`, `resources`, `env`, `timeout_s`, `host_setup`, `run_setup`.
- **`extras`** — forwarded verbatim to the launcher: `instance_type`,
  `partition`, `time_limit`, `n_cpu`, `n_gpu`, and whatever the next launcher
  wants.

Alongside them sit two typed columns. `tags String[]` is typed and separate
because it is the one field forwarded to **both** halves — it cannot honestly
live in either bag. `provider String?` is a **name, not a foreign key**: the
controlplane resolves providers by name, late, and an FK across a service
boundary breaks the moment the CP resolves against its own copy.

One `config` bag was rejected, and not on taste. That form has already failed
three times, always the same way — by making code *reconstruct* a partition that
was never stored. `_RUNTIME_FIELDS` in `lakeshore-py` is a hand-maintained list
of the runtime half with zero readers, while the real partition happens twice
more in two lists that disagree with it. The controlplane's `TYPED_KEYS` omits
`server`, so a runtime field round-trips through `resources.__extras` and works
by accident. And the two sides default `backend` and `runner` differently, so a
partial config changes meaning when stored and re-read. Two columns make the
boundary a schema fact, so there is nothing to reconstruct and nothing to drift.

A GPU config with a non-trivial host setup, which is the acceptance shape:

```json file="RunConfig — gpu-a10g"
{
  "runtime": {
    "backend": "fabric",
    "runner": "docker",
    "image": "nvcr.io/nvidia/pytorch:24.10-py3",
    "resources": { "gpu": 1, "cpu": 8, "memory": "32Gi" },
    "env": { "HF_HOME": "/mnt/cache/hf", "TORCH_CUDA_ARCH_LIST": "8.6" },
    "timeout_s": 3600,
    "host_setup": [
      "sudo nvidia-ctk runtime configure --runtime=docker",
      "sudo systemctl restart docker",
      "docker pull nvcr.io/nvidia/pytorch:24.10-py3"
    ],
    "run_setup": ["pip install -e ."]
  },
  "extras": { "instance_type": "g5.2xlarge", "n_gpu": 1, "n_cpu": 8 },
  "tags": ["gpu", "a10g"],
  "provider": "ec2-us-east-1"
}
```

The GPU appears in **both** halves, and it means two different things.
`runtime.resources.gpu` is what the **runner** asks of the host it lands on — a
requirement, checked against a machine that already exists. `extras.n_gpu` and
`extras.instance_type` are what the **launcher provisions** — an order, placed
before any host exists. They are usually consistent and they are not the same
statement, and a single bag cannot keep them apart.

One more gap, recorded rather than solved: `image` is a single string, so a
multi-container host setup is not expressible. Nothing in the acceptance shape
needs it.

> **Warning:** Both keys are **introduced by the host-key design**. The controlplane's `Mode`
> route has no such fields: its `TYPED_KEYS` set is exactly
> `{backend, runner, image, tags, resources, env, timeout_s, provider}`, and
> anything outside it is swept into `resources.__extras`. So a `host_setup` sent to
> `POST /v1/namespaces/:ns/modes` today does not round-trip as a runtime field — it
> survives, buried, in the launcher-extras bucket. (`server` has the same problem
> and it *is* a runtime field, which is the bug that made the two-column split
> worth doing.)
>
> `RunConfig.runtime` on dreamlake-server carries both keys as first-class runtime
> fields, and the Python SDK already emits them on the wire. Making the CP's `Mode`
> agree — or deleting `Mode` in favour of `RunConfig`, which is the staged plan — is
> a separate slice.

---

## The derived host key

There is **one** declaration, written by the author: the `RunConfig`. The host
requirement is **derived** from it — a hash over the placement-affecting subset —
and never written down beside it. That is the whole point: a second, hand-written
host field is a second source of truth that can disagree with the first.

The algorithm is not restated here. It is normative in the
[Host Setup design page](/lakeshore/host-setup.md), which owns the key's definition,
its canonicalisation rules and its golden vectors.

Where it is computed, and who is allowed to be right:

| Side | When | Authority |
|---|---|---|
| Python SDK | at submit, `RunConfig.host_key()` | **authoritative** — stamps `run_config["host_key"]` |
| nymph | at boot and after a setup refresh | advertises it on hello / poll |
| TypeScript CLI | on `lakeshore config show` | display only |
| lakeshore controlplane | on every daemon poll / claim | computes nothing; **matches** two strings (see below) |
| dreamlake-server | on every `RunConfig` write | **display only, non-authoritative** |

dreamlake-server keeps a fourth copy in `RunConfig.hostKey`, recomputed on every
write from `{ runner, image, resources, host_setup }` out of `runtime`, plus the
`provider` column and the whole `extras` column. It is null when it cannot be
computed — a float in `resources`, for instance, is a hard error rather than a
coercion.

**It does not travel, and nothing matches on it.** No scheduler, no worker and no
queue ever reads dreamlake's copy. It exists for exactly two reasons: the
dashboard can show which RunConfigs share a host, and a divergence between the
SDK's stamp and the stored value becomes a diffable string instead of a silent
mismatch. It exists at all only because a `RunConfig` is now authored in the UI
and the SDK never writes a `RunConfig` row — without a server-side computation
the column would be permanently null for precisely the rows this work exists to
show. The mitigation is mandatory: the golden vector fixture is copied
**verbatim** into the server and every vector is asserted, so an edited copy
fails immediately.

> **Warning:** Read the authority table above as a moving target. As of this writing the
> controlplane **does** consume the host key: `claimOne` composes a `hostKeyFilter`
> clause onto its `findAndModify` query, so a worker may only claim an invocation
> whose declaration hashes to the same `hk1_…`. That landed with the nymph
> lifecycle work and is not yet exercised end to end by a rolled-forward fleet.
>
> The compatibility rule is the part worth knowing, because it is what stops a
> half-upgraded fleet from deadlocking: **an absent key on either end degrades to
> exactly the previous matching.** A worker that advertises no host key gets no
> clause at all; an invocation with no `runConfig.host_key` is claimable by any
> worker. Only when both sides carry a key does the key narrow anything. That is
> why the SDK **omits** the field rather than nulling it.
>
> None of this changes dreamlake-server's position. Its `RunConfig.hostKey` is
> still the fourth copy, still display-only, and still matches nothing — the string
> the controlplane compares came from the SDK's stamp on the invocation, never from
> this column.

---

## What is not here

Everything on the execution side of the rule. None of it moves, and none of it
gains a mirror on dreamlake-server. The dashboard still shows all of it — by
**reading the controlplane through the proxy**, with no model in between. That is
[Execution views](/dev/execution-views.md).

- **Queues are not here.** Including `daemonTemplate`, elasticity policy and the
  permitted instance types. Ge reaffirmed it on the same day the rest of this was
  settled, and a queue is the clearest case the rule has: it is a piece of
  running machinery with a depth that changes by the second.
- **Invocations** — `runConfigRef` (a name) and `resolvedConfig` (the merged
  per-run snapshot) both stay on the controlplane.
- **Workers and daemons** — the live fleet, its capabilities and its heartbeats.
- **Events** — the run log.
- **Sessions and live channels** — a `Runnable` declares where a channel
  attaches; opening one is execution. There is no session model, no socket and no
  reconfiguration endpoint in this slice.

> **Warning:** `LakeshoreQueueDef` still exists on dreamlake-server and is **not** deleted by
> this work. It is **deprecated and frozen**: its routes and GraphQL fields keep
> serving existing callers, no field changes, and **no new UI offers it**. Dropping
> a model orphans documents in a shared Mongo database and there is no migration to
> undo that. Full removal — the model, four permission keys, the `CollectionSpec`
> entry, the GraphQL type and its two Query fields, the test-teardown line, and
> re-pointing two tests that use queue-defs as their sole coverage vehicle — is
> staged for Ge's approval, not executed.

> **Warning:** `LakeshoreStorage` is a third copy of what `Source` already is: a connector with
> non-secret `config` and an AES-256-GCM secret blob. The plan is to collapse it
> into `Source`, carrying over the immutable-target constraint
> `@@unique([namespaceId, bucket, prefix, endpoint])` — for which this schema has
> **no precedent**, since every existing namespace-scoped unique key is over
> `name`. It needs a data migration against the live database, so it is argued and
> staged, not executed. This is why no Storage page is built: `Source` already has
> a full UI at `/source/:ns`, and building a page with a known expiry date is the
> definition of throwaway work.

---

## Where to read further

- [Execution views](/dev/execution-views.md) — the other half of the line: runs,
  elastic queues and cluster topology, all read through the proxy, none of them a
  collection.
- `plans/2026-08-06_dreamlake-declaration-collections/README.md` — the full
  argument, including every rejected alternative.
- `plans/2026-08-06_dreamlake-declaration-collections/schema.md` — the five
  Prisma models verbatim, with their comment blocks.
- `DECISIONS.md`, 2026-08-06 — the two decision entries this page implements.
- [Host Setup](/lakeshore/host-setup.md) — the host-key derivation and why the
  requirement is derived rather than declared.

---

Source: https://docs.dreamlake.ai/dev/execution-views

# Execution views

The companion to [Declarations vs. execution](/dev/declaration-collections.md). That
page covers the half DreamLake **owns**. This one covers the half DreamLake only
**looks at**: the runs that are in flight, the queues that are scaling, and the
machines they are scaling onto.

## The rule, first

**Topology, elastic queues and invocations add no Prisma model and no
dreamlake-server collection.** Not one. Queues, invocations, elasticity events,
workers and everything topology is drawn from are execution, and execution stays
on the controlplane — Ge, 2026-08-06:

> those configs live on dreamlake server. lakeshore cp is responsible for the
> runtime / ephemeral states and the queue.

All three views are DreamLake-side **read surfaces** over a proxy that already
ships. There is nothing to sync, nothing to invalidate, and no second copy that
can be stale, because there is no copy at all.

---

## Everything goes through one proxy

```
GET /namespaces/:slug/lakeshores/:id/proxy/<controlplane-path>[?query]
```

The wildcard is forwarded **verbatim** to `${baseUrl}/<controlplane-path>` with
the Lakeshore's decrypted bearer token injected. Four properties of that route
are load-bearing for anything built on top of it.

**It is deliberately dumb, and single-target.** The proxy does not know what a
queue is. The *client* builds the controlplane path itself — including the
`lakeshoreNs` segment, which it reads off the `Lakeshore` record — and the proxy
resolves `baseUrl` from that same record and nothing else. That is what keeps it
from being pointed at any host but this Lakeshore's controlplane. The cost is
that the browser has to know the controlplane's URL grammar; the benefit is that
a new controlplane endpoint needs zero dreamlake-server work.

**GET is `lakeshore:read`; every mutating method is `lakeshore:use`, which is
ADMIN-only.** All three views are read-only, so an org member with READ sees all
three. Anything that would need `lakeshore:use` — killing an invocation, forcing
a scale action, draining a worker — is out of scope here precisely because it
changes the permission story.

**Only `content-type` and `cache-control` come back.** The proxy mirrors the
upstream status and exactly those two headers, then streams the body. Everything
else is dropped.

> **Warning:** Because the proxy forwards only `content-type` and `cache-control`, a `Link:
> rel="next"` header from the controlplane is **silently discarded** — the client
> sees a 200 with a complete body and no hint that more exists. Any paginated
> controlplane endpoint these views consume must carry its cursor **in the response
> body or in the query string**, never in a header. The existing feeds do this
> correctly (`?limit&before` on events, `?limit&offset` on invocations); the
> constraint is written down here so the next endpoint does not learn it the hard
> way.

**An unreachable controlplane is a 502.** The `fetch` is wrapped, and a transport
failure returns `502 { error: "controlplane unreachable", message }` — not a 503,
not a 504, not a hung request. Views distinguish three states from that: a 502 is
"the Lakeshore is down", a 4xx passed through is "the controlplane answered and
said no", and a network error before the proxy is "dreamlake-server is down".

### Resolving *which* Lakeshore

Every proxy URL needs a `lakeshoreId`, which comes from
`GET /namespaces/:slug/lakeshores` on dreamlake-server. The views pick the first
**connected** record — the literal reading of the requirement, *"in a single
connected lakeshore."*

Zero connected lakeshores is a first-class state, not an error state: each of the
three pages renders a "connect a lakeshore" prompt linking to `/:ns/lakeshore`.
Never a spinner that never resolves, and never a red error card — an unconfigured
namespace has not failed at anything.

---

## Topology — one spine, four levels

The requirement is *across providers, in a single connected lakeshore*. That
rules out two provider-shaped panels side by side, and it rules out mirroring
Kubernetes objects.

```
Lakeshore                the one connected controlplane
  └── Provider           Worker.providerName, else "byo"
        └── Pool         derived — see below
              └── Worker machineId · state · hostStatus · runners · queues · gpus
```

The whole design is the third level. **An EC2 auto-scaling group and a Karpenter
NodePool are the same object at this altitude**: a named group of interchangeable
machines that a provider grows and shrinks. Once you say that out loud, both live
clusters fall out of one spine with no special case:

| Cluster | Provider | Pools | Workers |
|---|---|---|---|
| `aws-workspace-ge` (EC2 + ASG) | one `aws-ec2` provider | ASG pools `cpu`, `gpu` | one nymph per EC2 instance |
| `dreamlake-k8s` (EKS + Karpenter) | one `k8s` provider | NodePools `cpu`, `gpu` | one nymph per pod |

> **Note:** No pods, no nodeclaims, no ASG scaling activities, no container statuses. **k9s
> already exists** and is better at every one of those than a dashboard panel will
> be. The view answers "how many GPU nodes are up, on which provider, in what
> state" — a fleet question — and stops there. Rendering is an indented grouped
> list, not a graph: a fleet is a containment tree, not a dataflow DAG, and a force
> layout makes the count harder to read, not easier.

### Pool-key derivation

Computed client-side from the `GET v1/namespaces/:ns/workers` response.
**First hit wins:**

1. `worker.capabilities.pool`, when the daemon reports it.
2. A tag matching `/^pool[:=](.+)$/i` — else a bare tag in `{cpu, gpu}`.
3. `worker.capabilities.gpu` present and non-zero → `"gpu"`, otherwise `"cpu"`.
4. `"default"`.

Rule 3 is why the view works **today**, before any daemon cooperation: a
`g5.2xlarge` reports GPUs and a spot CPU node does not, so the two pools separate
correctly on both live clusters with no change to the nymph. Rule 1 is what makes
it authoritative later; when a daemon starts reporting `capabilities.pool`,
nothing in this view changes except that a marker stops appearing.

**Pools derived by rule 3 render with a visible `inferred` badge.** That badge is
not decoration. Rules 1 and 2 report something an operator declared; rule 3 is the
dashboard guessing from a GPU count. A guess and a fact must not look identical,
because the moment they do, "the topology says these are two pools" stops being
evidence of anything.

`Provider` comes from `Worker.providerName`, which the controlplane stamps on
workers it launched; SSH-installed workers have none and group under `byo`.
`GET v1/admin/providers` is **best-effort enrichment only** — it wants an
admin-capable token, so a 401 or 403 there must degrade to provider names without
kind/region metadata. It must never produce an error page: losing the region
label is not losing the topology.

---

## Queues — the events feed is primary

Two controlplane endpoints, both already shipped, both with zero UI consumers
before this work:

| Endpoint | Returns |
|---|---|
| `GET v1/namespaces/:ns/queues/:name/events?limit&before&verbose` | the `ElasticityEvent` feed |
| `GET v1/namespaces/:ns/queues/:name/stats` | `{ queueName, daemon_count, utilization, pending_invocations, recent_scale_actions[] }` |

**The feed is the primary panel and the stats strip is secondary**, which is the
inverse of how a stats endpoint usually gets treated. The reason is one row type:
the controller logs `tick_noop` with a `reason` every time it decides *not* to
act, which makes the feed the only thing in the entire stack that answers **"why
didn't my cluster scale up"** — precisely the question a live demo produces.

`/stats` deliberately filters those out (`action: { not: "tick_noop" }`), so
`recent_scale_actions` is the **highlight reel** and the feed is the
**transcript**. Both are useful; only one of them explains a non-event. Default
the feed to `verbose=false` with a toggle, because noops are the point and they
are also roughly 95% of the rows.

Queue *policy* — elasticity kind, min/max/threshold, `admission.max_depth`,
`providerRef` — comes from `GET v1/namespaces/:ns/queues` and renders beside the
live signals. "max: 4" is the answer to a good half of the "why didn't it scale"
questions, and it is useless on a different screen from the depth it is capping.

`daemon_count` and `pending_invocations` are computed server-side from real rows.
They are trustworthy today; render them plainly.

### Utilization, and why it renders as a dash

> **Warning:** `utilization` is `sumCurrent / sumMax`, where `sumCurrent` sums
> `capabilities.current_invocations ?? 0` across the queue's workers. The `?? 0`
> is the problem: **a daemon that has never heard of the key contributes exactly
> what a fully idle daemon contributes.** `/stats` therefore exposes no way to tell
> "0% busy" from "nobody reported", and a dial pinned at 0% while a GPU node is
> melting is a confident lie.
>
> The dashboard must not guess from the number. It checks the source: the topology
> view already fetches `GET v1/namespaces/:ns/workers`, so the queue panel reuses
> that response and asks whether **any** worker in this queue carries a
> `capabilities.current_invocations` key at all.
>
> - some worker reports it → render the percentage
> - `daemon_count > 0` and none reports it → render **`—`**, footnoted
>   *"utilization not reported by these daemons"*
> - `daemon_count === 0` → render **`no daemons`**, which is a real answer and not
>   a missing one
>
> A concurrent workstream is landing the daemon-side field (the nymph now stamps
> `current_invocations` from its in-flight counter on every poll). The dash is the
> correct rendering until every daemon in a fleet has been rolled forward — and it
> stays correct afterwards, because a mixed-version fleet is the normal state of a
> fleet.

---

## Runs — invocations, and the join between the halves

`GET v1/namespaces/:ns/invocations?limit&offset&state&queue` and
`GET …/invocations/:id`.

List columns: id, function, state, queue, worker, submitted, duration. **The
`state` and `queue` filters are server-side query parameters, not client-side
array filters** — the list is unbounded, and filtering a page of 50 client-side
gives an answer about the page rather than about the namespace.

The detail page shows what a run *was*: the function ref, `runConfigRef`, the
`resolvedConfig` snapshot, the queue, the worker, and the repo commit from the
envelope's code stamp.

**That page is the join between the two halves of the system.** An invocation
names a `RunConfig` by name and a `Runnable` by module/qualname, and the detail
view links both back into the declaration collections — `/:ns/runconfigs/<name>`
and `/:ns/runnables/<name>` — **by name, not by id**. This is exactly what the
collections API's id-or-name resolution exists for: a 24-hex segment reads as an
id, anything else as a name. Without it, the link would need a lookup table
across a service boundary, which is the thing the whole declaration/execution
split exists to avoid.

Note what this does *not* claim: `runConfigRef` is a name that was resolved on the
controlplane at submit time, so the `RunConfig` it points at may since have been
edited. `resolvedConfig` is the snapshot of what actually ran and is authoritative
for the run; the link is navigation, not provenance.

### Out of scope, stated plainly

- **The log SSE stream.** `streamUrl` and a working SSE reader already exist in
  the locked `lib/lakeshore/`; the proxy streams SSE correctly. Wiring it into
  these pages is a separate slice.

> **Warning:** `parentInvocationId` and `rootInvocationId` exist on the controlplane's
> `Invocation` model, and the submit handler now walks the parent to stamp a root.
> **No lineage view is built here**, and the fields are not rendered on the run
> detail page. A tree view needs a fan-out read the list endpoint does not offer,
> and it needs every SDK path to populate the parent link before the tree means
> anything — today only the Python `HttpDispatch` sends `parent_invocation_id`, and
> only when a caller passes one. Treat lineage as designed and partially wired, not
> as available.

---

## The three routes

| Route | Reads (all via `/proxy/*`) | Poll |
|---|---|---|
| `/:ns/runs` | `v1/namespaces/:ns/invocations`, `…/invocations/:id` | **6 s** |
| `/:ns/queues` | `v1/namespaces/:ns/queues`, `…/:name/stats`, `…/:name/events` | **8 s** |
| `/:ns/topology` | `v1/namespaces/:ns/workers`, `v1/admin/providers` | **10 s** |

**Every poll pauses while the tab is hidden.** Each tick is a proxied round-trip
from the browser through dreamlake-server to the controlplane, and the existing
overview panel already mounts five pollers at 4–6 s. Three more unconditional
fast pollers would multiply proxy load for a dashboard nobody is looking at.
Pause on `document.hidden`, resume on visibility, and refetch once immediately on
resume so the first frame after a tab switch is not stale.

---

## Where to read further

- [Declarations vs. execution](/dev/declaration-collections.md) — the other half of
  the line, and the collections these views link into.
- `plans/2026-08-06_dreamlake-declaration-collections/README.md` — the full
  argument, including every rejected alternative.
- `DECISIONS.md`, 2026-08-06 — the decision this page implements.

---

Source: https://docs.dreamlake.ai/dev/notes/vault-shared-scopes

# Shared Vault scopes

## 2026-09-27 — Unreleased

Added explicit organization and team saving to the Vault dashboard and entry API. Shared tenants use immutable organization/team IDs, with membership checked on each request. Team membership and organization membership are both required for team secrets, including visible teams. Personal storage and access-key behavior remain unchanged.

Shared-scope operations are restricted to entry storage and write recovery. Personal-only delivery, key issuance, OTP generation and KMS administration are rejected for shared tenants until their authority contracts support shared ownership.

Validation covers cross-scope isolation at identical paths, unauthorized saves, removed memberships, deleted organizations, malformed scopes, personal compatibility, and browser transport scope selection.

Skill impact: no existing CLI/SDK procedure changes; their default remains personal. The new dashboard and HTTP contract is documented in the shared-scopes guide. No generated CLI/Notes skill source is changed.

---

Source: https://docs.dreamlake.ai/ml-dash/guides/experiments

# Experiments

Experiments are the foundation of ML-Dash. Each experiment represents a single experiment run, containing all your logs, parameters, metrics, and files.

## Prefix Format

The prefix is a universal key that identifies your experiment:

```
{owner}/{project}/path.../[name]
```

- **owner**: First segment (e.g., your username)
- **project**: Second segment (e.g., project name)
- **path**: Remaining segments form the folder structure
- **name**: Derived from the last segment

## Three Usage Styles

**Context Manager** (recommended for most cases):

```python

from ml_dash import Experiment

# Prefix format: owner/project/experiment-name
with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.log("Training started")
    exp.params.set(learning_rate=0.001)
    # Experiment automatically closed on exit
```

**Decorator** (clean for training functions):

```python

from ml_dash import ml_dash_experiment

@ml_dash_experiment(prefix="alice/project/my-experiment")
def train_model(experiment):
    experiment.log("Training started")
    experiment.params.set(learning_rate=0.001)

    for epoch in range(10):
        loss = train_epoch()
        experiment.metrics("train").log(loss=loss, epoch=epoch)

    return "Training complete!"

result = train_model()
```

**Direct** (manual control):

```python

from ml_dash import Experiment

exp = Experiment(prefix="alice/project/my-experiment")
exp.run.start()

try:
    exp.log("Training started")
    exp.params.set(learning_rate=0.001)
finally:
    exp.run.complete()
```

## Automatic Path Detection with RUN.entry

Use `RUN.entry = __file__` to automatically detect the script path and generate a meaningful experiment prefix:

```python

from ml_dash.run import RUN
from ml_dash.auto_start import dxp

# Set entry point to current file - enables automatic path detection
RUN.entry = __file__

# Now dxp will use the script's path to generate the prefix
# e.g., if running /home/user/project/experiments/train.py
# prefix becomes: user/project/experiments/train
with dxp.run:
    dxp.log("Training with automatic prefix")
    dxp.params.set(learning_rate=0.001)
```

This is useful when:
- Running multiple scripts in the same project
- You want the prefix to automatically reflect the file structure
- Organizing experiments by script location

## Local, Hybrid, and Remote Mode

Where an experiment writes depends on `dash_url` and `dash_root`:

| Mode | How to get it | Writes to |
|---|---|---|
| **Local** (default) | no `dash_url` | `.dash/` on disk. No server, no login |
| **Hybrid** | `dash_url=...` | the server **and** `.dash/` |
| **Remote** | `dash_url=...`, `dash_root=None` | the server only |

```python

# Local: zero setup, filesystem storage
with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.log("Using local storage")

# Hybrid: the server, plus a local copy
with Experiment(
    prefix="alice/project/my-experiment",
    dash_url="https://api.dash.ml"
).run as exp:
    exp.log("Using the server and .dash/")

# Remote only
with Experiment(
    prefix="alice/project/my-experiment",
    dash_url="https://api.dash.ml",
    dash_root=None
).run as exp:
    exp.log("Using the server only")
```

Any mode that uses the server needs a login first. See
[Authentication](/ml-dash/get-started/authentication.md). Runs recorded in local mode can
be uploaded later with [`ml-dash upload`](/ml-dash/reference/cli.md#ml-dash-upload).

## Experiment Metadata

Add a description (`readme`), tags, and bindrs for organization:

```python

with Experiment(
    prefix="alice/computer-vision/resnet50-imagenet",
    readme="ResNet-50 training with new augmentation",
    tags=["resnet", "imagenet", "baseline"],
    bindrs=["gpu-cluster", "team-a"]
).run as exp:
    exp.log("Training started")
```

**Metadata fields:**
- `readme`: Human-readable experiment description (shown as the description on the server). Note that the argument is `readme`, not `description`. Unknown keyword arguments are silently ignored.
- `tags`: List of tags for categorization (e.g., ["baseline", "production"])
- `bindrs`: List of bindrs for resource/team association (e.g., ["gpu-1", "team-ml"])

## Experiment Status Lifecycle

Experiments automatically track their status through the lifecycle:

- **RUNNING**: Automatically set when experiment opens
- **COMPLETED**: Set when experiment closes normally
- **FAILED**: Set when exception occurs during experiment
- **CANCELLED**: Can be set manually

**Automatic status management** (recommended):

```python

# Normal completion - status becomes COMPLETED
with Experiment(
    prefix="alice/ml/training",
    dash_url="https://api.dash.ml"
).run as exp:
    exp.log("Training...")
    # Status automatically set to COMPLETED on exit

# Exception handling - status becomes FAILED
with Experiment(
    prefix="alice/ml/training",
    dash_url="https://api.dash.ml"
).run as exp:
    exp.log("Training...")
    raise ValueError("Training failed!")
    # Status automatically set to FAILED on exception
```

**Manual status control**:

```python

from ml_dash import Experiment

exp = Experiment(
    prefix="alice/ml/training",
    dash_url="https://api.dash.ml"
)
exp.run.start()

try:
    exp.log("Training...")
    # ... training code ...
    exp.run.complete()
except KeyboardInterrupt:
    exp.run.cancel()
except Exception as e:
    exp.log(f"Error: {e}")
    exp.run.fail()
```

**Note:** Status updates only work in remote mode. Local mode doesn't track status.

## Resuming Experiments

Experiments use **upsert behavior** - reopen by using the same prefix:

```python

# First run
with Experiment(prefix="alice/ml/long-training").run as exp:
    exp.log("Starting epoch 1")
    exp.metrics("train").log(loss=0.5, epoch=1)

# Later - continues same experiment
with Experiment(prefix="alice/ml/long-training").run as exp:
    exp.log("Resuming from checkpoint")
    exp.metrics("train").log(loss=0.3, epoch=2)
```

## Available Operations

Once an experiment is open, you can use all ML-Dash features:

```python

with Experiment(prefix="alice/test/demo").run as exp:
    # Logging
    exp.log("Training started", level="info")

    # Parameters
    exp.params.set(lr=0.001, batch_size=32)

    # Metrics tracking
    exp.metrics("train").log(loss=0.5, epoch=1)

    # File uploads
    exp.files("models").save("model.pth")
```

## Storage Structure

**Local mode** creates a directory structure:

```
.dash/
└── alice/                          # owner
    └── project/                    # project
        └── my-experiment/          # experiment name
            ├── logs/
            │   └── logs.jsonl
            ├── parameters.json
            ├── metrics/
            │   └── train/
            │       └── data.jsonl
            └── files/
                └── models/
                    └── 7218065541365719/
                        └── model.pth
```

Files are stored under `files/{prefix}/{snowflake_id}/{filename}` where:
- `prefix`: Logical path (e.g., "models", "configs")
- `snowflake_id`: Unique identifier for the file
- `filename`: Original filename

**Remote mode** stores data in MongoDB + S3 on your server.

---

**Next:** Learn about [Logging](/ml-dash/guides/logging.md) to track events and progress.

---

Source: https://docs.dreamlake.ai/dev/plans/tasks

# Tasks and linked Notes

The [deployment record](/dev/notes/tasks) documents staging and production
Tasks delivery on 2026-09-14, including hosted acceptance and the docs/skill
release. See [#301](https://github.com/dreamlake-ai/dreamlake-workspace/issues/301)
and its receipt for the tested versions. Verify current CLI help and the target
server before running operations; that historical receipt is not a fresh
availability check.

## Storage and scope

Task is an optional tracking structure, independent of execution scheduling. Existing Notes are unchanged. Namespace and existing project Node ownership and content read/create/delete permissions apply to every route.

Task fields: stable ObjectId, namespaceId, projectNodeId, materialized path, slug, title, blurb, kind, text tags, status, ordered children IDs, role-based Note references, optional progress, actual startedAt/endedAt, nullable reviewedAt/acceptedAt, deletedAt, revision, createdBy/createdAt/updatedAt. API revisions are decimal strings.

Kinds are free text, normally agenda/workstream/stage/task. No Stage, Workstream or Attempt model. Sessions remain a chat integration; Pipeline, Workflow and TrackedRun retain execution ownership.

One structural parent per task; roots have no parent. Child order is the parent's children array. Paths are project-unique, at most 32 levels. Create ancestors first. Moves preserve IDs and atomically update descendant paths, reject cycles/collisions, and are bounded to 1,000 descendants. Cross-references belong in Notes. Soft-deleted paths remain reserved for restoration.

Note links have role, existing noteId and optional section key. Roles include agent_prompt, comment, details and acceptance. Linking needs access to the existing Note in the same namespace; reads omit inaccessible references. Section keys are references, not validated editor anchors. A text-only task needs no Note. Do not duplicate Note bodies in Task metadata.

## State and events

Status is not_done, done or deprecated. Soft deletion is separate, refuses live children and preserves children placement/history/Notes. Restore requires a live parent.

Progress is an absolute `{mode, completed, total?, unit}` snapshot. Discrete values are nonnegative safe integers; continuous values are finite nonnegative numbers; total must be >= completed. Missing total means unknown, including replacement of a known total. Mode/unit remain fixed until reopen. No mixed-unit or recursive numeric rollup is implied.

Start/end are explicit actual times. End may be known with unknown start; a known end cannot precede a known start. End does not mark done. Progress and done never imply human acceptance. Reviewed/accepted projections remain null in this delivery: a human review identity/evidence protocol is still a design extension.

TaskEvent records eventId, taskId, actor, type/data, occurredAt, receivedAt and taskRevision. Supported client events: started, ended, progress, status_changed, reopened, message, evidence. Structural changes generate server audit events. Same task/eventId, actor and normalized payload replay; a changed payload conflicts. State changes require the task's expectedRevision. The event and new projection commit transactionally. Reopen clears current-cycle progress/start/end/review/acceptance, while preserving history.

Event order and cursors use server taskRevision, not client clocks or Mongo IDs. Context/evidence can preserve historical occurrence times. No separate historical state replay mode. Evidence is an HTTP(S) reference; PR dates never populate task timing.

## HTTP

Base: /namespaces/:namespace/projects/:project/tasks.

- GET/POST base: list/create. List supports prefix, cursor, limit (max 200), includeDeleted.
- GET /resolve?path=...; GET/PATCH/DELETE /:id.
- POST /:id/move with path; PATCH /:id with children reorders the full existing set.
- POST /:id/restore.
- GET /:id/status: task, immediate child summaries, explicitly labeled immediate-child status rollup. Deprecated children excluded from the done denominator.
- GET/POST /:id/events: cursor is taskRevision; max 200; includeDeleted for history.
- GET/POST/DELETE /:id/notes.

Mutations carry expectedRevision in JSON except creation and contextual events. Re-read on 409; never silently overwrite or retry a changed intent. Event retries must preserve the exact event body including expectedRevision and occurredAt.

Enable TASKS_ENABLED=true only after tasks:ensure-indexes succeeds. Startup verifies the actual unique and query indexes. This requires MongoDB transactions/replica set. Index changes are additive; Notes schema is unchanged.

## Display and text links

UI: /:namespace/tasks?project=:slug and /:namespace/tasks/:id?project=:slug. Folder outline, waterfall, explicit start/end/status/progress controls, reorder/move, soft delete/restore, linked Notes and event history. Display **title** + blurb. Open recorded work uses a striped bar to now; unknown start/end are not fabricated. Refresh reads the current projection.

```markdown
1. **Write recovery** — Safely retry a write. <!-- task: [write-recovery](https://dreamlake.ai/ge/tasks/TASK_ID?project=my-project) -->

   Parent-context detail belongs to this source Note.
```

Hidden links retain stable target IDs; indented multiline text belongs to the source list item, not automatically to the target Note. Keyed nested items can identify child associations. AI-assisted text/structure reconciliation remains proposed; this delivery does not scan or rewrite Notes. Arbitrary unkeyed lists remain text.

## Install the Tasks skill

[Download the Tasks skill](/skills/dreamlake-tasks.zip) and unpack the `dreamlake-tasks` directory into your agent’s skills folder. The archive includes the contract and operation examples. Native CLI 0.19.0 provides task commands; the skill is distributed separately as this archive.

---

Source: https://docs.dreamlake.ai/ml-dash/guides/parameters

# Parameters

Metric hyperparameters, configuration values, and experiment settings. Parameters are static key-value pairs that define your experiment.

## Basic Usage

```python

from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.params.set(
        learning_rate=0.001,
        batch_size=32,
        optimizer="adam",
        epochs=100
    )
```

## Nested Parameters

Use nested dictionaries - they're automatically flattened with dot notation:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.params.set(
        model={
            "architecture": "resnet50",
            "pretrained": True,
            "num_classes": 1000
        },
        optimizer={
            "type": "adam",
            "lr": 0.001,
            "weight_decay": 0.0001
        }
    )

    # Stored as:
    # model.architecture = "resnet50"
    # model.pretrained = True
    # optimizer.type = "adam"
    # ...
```

## Class Objects Support

Pass configuration classes directly (perfect for `params-proto`):

```python

class TrainingConfig:
    learning_rate = 0.001
    batch_size = 32
    epochs = 100

class ModelConfig:
    architecture = "resnet50"
    hidden_size = 768

with Experiment(prefix="alice/project/my-experiment").run as exp:
    # Pass class objects directly
    exp.params.log(training=TrainingConfig, model=ModelConfig)

    # Stored as:
    # training.learning_rate = 0.001
    # training.batch_size = 32
    # training.epochs = 100
    # model.architecture = "resnet50"
    # model.hidden_size = 768
```

Private attributes (starting with `_`) are automatically skipped.

## Updating Parameters

Call `exp.params.set()` multiple times - values merge and overwrite:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    # Initial parameters
    exp.params.set(learning_rate=0.001, batch_size=32)

    # Add more
    exp.params.set(optimizer="adam", momentum=0.9)

    # Update existing
    exp.params.set(learning_rate=0.0001)

    # Final result:
    # learning_rate = 0.0001  (updated)
    # batch_size = 32
    # optimizer = "adam"
    # momentum = 0.9
```

## Loading from Config Files

**From JSON:**

```python

import json
from ml_dash import Experiment

with open("config.json", "r") as f:
    config = json.load(f)

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.params.set(**config)
    exp.log("Configuration loaded")
```

**From command line arguments:**

```python

import argparse
from ml_dash import Experiment

parser = argparse.ArgumentParser()
parser.add_argument("--lr", type=float, default=0.001)
parser.add_argument("--batch-size", type=int, default=32)
args = parser.parse_args()

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.params.set(**vars(args))
```

**From dataclass:**

```python

from dataclasses import dataclass, asdict
from ml_dash import Experiment

@dataclass
class TrainingConfig:
    learning_rate: float = 0.001
    batch_size: int = 32
    epochs: int = 100

config = TrainingConfig()

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.params.set(**asdict(config))
```

**From params-proto (or any class):**

```python

from ml_dash import Experiment

# Works with params_proto or any Python class
class Args:
    batch_size = 64
    learning_rate = 0.001

with Experiment(prefix="alice/project/my-experiment").run as exp:
    # Pass class directly - automatically extracts attributes
    exp.params.log(Args=Args)
```

## Complete Training Configuration

```python

with Experiment(prefix="alice/cv/resnet-imagenet").run as exp:
    exp.params.set(**{
        "model": {
            "architecture": "resnet50",
            "pretrained": True,
            "num_classes": 1000
        },
        "data": {
            "dataset": "imagenet",
            "train_split": 0.8,
            "num_workers": 4
        },
        "training": {
            "epochs": 100,
            "batch_size": 256,
            "learning_rate": 0.1,
            "optimizer": "sgd",
            "momentum": 0.9
        }
    })
```

## Retrieving Parameters

Get parameters during or after an experiment:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.params.set(learning_rate=0.001, batch_size=32)

    # Retrieve flattened parameters
    params = exp.params.get()
    print(params)
    # → {"learning_rate": 0.001, "batch_size": 32}

    # Retrieve as nested dictionary
    params_nested = exp.params.get(flatten=False)
    print(params_nested)
    # → {"learning_rate": 0.001, "batch_size": 32}
```

## API Methods

### `set()` / `log()`

Both methods do the same thing - set or merge parameters:

- **Nested dicts** are automatically flattened to dot notation
- **Class objects** are converted to dictionaries by extracting their attributes
- **Multiple calls** merge parameters (later values override earlier ones)
- Returns self for potential chaining

The `log()` method exists for semantic clarity but behaves identically to `set()`.

### `get()`

Retrieve current parameters:

- **`flatten=True` (default)**: Returns flattened dict with dot notation
- **`flatten=False`**: Returns nested dict structure

## Storage Format

**Local mode** - Stored as JSON:

```bash
cat .dash/alice/project/my-experiment/parameters.json
```

The flattened parameters sit under `"data"`:

```json
{
  "version": 1,
  "data": {
    "learning_rate": 0.001,
    "batch_size": 32,
    "optimizer": "adam",
    "model.architecture": "resnet50",
    "model.pretrained": true
  },
  "createdAt": "2025-10-29T10:30:00.000000Z",
  "updatedAt": "2025-10-29T10:30:00.000000Z"
}
```

**Remote mode** - Stored in MongoDB as a document.

---

**Next:** Learn about [Metrics](/ml-dash/guides/metrics.md) for time-series metrics tracking.

---

Source: https://docs.dreamlake.ai/dev/skills

# Docs to skills

Maintain the instructions people review in docs. Public skills distribute
those instructions to agents. A correction starts in the owning guide; it
must not become an independent edit to a generated skill.

## Sources

| Skill | Facts and behavior | Task routing | Public output |
|---|---|---|---|
| `dreamlake-notes` | Workspace `docs/pages/notes/+Page.mdx` | `docs/skill-guides/notes/SKILL.md` and `actions/*.md` | Action guides plus generated Notes references |
| `dreamlake-cli` | CLI repository `docs/pages/**/+Page.mdx` | CLI `docs/skill-guides/cli/SKILL.md` and `actions/*.md` | Action guides plus the full generated CLI reference |
| `dreamlake-scene-generation` | Workspace `docs/pages/{scene-generation,libraries,envs,envs/layers}/+Page.mdx` | `docs/skill-guides/scene-generation/SKILL.md`, `actions/*.md` and `tools/*.py` | Action guides and scene tools plus those four generated references |

Docs remain authoritative for product behavior, API facts and runnable
examples. Action guides are separately authored routing and task procedures;
keep them short, concrete and scoped to one operation. They may select useful
details from docs but must not become another API manual. Entrypoints name the
CLI as the default interface and route to independent action files. Keep Python
guidance in a separate SDK integration skill only where documented APIs warrant
one; do not mix SDK and CLI steps into one automatic route.

The Notes bundle keeps its generated Notes page for reference, plus focused
read, edit, collaboration and attachment actions. The CLI bundle keeps its
complete generated reference corpus and adds task-first actions. The
scene-generation bundle also ships runnable helpers: everything under the
guide's `tools/` (the scripts and their pytest suite) is copied into the
skill and hashed as guide source, so a tool fix follows the same
docs-commit-then-sync path as a procedure fix. Only these three generated
cores are covered by this pipeline; other public skills remain explicitly
reviewed against their affected docs.

The public skills repo's `sources.json` records the source repository, commit
and generator hash. `generated-files.json` records the exact files owned by
the synchronizer. Other public skills are not yet migrated to this flow;
their owners must still reconcile affected docs and skill content explicitly.

## Update and check

Commit the reviewed source changes on a feature branch. From a checkout of
`dreamlake-skills`, with access to the two source repositories:

```bash
python3 scripts/sync-docs.py --workspace /path/to/dreamlake-workspace --cli /path/to/dreamlake-cli
python3 scripts/sync-docs.py --workspace /path/to/dreamlake-workspace --cli /path/to/dreamlake-cli --check
```

The script reads committed `HEAD` snapshots, including docs pages, generators,
the workspace's `docs/skill-guides/{notes,scene-generation}/` (the
scene-generation guide includes its `tools/` — scripts and their test suite
are hashed and shipped as guide source) and the CLI's `docs/skill-guides/cli/`,
then runs each repository's generator in a temporary directory. `sources.json`
records commits, generator hashes, every guide-file hash, the Notes
source-page hash, and the hashes of the four scene reference pages it bundles
(`scenePages`: scene-generation, libraries, envs, envs/layers);
`generated-files.json` records the exact skill outputs owned by sync. Review
that file list before publication.
Sync does not modify source checkouts, publish docs, install skills or remove
unrelated resources. Node and Git are required; generation needs no credentials.

To reproduce the recorded release instead of checking current source heads:

```bash
python3 scripts/sync-docs.py --workspace /path/to/dreamlake-workspace --cli /path/to/dreamlake-cli --check --locked
```

Use `--check` against current source heads to detect propagation gaps.
`--locked` proves reproducibility of the recorded source only; it cannot prove
that newer docs have propagated. Publish accessible companion source branches
before asking a teammate to reproduce unpublished commits.

## Verification and release

- Inventory user tasks and split CLI and SDK requests into distinct
  entrypoints where both interfaces are supported. Put each frequent operation
  in its own action file; preserve setup, exact commands, revision rules,
  capability/version limits and failure handling. Link the full reference only
  when a step needs detail. Never summarize away required API operations or
  CodeTabs examples.
- Evaluate independent requests: representative tasks for every action (Notes
  read, edit, watch, attachments; CLI setup, data, Notes, artifact, workflow)
  and boundaries for SDK-only requests, unreleased flags, stale revisions and
  paths containing spaces. Confirm the right interface and action, safe failure
  response and selective reference lookup. Revise source docs or guides when
  an evaluation exposes a gap.
- Commit source docs, action guides and generators. Run each generator and its
  `--check`, sync public outputs and review the generated diff plus source map.
  Run public offline sync tests and `--verify-files`. Full sync `--check`
  against current heads detects drift; `--locked` reproduces recorded source,
  while `--verify-files` checks local integrity only.
- Link the source docs PR and skills PR. Deploy docs, publish skills, then
  compare live Markdown and a fresh skill install/download with the reviewed
  output. Report each stage separately; source sync and merge do not prove
  publication or installed readback.

Keep private operational material out of public exports. Review the generated
file list before publishing. The workspace `AGENTS.md` states this policy;
`CLAUDE.md` points to it.

---

Source: https://docs.dreamlake.ai/dev/notes/audio-playback

# Notes audio playback

Unreleased — 2026-09-27. The Notes title has a borderless waveform button.
It opens a player over the document and reads the current note in short passages.
This implementation uses ElevenLabs; no browser speech fallback is silently substituted.

## Credentials

Set `ELEVENLABS_API_KEY` and `ELEVENLABS_VOICE_ID` in the **dreamlake-server** runtime
secret configuration. For local development use the server's ignored `.env` file.
`ELEVENLABS_MODEL_ID` defaults to `eleven_flash_v2_5`.
Create a restricted ElevenLabs key with text-to-speech access and a provider-side
credit ceiling. Use separate keys for development and production. Restart the
server after changing its environment. Never put the key in `VITE_*`, the frontend,
a note, source control, or chat. Users use their existing DreamLake login; they do
not supply individual ElevenLabs keys.

The internal browser transport is authenticated
`POST /namespaces/:slug/notes/:noteId/speech`, with `{ "text": "A short passage." }`.
Unreleased — 2026-09-29: signed-in namespace members and recipients with an
active, previously accepted read or edit share grant can synthesize audio for a
live note. The same access check protects voice options. Membership in the
recipient's own workspace is not required. Anonymous visitors and signed-in
public readers without a share grant cannot synthesize audio. Open the shared
note while signed in to accept its link before using playback. Disabling sharing
or removing the recipient's grant blocks subsequent audio requests; already
buffered audio may continue playing. The existing per-user limits apply equally
to members and share recipients. Voice-options failures display the server's
error without promising that the default voice will work.
Missing key or voice configuration returns 503 with a setup message.

The server forwards to ElevenLabs `stream/with-timestamps` with `pcm_24000` and
streams NDJSON through without buffering a full note. Browser requests cannot
choose arbitrary provider URLs, voices, or models. The client schedules PCM in
Web Audio as chunks arrive. It highlights a passage, rather than attempting
word alignment against Markdown transformed for speech. Provider alignment data
is available in the transport for a future word-highlight mode.

Each request accepts at most 1,500 characters. Per server process, each user has
two concurrent requests and a 60,000-character hourly budget. A request is
aborted on client disconnect or after 45 seconds. These are process-local
safety limits, not globally distributed billing quotas: the provider-side key
credit ceiling must be configured before production enablement. The server
does not forward provider diagnostics to the client.

Server-side caching — 2026-09-30: completed speech responses (PCM audio and alignment
timestamps) are saved permanently and privately in `S3_BUCKET` under
`speech-cache/v1/<namespaceId>/<noteId>/<sha256>.ndjson`. The digest covers the
voice, output format, and exact provider payload (text, model, and surrounding
context). Every replay rechecks current note access; no public or presigned audio
URL is issued. Cache hits avoid provider usage but retain existing playback limits.
New responses stream immediately and are saved only after successful completion;
failed, cancelled, or responses over 16 MiB are not stored. Storage failures fall
back to synthesis. There is no application expiry or automatic deletion for this
prefix; do not apply an expiring S3 lifecycle rule to it.
The response header `x-speech-cache` reports `hit` or `miss` for verification.
No public skill impact: this changes only the internal browser transport, with
no CLI or SDK task contract changes.
ElevenLabs receives the passages requested for playback; its account retention
settings apply. Stopping cancels the current request; text already submitted
may already have incurred provider usage.

## Editing and playback

- The caret and normal selection remain independent from the passive playback
  highlight. Clicking text never seeks audio.
- Typing or scrolling manually suspends follow mode, without pausing audio.
  **Back to audio** reveals the current passage and restores follow mode.
- The currently spoken passage finishes from its original audio. Editing inside
  it replaces the highlight with a side marker. Anchors map through local and
  collaborative edits. Future passages use the latest document text.
- **Read from cursor / selection** explicitly starts at the caret or restricts
  reading to the selection. The selection's end tracks subsequent edits.
- The UIKit slider seeks within the buffered audio of the current passage.
  This first implementation does not show an estimated whole-note duration.
- Pause/resume and speed changes are local. Released — 2026-10-01, UI PR
  [#658](https://github.com/dreamlake-ai/dreamlake-ai/pull/658):
  playback speed preserves voice pitch through client-side time stretching of
  the PCM stream. The 1× path plays the original audio. Faster rates load a
  Signalsmith Stretch AudioWorklet/WASM processor; progress stays in original
  audio seconds while remaining time accounts for the selected speed. Startup
  waits for the processor and buffered audio, and passage completion drains
  its output tail. If pitch-preserving processing is unavailable or fails,
  playback returns to 1× and shows an error rather than raising the voice pitch.
  The last ten completed passages are
  cached in memory per mounted note/player and reused when their spoken text
  matches. Closing clears the cache. Code fences and Markdown destinations are
  omitted; this is a bounded text normalizer, not a complete Markdown narrator.

## Local voice preferences

Unreleased — 2026-09-30: manual speaker and ElevenLabs model selections become
favorites saved per signed-in user in this browser's localStorage. On each player
opening, an epsilon-greedy bandit picks independently from available favorites:
20% uniform exploration, otherwise the best smoothed preference score (random
ties). Changing a selection rewards the chosen option and rejects the replaced
option. Automatic picks never count as positive feedback. Choices stay fixed
while reading, seeking, pausing, or resuming; removed provider options are excluded.

Memory uses a compact score table (12 favorites per dimension) plus the last 24
manual edits. Scores decay on feedback so recent preferences carry more weight.
Account Settings includes a **Reading voice preferences** section with saved
speaker/model names, individual removal, memory usage, and a reset action. These
changes apply on the next player opening and do not interrupt active audio.
The serialized record is capped at 8 KiB in UTF-8, pruning oldest edits and then
least recently selected favorites. It stores IDs, display names, scores and timestamps, never note text
or audio. Invalid or inaccessible storage falls back to the existing defaults.
A table alone loses the recent change trail; an edit list alone loses learning
when pruned. The bounded combination keeps both without replaying a growing log.
No public skill impact: this is browser-only playback preference state.

## Verification

The UI includes `tests/notes-audio-preview`, a real CodeMirror + player harness
with a quiet synthetic PCM stream, explicitly labeled as synthetic. It exercises
browser audio, pause/resume, selection, scroll behavior and provider errors
without credentials. It does not prove ElevenLabs voice output.

Pitch signal tests render the real WASM engine with a 440 Hz tone at changed
speeds, checking pitch and duration across chunk boundaries, rate changes,
underruns, and a 48 kHz context. Worklet lifecycle tests use an empty input list
for idle, pause, and disposal, matching the browser buffer-only graph. A Chrome
preview measurement of its synthetic 220 Hz stream at 2× returned 219.7 Hz.
This establishes pitch preservation for synthetic signals; physical iPad voice
quality still requires device acceptance.

![Synthetic Notes preview at 2× after pause and paragraph replay](/screenshots/notes-audio/pitch-preserving-2x.png)

UI tests cover Markdown ranges, edit mapping, packet boundaries, odd PCM byte
boundaries, pause/resume and network underruns. Server tests cover access checks,
missing configuration, provider error sanitization, request limits and stream
cleanup. Live voice acceptance still requires a configured key and voice.

The generated workspace `dreamlake` reference includes this operations page.
No distributed task-skill impact: this is an internal browser transport and server
operations page. The public Notes document/CLI API and task procedures are
unchanged; no new CLI speech command or SDK contract is introduced.

## Browser authentication transport

The application sends OAuth token and user-info requests to the DreamLake API
(`/api/auth/oauth2/token` and `/api/auth/oauth2/userinfo`). Authorization still
opens the identity provider. The backend forwards only authorization-code PKCE
and refresh-token grants for `VUER_AUTH_PUBLIC_CLIENT_ID` to the fixed
`VUER_AUTH_URL` HTTPS origin. The identity provider continues to validate PKCE,
redirect registration, and tokens.

`VUER_AUTH_BROWSER_ORIGINS` is a comma-separated exact-origin allowlist. A local
frontend must have its origin configured there and its callback registered with
the identity provider. No Vite proxy is used. Token responses use `no-store`;
provider credentials and diagnostics are never logged or returned in error text.

Deployment injects `ELEVENLABS_API_KEY` from the GitHub environment secret and
`ELEVENLABS_VOICE_ID` / `ELEVENLABS_MODEL_ID` from environment variables. Voice
listing permission is not needed when an allowed voice ID is already configured.

## Inspect and control preference learning

Settings shows saved speaker and model favorites, smoothed preference scores,
and up to 24 recent manual changes. The scores count selecting and replacing
options; automatic selections never reward themselves. Exploration defaults
to 20% among available saved favorites, with 0%, 10% and 20% controls.
Keeping recent change records can be turned off independently of learning.
Clear recent changes preserves favorites and aggregate scores. Removing a
favorite also removes records involving it; Reset voice preferences forgets
favorites, scores, records and restores default settings. Storage remains
bounded to 12 speakers, 12 models and 8 KiB per account in this browser.
Changes apply the next time the audio player opens.

## Volume and iPad playback sessions

Released in UI PR [#647](https://github.com/dreamlake-ai/dreamlake-ai/pull/647),
2026-10-01. The Notes player centers Play between previous/next paragraph
controls. Pin stays at the far left. The cursor group (Read from cursor / selection
and conditional Back to audio) precedes the volume/speaker control in both visual
and keyboard order. A 12 px spacer sits immediately before the speaker icon:
after Read from cursor / selection normally, and after Back to audio when it
appears. The speaker icon sits immediately left of the playback controls. Speed and remaining paragraph time sit right of Play. Remaining time accounts
for playback speed and describes the buffered paragraph, not the entire note.
Voice and model selectors have up to 90 px each and shrink to 40 px in narrow
panels; very narrow panels place them on a second row. These layout refinements
ship in UI PR [#651](https://github.com/dreamlake-ai/dreamlake-ai/pull/651).
The Notes Share trigger shows a person-plus icon without presence avatars and
a plus icon alongside visible avatars; sharing permissions are unchanged.
Tap the volume button to open the slider and mute/unmute control. Unmuting
restores the last nonzero level without restarting streamed or cached audio.

Speech requests `navigator.audioSession.type = 'playback'` when available.
iPadOS can otherwise silence default Web Audio in Silent Mode, even while
media in another tab remains audible. See [WebKit issue 237322](https://bugs.webkit.org/show_bug.cgi?id=237322).
The previous session type is restored when the last Notes player closes.
Browsers without the Audio Session API keep the existing audio path; disabling
Silent Mode is a workaround on older iPadOS versions. Physical iPad verification
is still pending; desktop tests do not establish device audibility.

![Actual Notes player with grouped left controls](/screenshots/notes-audio/controls-near-play-wide.jpg)

![Actual player in a narrow panel](/screenshots/notes-audio/controls-near-play-narrow.jpg)

No public skill impact: this changes the browser UI and playback session,
with no SDK, CLI, or API contract changes.

---

Source: https://docs.dreamlake.ai/ml-dash/guides/metrics

# Metrics

Track time-series metrics that change over time - loss, accuracy, learning rate, and custom measurements.

## Basic Usage

Log train and eval metrics together with a single call:

```python

from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:

    for epoch in range(10):
        train_loss, train_acc = train_one_epoch(model)
        eval_loss, eval_acc = evaluate(model)

        # Log all metrics for this epoch in one call
        exp.metrics.log(
            epoch=epoch,
            train=dict(loss=train_loss, accuracy=train_acc),
            eval=dict(loss=eval_loss, accuracy=eval_acc)
        )
```

## Alternative: Prefix-Based Logging

You can also log metrics using namespace prefixes with explicit context:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    for epoch in range(10):
        # Log train metrics with prefix
        exp.metrics("train").log(loss=train_loss, accuracy=train_acc, epoch=epoch)

        # Log eval metrics with prefix
        exp.metrics("eval").log(loss=eval_loss, accuracy=eval_acc, epoch=epoch)
```

Include `epoch` (or `step`) in each group's `log()` call. A bare
`exp.metrics.log(epoch=epoch)` writes to a separate unnamed series; it is not
attached to the `train` and `eval` rows. The grouped form above,
`exp.metrics.log(epoch=..., train=dict(...), eval=dict(...))`, does copy
`epoch` into every group.

## Custom Metric Groups

Define your own metric groups beyond train/eval:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Log with custom groups
    exp.metrics.log(
        step=100,
        train=dict(loss=0.5, accuracy=0.85),
        eval=dict(loss=0.6, accuracy=0.82),
        system=dict(gpu_memory=4.2, cpu_percent=45),
        lr=dict(value=0.001)
    )
```

## Reading Data

Read metric data by index range:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    # Log data
    for i in range(100):
        exp.metrics("train").log(loss=1.0 / (i + 1), step=i)

    # Read first 10 points
    result = exp.metrics("train").read(start_index=0, limit=10)

    for point in result['data']:
        print(f"Index {point['index']}: {point['data']}")
```

## Buffer API

For high-frequency logging (e.g., per-batch), use the buffer API to accumulate values and periodically log summary statistics:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    for epoch in range(10):
        for batch in dataloader:
            loss = train_step(batch)
            acc = compute_accuracy(batch)

            # Buffer per-batch values (not written to disk yet)
            exp.metrics("train").buffer(loss=loss, accuracy=acc)

        # At end of epoch, compute and log summary statistics
        exp.metrics.buffer.log_summary(epoch=epoch)  # default: mean, plus epoch
```

This produces statistics like `loss.mean`, `accuracy.mean` per epoch.

### Buffer API Methods

- **`metrics("prefix").buffer(**kwargs)`** - Accumulate values for later summarization
- **`metrics.buffer.log_summary(*aggs)`** - Compute statistics and log to all prefixes
- **`metrics.buffer.peek(prefix, *keys, limit=5)`** - Non-destructive look at buffered values

### Supported Aggregations

```python
# Default (just mean)
exp.metrics.buffer.log_summary()

# Multiple aggregations
exp.metrics.buffer.log_summary("mean", "std", "min", "max", "count")

# Percentiles
exp.metrics.buffer.log_summary("p50", "p90", "p95", "p99")

# First/last values
exp.metrics.buffer.log_summary("first", "last")
```

Available aggregations: `mean`, `std`, `min`, `max`, `count`, `median`, `sum`, `p50`, `p90`, `p95`, `p99`, `first`, `last`

### Multiple Prefixes

Buffer works across multiple prefixes simultaneously:

```python

for batch in dataloader:
    train_loss = train_step(batch)
    val_loss = validate_step(batch)

    # Buffer to different prefixes
    exp.metrics("train").buffer(loss=train_loss)
    exp.metrics("eval").buffer(loss=val_loss)

# Single call logs summaries for ALL prefixes
exp.metrics.buffer.log_summary("mean", "std")
```

## Summary Cache (Legacy API)

The summary cache API is still supported for backward compatibility:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    for epoch in range(10):
        for batch in dataloader:
            loss = train_step(batch)

            # Store per-batch values (not written to disk yet)
            exp.metrics("train").summary_cache.store(loss=loss)

        # At end of epoch, summarize and write to disk
        exp.metrics("train").summary_cache.set(epoch=epoch)
        exp.metrics("train").summary_cache.summarize()
```

### Summary Cache Methods

- **`store(**kwargs)`** - Accumulate values for later summarization
- **`set(**kwargs)`** - Set metadata (epoch, lr) that doesn't need aggregation
- **`summarize(clear=True)`** - Compute statistics and append to metrics
- **`peek(*keys, limit=5)`** - Non-destructive look at stored values

### Rolling vs Cumulative

```python

# Rolling window (default) - clears cache after summarize
metric.summary_cache.summarize()  # clear=True by default

# Cumulative - keeps accumulating
metric.summary_cache.summarize(clear=False)
```

## Training Loop Example

```python

with Experiment(prefix="alice/cv/mnist-training").run as exp:
    exp.params.set(learning_rate=0.001, batch_size=32)
    exp.log("Starting training")

    for epoch in range(10):
        train_loss = train_one_epoch(model, train_loader)
        val_loss, val_accuracy = validate(model, val_loader)

        # Log metrics
        exp.metrics("train").log(loss=train_loss, epoch=epoch + 1)
        exp.metrics("eval").log(loss=val_loss, accuracy=val_accuracy, epoch=epoch + 1)

        exp.log(
            f"Epoch {epoch + 1}/10 complete",
            metadata={"train_loss": train_loss, "val_loss": val_loss}
        )

    exp.log("Training complete")
```

## Multiple Metrics in One Call

Combine related metrics:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    for epoch in range(10):
        exp.metrics("train").log(
            epoch=epoch,
            loss=0.5 / (epoch + 1),
            accuracy=0.8 + epoch * 0.01
        )
        exp.metrics("eval").log(
            epoch=epoch,
            loss=0.6 / (epoch + 1),
            accuracy=0.75 + epoch * 0.01
        )
```

## Timestamps

Every metric data point automatically records a `_ts` field (Unix timestamp, seconds since epoch). You can also provide it explicitly or inherit it from the previous call:

```python
import time

# Auto-assigned (default)
exp.metrics("train").log(loss=0.5)
# → data: {"loss": 0.5, "_ts": 1742382000.123}

# Explicit timestamp
exp.metrics("train").log(loss=0.5, _ts=time.time())

# Inherit timestamp from previous metric or track call (same thread)
exp.metrics("train").log(loss=0.5)                  # sets _last_timestamp
exp.metrics("eval").log(loss=0.6, _ts=-1)           # inherits same _ts

# Cross-inheritance with tracks
exp.tracks("robot/pos").append(x=1.0, _ts=100.0)   # sets _last_timestamp
exp.metrics("train").log(loss=0.5, _ts=-1)          # inherits 100.0
```

`_ts=-1` inherits across **both metrics and tracks** within the same thread.

## Storage Format

**Local mode** - JSONL files:

```bash
cat .dash/alice/project/my-experiment/metrics/train/data.jsonl
```

```json
{"index": 0, "data": {"loss": 0.5, "epoch": 1, "_ts": 1742382000.1}, "createdAt": "2026-03-20T10:00:00.000000Z"}
{"index": 1, "data": {"loss": 0.45, "epoch": 2, "_ts": 1742382001.2}, "createdAt": "2026-03-20T10:00:01.000000Z"}
{"index": 2, "data": {"loss": 0.40, "epoch": 3, "_ts": 1742382002.3}, "createdAt": "2026-03-20T10:00:02.000000Z"}
```

**Remote mode** - Two-tier storage:
- **Hot tier:** Recent data in MongoDB (fast access)
- **Cold tier:** Historical data in S3 (auto-archived after 10,000 points)

---

**Next:** Learn about [Files](/ml-dash/guides/files.md) to upload models, plots, and artifacts.

---

Source: https://docs.dreamlake.ai/dev/notes/list-ordering

# Notes list ordering

## 2026-09-28 — Hierarchical list addresses

Lists need selectable containers and distinguishable checklist items, while all
addresses must follow the same reading order as paragraphs. Separate counters
hide the relationship between a paragraph and the list immediately after it.

Use `p`, `ul`, `ol` and `li`, matching the semantic HTML elements. List and
item IDs include their containing list/item path. A section might contain
`s1.p1`, `s1.ul2`, `s1.ul2.li3`, `s1.ul2.li4`, then `s1.p5`.
A nested ordered list extends the item path: `s1.ul2.li4.ol5`, with an item
`s1.ul2.li4.ol5.li6`. Numeric suffixes use one section-wide counter.

Checkboxes are item state: a task is still `li`, with `data-checked="true"`
or `"false"`. Ordinary items omit the attribute. No `tl`, `tli` or `cli`
address type is needed. A mixed list remains its underlying `ul` or `ol`.

Traverse lists before their items, depth-first, using a single section counter.
Nested lists consume numbers too. Paragraph wrappers inside list items do not.
The counter resets per section, with pre-heading content under `s0`. A whole
list target includes its items; an item includes its continuation and nested
content. Preserve exact Unicode code-point source spans, including CRLF.

Addresses are snapshot-local. Clients must discover IDs from each snapshot,
retain its revision and use conditional writes. Old per-type numbering is not
an alias: retaining it would make the same address mean two different things.
Historical source is rendered using the current addressing implementation, so
rediscover addresses after a renderer upgrade even when reading an old revision.

Tests cover mixed paragraphs and lists, nested ordered and unordered lists,
checked and unchecked items, preambles, section resets, emoji, CRLF, exact
scoped source and native HTML checkboxes. Caller-supplied data attributes cannot
forge checklist state. The Notes docs and action guides are the source for the
public skill; generation, synchronization and live publication are separate checks.

---

Source: https://docs.dreamlake.ai/dev/notes/incremental-read-failure

# Notes incremental read failure

## Dev Notes — 2026-09-28

Installed CLI 0.33.0 against production reproduced `400 bad_reference` for both
a retained SHA-256 reference and a relative timestamp. Inspecting the HTTP error
body revealed `Character alignment trace limit exceeded`. Reference resolution
was valid; the broad route catch mislabeled patch generation failures. The CLI
currently displays the flat error code without its explanatory message.

The saved source pair was 2,475 and 4,747 UTF-16 units. The old generator fails
on that pair; direct line alignment produces an exact round trip. Private source
text is excluded from this repository. Synthetic fixtures cover the same failure.

Read-only unified diffs use bounded line alignment, three context lines, exact
newline preservation and existing source/output limits. Character alignment and
native-identity write compilation retain their safety limits. No merge/exact
policy changes are introduced. Invalid references are 400, missing baselines
404, generation errors 422, and service failures 503 with server-side logging.

Validation covers large rewrites, distant localized hunks, Unicode, CRLF, missing
final newline, empty/no-op sources, hash and time route reads, and error classes.
Production disposable-note checks verified task presence, a browser-originated
RTC edit read through the CLI, and a merge-mode inline comment with live readback.
These checks do not establish deployment of this fix.

The separate successful-but-missing eight-comment incident is now reproduced:
installed native CLI 0.33.0 sends an empty `payload.patch` for
`--file - < patch.dff`, visible in `--dry-run --json`. A pipe or explicit file
path preserves the bytes. Both retained receipt journals contain only additional
browser operations and no corresponding native comment message. The server
acknowledged a no-op, rather than discarding a submitted merge. A companion CLI
fix uses Bun's native stdin stream and rejects empty patches before sending.
Its native packaging gate checks regular-file redirection, pipes, explicit file
paths, and empty/UTF-8/size rejection. A newly compiled fixed CLI submitted eight
comments via redirected stdin to a disposable note; all eight appeared exactly
once in the acknowledged snapshot, preserving previous comments and a peer edit.

The preserved unified patch independently hits the character-alignment trace
budget in the write parser. The CLI now retains that explanatory error instead
of asserting a baseline mismatch. Existing write limits remain intentional.
A live stale-baseline MERGE test inserted eight comments and preserved a peer's
intervening RTC insertion. A browser-originated edit was independently verified
through incremental reads; a second browser concurrency run was interrupted by
browser-control unavailability. No pitch-note writes were performed.

Legacy `insert --if-match` uses a quoted ETag, not an RTC token. The companion
CLI rejects that mismatch before network activity and updates generated help.
A guarded legacy insertion example was executed on a disposable note and read
back through the modern interface. Exact mode remains opt-in; a 412 during
concurrent editing is not independently evidence of a defect.

Affected skill: `dreamlake-notes`, generated from the Notes reference. Synchronize
its public companion from this committed source. Release requires review, merge,
API/docs deployment, skill publication and fresh installed readback. None is
implied by local validation or PR creation.

---

Source: https://docs.dreamlake.ai/dev/notes/highlight-metadata

# Notes highlight metadata

## 2026-09-26

Extend the shared highlight parser with optional `user` and `comment` attributes.
Reuse the inline/sidebar comments toggle, uikit Popover and comment rail.
Keep metadata outside source-mapped highlighted text; read-only views expose no edits. Preserve exact raw Markdown, colors, table cells, Unicode
and revision-safe edits. Unknown and duplicate attributes remain literal.

The Notes guide is the source for the generated public `dreamlake-notes` skill.
The Markdown authoring guide links its syntax and escaping contract. No CLI/SDK API change is needed: both already store arbitrary Markdown.
CLI 0.31.3 refreshes the bundled CLI skill with the same runnable example.
CLI/API HTML export continues to preserve rich directives as source text.

Release status: shipped 2026-09-26. App PR #483 merged and deployed to staging
and production at `897bb613d1fab2c4c5af9d26b2cc75bada019f23`.
Production deploy `6ab86d5cfe373a000853165b` published 2026-09-27T01:13:38.515Z;
staging deploy `6ab86cad8b20e000081df2d6` served the same commit.
Live checks covered popovers, direct highlight editing, shared sidebar cards,
Unicode, escaped metadata and keyboard access in tables. QA source and revision
remained unchanged; home and artifact routes returned 200 in both environments.
The user explicitly waived waiting for final CI; local browser regressions,
focused tests and TypeScript passed before deployment.

Docs 0.1.28 and CLI docs 0.31.3 were published and read back against generated web
output. Public skills PR #64 merged; fresh download and installed Notes/CLI skill
files matched. CLI 0.31.3 publication workflow succeeded; its versioned native
binary passed checksum verification and fresh bundled-skill installation.

## User checklist

- [x] Clicking highlighted text reveals its editable Markdown (companion app PR #484).
- [x] Reuse comment UI and the existing inline/sidebar toggle state.
- [x] Use uikit Popover for inline metadata and existing comment rail for sidebar mode.
- [x] Document existing CLI support with a full revision-safe matching-text example.
- [x] Ship app, docs and public skill and verify each live surface.

## 2026-09-26 follow-up — Hover and canonical handles

- [x] Remove the inline icon; hover or keyboard-focus the highlight for only its handle and comment.
- [x] Reuse the uikit tooltip primitive for the informational popover, without stealing editor focus.
- [x] Keep click-to-source editing, the shared toggle, and sidebar comment cards.
- [x] Insert canonical public handles and resolve exact personal profiles; never infer an account from a legacy name.
- [x] Preserve self-declared attribution and raw Markdown.
- [x] TypeScript, 2,606 unit tests (five skipped), browser regression, and visual preview pass.
- [x] Deploy and verify the correction, then publish docs and synchronized Notes/CLI skills.

App PR #487 shipped `62eb384aad328cfc6d51602cf84e655be5850dd1` to staging
(`6ab876d332937d0008df1e09`) and production (`6ab877685aec060008976389`,
published 2026-09-27T01:56:35.891Z). Live checks verified the minimal hover/focus
popover without an icon, direct source editing, the shared sidebar, exact public
profile resolution for `geyang`, and unresolved legacy names. Production QA source,
hash and RTC revision remained unchanged. Home and artifact routes returned 200.
Both dedicated QA notes were soft-deleted and temporary previews stopped.

The revised CLI example ran with an ETag precondition and exact readback on the
QA note. CLI #154 packages this guidance in 0.32.1; workspace #791 publishes docs
0.1.30; public skills #65 synchronizes the committed Notes and CLI sources.

Docs 0.1.30 shipped from workspace #791 merge
`328de60ba37821bf08c92d615fe9c150ffaa9664` in deploy
`6ab87a2a6c3922c0a35e964b`; live Notes/Markdown/dev-note pages and the permanent
version snapshot matched generated web output exactly. Public skills #65 merged
`d439e156de04bd3ea45b8d0e88e2d497f64ee298`, synchronized to that workspace commit
and CLI #154 merge `aba16ff689adf8cc36fd0416f835798f97eb443a`.
A fresh public clone passed current-source and 46-file integrity checks; the
installed Notes and CLI symlinks matched all 46 files after a clean fast-forward.
CLI 0.32.1 publication workflow `36288497772` succeeded from the reviewed
`aba16ff689adf8cc36fd0416f835798f97eb443a` commit. The public native darwin-arm64
binary reports 0.32.1; its SHA256
`2b0f8b033718ea7df714fa4ff21e438f9405ca7002ccc1000e08fe8223f2b6ec`
and byte size match the manifest, and an isolated install matches all 44 bundled
skill files. CLI docs 0.32.1 shipped in deploy `6ab8818ea90f29f9e975ebaf`;
rich-content and release-notes Markdown match generated output on both the public
site and permanent version alias. A fresh npm installation also reports 0.32.1
and matches all 44 bundled skill files. Both publication jobs passed; no further
local test runs were needed for these release records.

App CI run `36286802167` completed with formatting, component tests, build,
both E2E shards and end-to-end aggregation passing. Its final PR-state gate
reported the candidate superseded because the PR had already merged under the
user's instruction to deploy without waiting for CI; no test failed.

---

Source: https://docs.dreamlake.ai/dev/notes/vault-environment-files

# Vault environment-file guide

## 2026-09-15

Added [Environment files in Vault](/vault/environment-files/) for the SSH host setup work under [#247](https://github.com/dreamlake-ai/dreamlake-workspace/issues/247). The guide uses `dreamlake/envs/dev-env` and `dreamlake/envs/prod-env`, exact-string stdin upload, revision-checked replacement, and exclusive owner-only local restoration.

CLI 0.23.0 help and the Vault formatter confirm the command surface and raw string retrieval. No real environment files were read or uploaded. Whole-file storage does not imply remote environment delivery. Docs build and publication verification are recorded in the pull request.

---

Source: https://docs.dreamlake.ai/ml-dash/guides/logging

# Logging

Metric events, progress, and debugging information throughout your experiments. Logs are stored with timestamps, levels, and optional metadata.

## Basic Usage

```python

from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.log("Training started")
    exp.log("Model architecture: ResNet-50", level="info")
    exp.log("GPU memory low", level="warn")
    exp.log("Failed to load checkpoint", level="error")
```

## Log Levels

**Available levels:** `debug`, `info` (default), `warn`, `error`, `fatal`

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.log("Detailed debugging info", level="debug")
    exp.log("Training epoch 1", level="info")
    exp.log("Learning rate decreased", level="warn")
    exp.log("Gradient exploded", level="error")
    exp.log("Out of memory - aborting", level="fatal")
```

## Structured Metadata

Add context and metrics to your logs:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    # Log with metrics
    exp.log(
        "Epoch completed",
        level="info",
        metadata={
            "epoch": 5,
            "train_loss": 0.234,
            "val_loss": 0.456,
            "learning_rate": 0.001
        }
    )

    # Log with system info
    exp.log(
        "System status",
        level="info",
        metadata={
            "gpu_memory": "8GB",
            "cpu_percent": 45.2
        }
    )
```

## Common Patterns

**Training loop:**

```python

with Experiment(prefix="alice/ml/mnist-training").run as exp:
    exp.log("Starting training", level="info")

    for epoch in range(10):
        train_loss = train_one_epoch(model, train_loader)
        val_loss = validate(model, val_loader)

        exp.log(
            f"Epoch {epoch + 1} complete",
            level="info",
            metadata={
                "epoch": epoch + 1,
                "train_loss": train_loss,
                "val_loss": val_loss
            }
        )

    exp.log("Training complete", level="info")
```

**Error tracking:**

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:
    try:
        result = risky_operation()
        exp.log("Operation succeeded", level="info")
    except Exception as e:
        exp.log(
            f"Operation failed: {str(e)}",
            level="error",
            metadata={
                "error_type": type(e).__name__,
                "error_message": str(e)
            }
        )
        raise
```

**Progress tracking:**

```python

with Experiment(prefix="alice/etl/data-processing").run as exp:
    total = 10000
    exp.log(f"Processing {total} items", level="info")

    for i in range(total):
        process_item(i)

        if (i + 1) % (total // 10) == 0:
            percent = ((i + 1) / total) * 100
            exp.log(
                f"Progress: {percent:.0f}%",
                level="info",
                metadata={"processed": i + 1, "total": total}
            )

    exp.log("Processing complete", level="info")
```

## Storage Format

**Local mode** - Logs stored as JSONL (JSON Lines):

```bash
cat .dash/alice/project/my-experiment/logs/logs.jsonl
```

Each line is a JSON object. `metadata` is present only when you pass it:

```json
{"sequenceNumber": 0, "timestamp": "2025-10-29T10:30:00.000000Z", "level": "info", "message": "Training started"}
{"sequenceNumber": 1, "timestamp": "2025-10-29T10:30:05.000000Z", "level": "info", "message": "Epoch 1 complete", "metadata": {"train_loss": 0.5}}
```

**Remote mode** - Logs stored in MongoDB with automatic indexing on timestamp and level.

---

**Next:** Learn about [Parameters](/ml-dash/guides/parameters.md) to metric hyperparameters and configuration.

---

Source: https://docs.dreamlake.ai/dev/notes/comment-html-ids

# Comment IDs in HTML reads

## Unreleased — 2026-09-28

Comments were rendered as ordinary text in HTML snapshots, so an agent could target their paragraph but not the individual comment. Closed comment directives now render as atomic elements with `sN.cK` addresses sharing the section's reading-order counter. Saved references expose their persistent `data-comment-id`, and keyed drafts expose `data-comment-key`. Duplicate references retain one resource identity and have distinct target addresses.

No saved note content is rewritten and no comment body is fetched by static rendering. Code, links, escapes and malformed directives remain literal. Exact source range checks govern whether a comment is individually targetable.

Validation: all 146 HTML renderer tests and the renderer's targeted TypeScript check passed. Full server TypeScript is blocked locally by the existing missing `onnxruntime-node` dependency. A rendered browser fixture verified comment IDs and source ranges. Source docs and the Notes read action guide are synchronized into the public Notes skill.

---

Source: https://docs.dreamlake.ai/dev/notes/vault-writer-fleet

# Vault writer fleet audit

## 2026-09-15 — both Main writers use the reviewed epoch-aware source

The read-only audit of AWS account `747143892217`, region `us-east-1`, found one ECS cluster and 13 running service tasks. Staging Main revision172 and production Main revision122 both run `1058ef4e8aa57054ebeb86572cfaf7d8ff22f046`, with `DREAMLAKE_VAULT_KMS_MIGRATION_ENABLED=false`. Their actual container digests and the complete service/source inventory are in the [audit receipt](https://github.com/dreamlake-ai/dreamlake-workspace/blob/docs/241-vault-writer-fleet/design/reconciliation/241-vault-writer-fleet.json).

Vault entry writes, OTP/replay records, scoped-key writes, host credential operations and policy operations run in Main. Key GC, entry GC and password-rotation collection are embedded in that same process. Queue mount credentials use its Vault service. Private delivery/progress and run reconciliation also belong to Main; private runs are enabled in staging and disabled in production. These are not separate GC or queue deployments needing an independent image rollout.

The other 11 deployed services were traced to their exact image-tag commits and runtime build roots. Auth uses OAuth/account models; hub uses workspace/environment models; BSS uses File/Embedding; dashboard and its cleanup worker use Node/PhysicalFile/Experiment/track models; viz has no Vault database path; RTC uses document/journal/session models. Their Prisma schemas, raw command collection targets and runtime imports contain no identified Vault writer. A database setting alone was not used as proof of inclusion or exclusion.

Known retired staging171 has positive execution-stop evidence at 13:22:55.454 UTC. Archived production121 task `8c801bd0d2e147d5928c32e617557519` has Main STOPPED and execution-stop evidence at 13:53:47.280 UTC; its later absence from ECS history is not the basis of that conclusion. [Production rollout receipt](https://github.com/dreamlake-ai/dreamlake-workspace/pull/586#issuecomment-5681374346).

This covers the enumerated ECS fleet, not arbitrary database clients, manual processes, other regions or other accounts. Source classification does not assert that credentials technically prohibit arbitrary writes. Within the inspected fleet, only the two reviewed Main runtimes are identified Vault writers, and no additional process rollout is indicated. The operator must bind any migration approval to this actual hosted database and known writer inventory; unknown external access is not silently declared absent.

Migration remains disabled. The [proposed isolated staging procedure](https://github.com/dreamlake-ai/dreamlake-workspace/blob/docs/241-vault-writer-fleet/design/acceptance/vault-hosted-kms-plan.md) is review-only. No flag, key, grant, namespace, entry or deployment was changed by the audit.

The review candidate now includes a phased owned staging runner and a read-only flag planner. Reverse migration uses the already supported `managed` target with a distinct persisted ID; it restores the configured default key while retaining an explicit managed boundary and checkpoint metadata. Seven offline safety/orchestration tests passed. The new runner then passed its actual local HTTP/Mongo lifecycle with both enabled and disabled route registrations: forward and managed reverse, exact values/replay, scoped retirement, final disabled checks, and partial-baseline cleanup while disabled. The independently verified public npm CLI 0.21.2 binary and Python 0.17.0 wheel are bound by hash; installed SDK source bytes are checked against that wheel. These are local fixture and release checks, not hosted migration proof. See the [runner validation receipt](https://github.com/dreamlake-ai/dreamlake-workspace/blob/docs/241-vault-writer-fleet/design/reconciliation/241-hosted-kms-runner-validation.json).

---

Source: https://docs.dreamlake.ai/dev/notes/addressed-reads

# Addressed Notes reads

**Specification · addressed snapshot reads**

This page defines the read contract and its acceptance criteria. It is the design
reference; the [Notes guide](/notes/) and distributed agent skills describe how to
use it. Guides may use different explanations, but must preserve these semantics.

## The two read modes

| Request | Meaning | Result |
| --- | --- | --- |
| `read NOTE` | Observe current state | Complete source, content hash, write revision |
| `read NOTE --at REV` | Retrieve retained state | The same snapshot every time, while retained and accessible |
| `read NOTE --since HASH` | Compare prior content with current content | Unified line diff, base hash, result hash and revision |

`--toc`, `--section` and `--tag` select a snapshot view. They never change the
meaning of `--since`. `--linger` delivers an initial current snapshot and then
line diffs through its existing SSE transport.

## Actions the representation must support

| Assistant action | Required information |
| --- | --- |
| Orient within an article | Full heading outline with levels and source-derived section IDs |
| Read a section or subsection | Semantic nested section subtree, including child sections |
| Read one paragraph or heading | Exact element ID, source slice, global string and line ranges |
| Generate an edit | Original source spelling, code-point offsets and the original write revision |
| Verify an edit | Read the revision in the acknowledged write receipt |
| Continue during collaboration | Keep the draft baseline separate from newer streamed observations |

## Normative snapshot contract

There are two read modes. `read` returns the current snapshot; `--at REVISION`
returns the retained snapshot identified by that opaque revision. `--since HASH`
returns a unified line diff against the current source. A hash is a content
reference, not a write revision. Snapshot views do not change differential reads.
Explicit `--format inline-dff` remains available for character diffs; patch input
continues to default to `inline-dff`.

```bash
# NOTE_ID identifies a note you can read. Plain reads show hash and revision.
dreamlake notes read "$NOTE_ID"
dreamlake notes read "$NOTE_ID" --view html
# Copy REVISION from the read receipt; keep it with the draft it describes.
dreamlake notes read "$NOTE_ID" --at "$REVISION" --toc
dreamlake notes read "$NOTE_ID" --at "$REVISION" --section s1.1
dreamlake notes read "$NOTE_ID" --at "$REVISION" --tag s1.1.p1
# HASH is the content hash from that receipt. This returns line diffs.
dreamlake notes read "$NOTE_ID" --since "$HASH"
```

TOC, section and tag selectors return mapped HTML without needing `--view html`.
They are mutually exclusive and cannot combine with `--since`. `--tag` is an exact
generated element ID, not an arbitrary CSS selector. A paragraph ID selects one
paragraph; a section's slug ID selects the entire nested section. `--section`
accepts a numeric section index or its content-derived ID. `--at` cannot combine
with `--if-match`: the former retrieves history, the latter requires the current
revision to match. Missing snapshots or elements return 404. Every read, including
cached historical reads, rechecks current note permissions.

### Elements, identifiers and ranges

Snapshot HTML uses real nested `section` elements and `h1`–`h6` headings:

```html
<section id="section-plan" data-index="s1" data-char="0:90" data-lines="1:11">
  <h1 id="s1.h" data-index="s1" data-char="0:7" data-lines="1:1">Plan</h1>
  <p id="s1.p1" data-char="8:25" data-lines="3:3">We build robots.</p>
  <section id="section-training" data-index="s1.1" data-char="26:56" data-lines="5:8">
    <h2 id="s1.1.h" data-index="s1.1" data-char="26:38" data-lines="5:5">Training</h2>
    <p id="s1.1.p1" data-char="39:55" data-lines="7:7">Train 😀 safely.</p>
  </section>
</section>
```

This abbreviated example omits mapping spans and later section content. Source
ranges count Unicode code points, start at zero, and exclude the end. Line ranges
are one-based and include both endpoints. Ranges refer to original source,
including Markdown syntax and line terminators, never rendered text. Section
ranges include subsections. Heading ranges cover only the heading. Paragraphs
are numbered within their nearest section; lists, quotes, code and tables do not
advance the prose counter. Preamble paragraphs use `s0.pN`. Skipped heading levels
add a nesting level, without invented empty headings; sibling numbering remains
unique when heading levels change. IDs and ranges are local to one revision.

Section slugs follow the existing editor convention: NFC normalization, lowercase,
remove characters other than Unicode letters/numbers, whitespace, `_` and `-`,
then collapse whitespace to hyphens. Prefix with `section-`; an empty slug uses
`untitled`. Duplicate slugs get `-1`, `-2`, etc., in document order. No truncation
is applied. Reverse lookup uses the element's exact source range, not reversal of
the lossy slug. Headings use `sN.h`; paragraphs use `sN.pN`.

### List items and Markdown hints

List items use section-local IDs in document order: `s1.li1`, `s1.li2`,
and so on. Nested items get their own IDs; a parent item's range includes its
nested list. Ordered and task-list items use the same rule. Markers, indentation
and line endings belong to the original source range. Lists do not advance the
paragraph counter. Preamble items use `s0.liN`.

```html
<li id="s1.li1" data-char="11:29" data-lines="3:4">
  😀 One
  <ul><li id="s1.li2" data-char="20:29" data-lines="4:4">Two</li></ul>
</li>
```

Use `read NOTE --tag s1.li2` to select a single item. For Markdown notes,
`--view markdown` prints the original selected Markdown with generated address
comments before headings, paragraphs and list items. It uses the same validated
HTML snapshot and supports `--at`, `--toc`, `--section`, or `--tag`:

```bash
dreamlake notes read "$NOTE_ID" --at "$REVISION" --section s1 --view markdown
```

```markdown
<!-- s1.li1 chars=11:29 lines=3:4 -->
- 😀 One
<!-- s1.li2 chars=20:29 lines=4:4 -->
  - Two
```

This is a reading view, not canonical source. Its header identifies the revision
and hash; ranges always refer to original source, excluding generated hints.
Do not write the annotated output back as article content. Default source reads
stay exact and unannotated. `--since` and `--linger` retain their existing source
contracts; they cannot combine with the annotated view. HTML-source notes use
`--view html` instead.

### Scoped source and edit commands

A scoped root retains the whole document's `data-hash` and `data-revision`, and
adds `data-scope`, `data-source-start`, `data-source-end` and `data-source-hash`.
Its `data-source` contains only the selected source slice, not the entire note.
For a mapped element, subtract `data-source-start` when slicing this local source;
retain absolute offsets in edit commands. A TOC has empty root source, with exact
heading source attached to each heading's `data-source`. It does not imply the
assistant read omitted section bodies. Full HTML keeps the existing full-source
contract. The CLI checks the returned scope, revision and source hash before
printing. Never write the HTML or a partial source slice as the complete note.

For the fixture paragraph above, a directly generated patch is:

```text
@@ chars 39:55 @@
~ [-Train 😀 safely.\n-]{+Train safely and quickly.\n+}
```

```bash
# edit.dff contains the patch prepared against REVISION, with exact old text.
dreamlake notes patch "$NOTE_ID" --file edit.dff --base-revision "$REVISION" --exact
# Copy NEXT_REVISION from the write receipt; read that exact acknowledged state.
dreamlake notes read "$NOTE_ID" --at "$NEXT_REVISION" --tag s1.1.p1
```

Exact mode refuses concurrent changes with 412. Without `--exact`, the existing
native RTC merge mode uses the original baseline identities. A later read or
streamed revision must never silently replace the baseline of a prepared draft.

### Linger and presence

`--linger` retains its existing contract: an initial source snapshot, then
SSE-driven, debounced line diffs. It does not stream HTML or scoped fragments.
Read a focused view in a separate command using a revision emitted by linger:
`read NOTE --at REVISION --tag s1.1.p1`. Pinned reads do not overwrite the live
presence selection with historical offsets. Live scoped reads report their
actual range; a TOC reports no whole-document passage highlight. Selection events
carry their own content hash and must not be interpreted against a different
source. `--linger` rejects `--at`, `--toc`, `--tag`, sections and HTML before joining.

### Server retrieval

On the server, a pinned read performs permission checks and a direct retained
baseline lookup, without initializing or reading RTC and without uploading new
snapshots. Rendering shares a bounded content cache (16 entries, 8 MiB estimated
payload budget); a cold read still loads and parses the complete source once.
Current reads retain the existing coherent RTC observation and persistence path.
No claim of constant-time cold reads or eliminated live-read storage costs is made.

## Acceptance evidence

All tests below run against isolated fixtures. The HTTP harness launches the real
CLI and the real Fastify routes on localhost, with fixture storage and RTC
authority. It is not production or a live hosted RTC test.

| Requirement | Verified behavior |
| --- | --- |
| Efficient retrieval | Pinned read bypasses RTC initialization, RTC observation and snapshot uploads. Scope rendering shares a bounded cache. |
| Repeated reads are consistent | Outline and paragraph read at the same revision remain identical despite an intervening edit. Old snapshots remain readable after a later write. |
| Editing is direct | Paragraph offsets and exact source generate a patch accepted by the existing edit endpoint; unrelated source stays byte-for-byte unchanged. |
| Stale writes fail | Exact-mode edit against an intervening change returns 412, without applying the draft. |
| Read scopes are clear | Whole article, TOC, nested section and one paragraph are separately verified; scoped reads do not include unrelated paragraph source. |
| Linger remains compatible | Real CLI receives snapshot B and line diff B→C; `--at B --tag …` still returns B. SIGINT sends leave. |
| Authorization persists | Revoked note access prevents historical retrieval, even with a valid retained token. |
| Offset integrity | Emoji, CRLF, formatting, skipped heading levels, duplicate titles and repeated projections are tested. |

### Measured example

A local fixture containing 100 sections and 400 paragraphs produced these results:

| View | Response size | Local rendering time |
| --- | --- | --- |
| Entire article | 586 KB | 39 ms, cold |
| TOC | 35.6 KB | 1.8 ms, warm median |
| One section | 6.9 KB | 1.8 ms, warm median |
| One paragraph | 2.4 KB | 1.7 ms, warm median |

Source size: 237 KB. Warm measurements use 20 iterations. Timings exclude network,
permission checks, and object-storage latency; they are not a service SLA.
A cold read still loads and parses the complete source. Current reads retain the
existing RTC observation and persistence cost. Historical reads load and validate
a retained baseline by direct object key, without listing history.

### Reproduce

From a workspace checkout containing `dreamlake-server`, set `CLI_SOURCE` to the
companion CLI checkout and `ARTIFACTS` to an output directory:

```bash
NOTES_SCOPED_CLI="$CLI_SOURCE" NOTES_READ_ARTIFACTS="$ARTIFACTS" \
  pnpm -C dreamlake-server exec vitest run --project unit \
  src/services/notesV2Routes.test.ts src/services/notesReadBaseline.test.ts src/lib/noteHtml
pnpm -C dreamlake-server exec tsx scripts/benchmark-notes-read.ts "$ARTIFACTS"
```

The harness emits article, outline, section and paragraph HTML; the generated
patch; the write receipt and exact readback; the linger event stream; and a JSON
report. The benchmark emits `benchmark.json`. No real notes are modified.

---

Source: https://docs.dreamlake.ai/dev/notes/url-layout

# Shareable view layouts — 2026-10-01

Status: [app PR #656](https://github.com/dreamlake-ai/dreamlake-ai/pull/656) merged at `2a5135ef`; production published and signed-in live restoration verified. The app owns the
bounded panel/state codec and idle writer. UIKit keeps interaction mechanics;
no frame protocol, CLI command or artifact author API changes are introduced.
The authoritative user behavior is [Panels and agent control](/notes/panels.md).
The downloadable full docs bundle is regenerated from these source pages.
The focused public Notes/CLI skills have no new task procedure: their existing
panel-documentation link stays authoritative, so no generated core skill content
needs a parallel manual edit.

Capture declared primitive display state only: sidebar collapse/folds, note
outline/preview toggles, list query/filter/order, folder multi-selection/anchor,
search reveal, and scroll positions. The path/query already owns folder/project
location and route selection. Artifact query/fragment is retained verbatim after
normalization; arbitrary iframe memory is outside the current author contract.
Transient menus, unsaved editor text, credentials, RTC state and grants are not
view layout data.

Version 6 carries the compact tree plus sorted state entries. It uses the accepted
common-span mini-LZ encoder, bounded to a 4096-character search window and 64
candidates. Plain/compressed selection compares escaped URL length. IDs are exact;
only the route's primary identity is implicit. Read compatibility remains for
version 5, DEFLATE and prototype links. Decoding is bounded to 200 tree nodes,
depth 20, 256 state entries, 200 primitives per entry, 2048 characters per string,
64,000 decoded characters and 32,000 escaped layout characters.

Runtime: mark dirty → coalesce 250 ms → request idle time with a 1000 ms deadline
(or timer fallback) → read latest tree/state → encode → replace history. Cancel
superseded work and teardown, and guard route changes. Scroll data lives in refs.
Restore display preferences after durable-preference effects without saving the
recipient's URL seed into their persistent preferences. Restore scroll as content
arrives, yielding to user input. The app's replaceRoot adapter suppresses UIKit's
first-leaf focus while replacing a tree, preserving a visible focused tab or
adopting the incoming active tab. Title updates must not change the active note.

Auxiliary note metadata probes run at most four concurrently; body URLs are not
prefetched. 403/404 leaves empty regions or removes unavailable tabs. Primary
access and artifact loaders keep their existing authorization paths. Transient
errors stay with normal loader retry.

Validation: codec state and exact-ID round trips, malformed/oversized input,
legacy formats, burst/idle/cancellation tests, full unit suite, typecheck and SSR
build; browser checks cover split widths/reload, missing auxiliary notes, native
tab selection/reload, sidebar overrides, list query/order reload, and delayed-content reading position.
Typecheck and production/SSR build passed, as did 344 test files and 3,533 unit
tests (7 skipped), plus six browser tests against the built bundle. CI was
requested with `ci:full` and runs in the background; results are unverified.
Netlify deploy `6abebe2d171ea20008cebc98` published that exact app commit.
Signed-in UI build `2a5135e` restored the report and guide at 35/65 width;
version 6 reload retained the collapsed sidebar and both 60 px reading positions.
A separate list+note view retained search `auto`, order `oldest` and the primary
note after reload. Missing auxiliary fallback remains mocked-browser evidence.
Docs PR #871 published v0.1.53; live Markdown, illustration bytes and the complete
downloadable docs skill bundle were verified. The lab report has five verified
version milestones ending in `codec-v2-production-verified`.

[Experiment lab report](https://dreamlake.ai/geyang/notes/6abe080eca8cbe9312244338)
retains figures, separate corpus measurements and frequently tagged milestones.

Duplicate instances of the same note currently share their reading/toggle state
key. The 32K application cutoff is not a universal proxy/browser URL guarantee.
Unsupported or oversized automatic updates retain the last usable URL.

---

Source: https://docs.dreamlake.ai/ml-dash/guides/files

# Folder (Files)

Upload and manage experiment artifacts - models, plots, configs, and results. Files are automatically checksummed and organized with metadata.

## Fluent Interface Overview

The folder API uses a fluent interface that supports multiple styles:

```python

from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Upload file from disk
    exp.files("checkpoints").upload("./model.pt")
    exp.files("checkpoints").upload("./model.pt", to="checkpoint.pt")

    # Save objects as files
    exp.files("models").save_torch(model, to="model.pt")
    exp.files("configs").save_json(config, to="config.json")

    # List files in a location
    files = exp.files("/models").list()

    # Download a file
    exp.files("some.text").download()
    exp.files("some.text").download(to="./local_copy.text")

    # Download using glob patterns
    file_paths = exp.files("images").list("*.png")
    exp.files("images").download("*.png", to="local_images")

    # Delete files
    exp.files("some.text").delete()
    exp.files.delete("some.text")
    exp.files.delete("images/*.png")

    # Specific file types
    exp.files.save_text("content", to="view.yaml")
    exp.files.save_json(dict(hey="yo"), to="config.json")
    exp.files.save_blob(b"xxx", to="data.bin")
```

## Basic Upload

### Upload Existing File

```python

from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Upload a file to a prefix
    result = exp.files("models").upload("./model.pth")
    print(result)  # {'id': 'pending', 'status': 'queued'}
```

Uploads are [buffered](/ml-dash/guides/buffering.md) by default, so `upload()` and the
`save*()` methods return `{"id": "pending", "status": "queued"}` and write the
file in the background. The file can't be listed or downloaded until the buffer
flushes (at the latest when the `with` block exits). To get the stored record
(`filename`, `sizeBytes`, `checksum`, `id`, ...) back from the call itself,
set `ML_DASH_BUFFER_ENABLED=false` before creating the experiment, or read it
later with `exp.files("models").list()`.

### Save Objects as Files

Save Python objects directly without creating intermediate files:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Save dict/list as JSON
    config = {"model": "resnet50", "lr": 0.001}
    exp.files("configs").save_json(config, to="config.json")

    # Save bytes directly
    exp.files("data").save_blob(b"binary data", to="data.bin")

    # Save PyTorch model
    import torch
    model = torch.nn.Linear(10, 5)
    exp.files("checkpoints").save_torch(model, to="checkpoint.pt")
    exp.files("checkpoints").save_torch(model.state_dict(), to="weights.pt")
```

### Direct Method Style

You can also use the direct method style without specifying a prefix:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Upload file directly
    exp.files.upload("./model.pt", to="models/model.pt")

    # Save objects directly
    exp.files.save_text("yaml content", to="configs/view.yaml")
    exp.files.save_json({"key": "value"}, to="data/config.json")
    exp.files.save_blob(b"\x00\x01\x02", to="binary/data.bin")
```

## Organizing Files

Use paths to organize files logically:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Models
    exp.files("models").upload("model.pth")
    exp.files("models/checkpoints").upload("best_model.pth")

    # Visualizations
    exp.files("visualizations").upload("loss_curve.png")

    # Configuration
    exp.files("config").save_json(config, to="config.json")

    # Results
    exp.files("results").upload("results.csv")
```

## Listing Files

### List All Files

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # List all files
    files = exp.files().list()

    for file_info in files:
        print(f"File: {file_info['filename']}")
        print(f"  Path: {file_info['path']}")
        print(f"  Size: {file_info['sizeBytes']} bytes")
        print(f"  ID: {file_info['id']}")
```

### List by Prefix

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # List files in specific prefix
    model_files = exp.files("/models").list()
    config_files = exp.files("/configs").list()
```

### List with Glob Pattern

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # List files matching pattern
    png_files = exp.files("images").list("*.png")
    model_files = exp.files().list("*.pt")
    all_configs = exp.files().list("**/*.json")
```

## Downloading Files

### Download Single File

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Download by filename/path
    exp.files("model.pt").download()  # Downloads to current directory
    exp.files("model.pt").download(to="./local_model.pt")  # Custom destination

    # Download from specific prefix
    exp.files("models/best.pt").download(to="./best_model.pt")
```

### Download with Glob Pattern

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Download all PNG files from images prefix
    paths = exp.files("images").download("*.png", to="./local_images")

    # Direct style with path/pattern
    paths = exp.files.download("images/*.png", to="local_images")

    print(f"Downloaded {len(paths)} files")
```

### Download by File ID (Legacy)

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Look up the ID of a file uploaded in an earlier run
    file_id = exp.files("models").list()[0]["id"]

    # Download by ID
    downloaded_path = exp.files(file_id=file_id).download()
    print(f"Downloaded to: {downloaded_path}")
```

### Checksum Verification

Downloads automatically verify checksums to ensure file integrity. Download
from a later run, after the upload has been flushed:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # The stored SHA-256 checksum
    print(exp.files("models").list()[0]["checksum"])

    # Download (checksum verified automatically)
    downloaded = exp.files("model.pth").download(to="./verified_model.pth")
    print(f"Download verified and saved to: {downloaded}")
```

## Deleting Files

### Delete Single File

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Delete by filename/path
    result = exp.files("some.text").delete()

    # Direct style
    result = exp.files.delete("some.text")
```

### Delete with Glob Pattern

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Delete all PNG files from images prefix
    results = exp.files("images").delete("*.png")

    # Direct style
    results = exp.files.delete("images/*.png")

    print(f"Deleted {len(results)} files")
```

## File Metadata

Add description, tags, and custom metadata:

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    result = exp.files("models",
        description="Best model from epoch 50",
        tags=["checkpoint", "best"],
        metadata={"epoch": 50, "val_accuracy": 0.95, "optimizer_state": True},
    ).save_torch(model, to="best_model.pth")
```

## Saving Specific File Types

### Save Text

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Save text content
    yaml_content = """
    model:
      architecture: resnet50
      pretrained: true
    """
    exp.files("configs").save_text(yaml_content, to="model.yaml")

    # Or using direct style
    exp.files.save_text(yaml_content, to="configs/model.yaml")
```

### Save JSON

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    config = {"model": "resnet50", "lr": 0.001}

    # Save JSON
    exp.files("configs").save_json(config, to="config.json")

    # Or direct style
    exp.files.save_json(config, to="configs/training.json")
```

### Save Binary Data

```python

with Experiment(prefix="alice/project/my-experiment").run as exp:

    binary_data = b"\x00\x01\x02\x03"

    # Save blob
    exp.files("data").save_blob(binary_data, to="weights.bin")

    # Or direct style
    exp.files.save_blob(binary_data, to="data/embeddings.bin")
```

## Training with Checkpoints

Save models during training:

```python

import torch
from ml_dash import Experiment

with Experiment(prefix="alice/cv/resnet-training").run as exp:

    exp.params.set(model="resnet50", epochs=100)
    exp.log("Starting training")

    best_accuracy = 0.0

    for epoch in range(100):
        train_loss = train_one_epoch(model, train_loader)
        val_loss, val_accuracy = validate(model, val_loader)

        # Log metrics (single call with nested dict)
        exp.metrics.log(
            epoch=epoch,
            train=dict(loss=train_loss, accuracy=val_accuracy),
            eval=dict(loss=val_loss, accuracy=val_accuracy)
        )

        # Alternative: prefix-based logging
        # exp.metrics("train").log(loss=train_loss, accuracy=val_accuracy, epoch=epoch)
        # exp.metrics("eval").log(loss=val_loss, accuracy=val_accuracy, epoch=epoch)

        # Save checkpoint every 10 epochs
        if (epoch + 1) % 10 == 0:
            exp.files("checkpoints",
                tags=["checkpoint"],
                metadata={"epoch": epoch + 1, "val_accuracy": val_accuracy},
            ).save_torch(model.state_dict(), to=f"checkpoint_epoch_{epoch + 1}.pt")

        # Save best model
        if val_accuracy > best_accuracy:
            best_accuracy = val_accuracy

            exp.files("models",
                description=f"Best model (accuracy: {best_accuracy:.4f})",
                tags=["best"],
                metadata={"epoch": epoch + 1, "accuracy": best_accuracy},
            ).save_torch(model.state_dict(), to="best_model.pt")

            exp.log(f"New best model saved (accuracy: {best_accuracy:.4f})")

    exp.log("Training complete")
```

## Saving Visualizations

Upload matplotlib plots using the convenient `save_fig()` method:

```python

import matplotlib.pyplot as plt
import numpy as np
from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Generate plot
    losses = [0.5, 0.4, 0.3, 0.25, 0.2]
    plt.plot(losses)
    plt.title("Training Loss")
    plt.xlabel("Epoch")
    plt.ylabel("Loss")

    # Save directly (auto-closes figure)
    exp.files("visualizations").save_fig(to="loss_curve.png")

    # Save as PDF with custom DPI
    xs = np.linspace(-5, 5, 100)
    plt.plot(xs, np.cos(xs), label='Cosine')
    plt.legend()
    exp.files("visualizations").save_fig(
        to="cosine_function.pdf",
        dpi=150,
        transparent=True,
        bbox_inches='tight'
    )
```

**Note:** `save_fig()` automatically closes the figure after saving to prevent memory leaks.

## Saving Videos

Upload video frame stacks using the `save_video()` method. This is useful for saving training visualizations, agent rollouts, or any sequence of images.

`save_video()` needs the video extra, which installs imageio and ffmpeg:

```bash
pip install "ml-dash[video]"
```

```python

import numpy as np
from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:

    # Generate frame stack
    frames = [np.random.rand(200, 200) for _ in range(20)]

    # Save as MP4 (default 20 FPS)
    exp.files("videos").save_video(frames, to="animation.mp4")

    # Save with custom FPS
    exp.files("videos").save_video(frames, to="animation.mp4", fps=30)

    # Save as GIF
    exp.files("videos").save_video(frames, to="animation.gif")
```

### Practical Example: Agent Rollout

Record an agent's trajectory or any animated visualization:

```python

import numpy as np
from ml_dash import Experiment

def render_frame(x, y):
    """Render a frame with a marker at position (x, y)."""
    canvas = np.zeros((200, 200))
    # Draw a 10x10 square at position
    canvas[max(0, x-5):x+5, max(0, y-5):y+5] = 1.0
    return canvas

with Experiment(prefix="alice/rl/agent-rollout").run as exp:

    # Simulate agent moving across the canvas
    frames = [render_frame(100 + i, 80) for i in range(20)]

    exp.files("videos").save_video(frames, to="rollout.mp4")
```

### Video Encoding Options

Control video quality and encoding with additional parameters:

```python

# High quality MP4
exp.files("videos").save_video(frames, to="high_quality.mp4", fps=30, quality=8)

# Lower quality for smaller file size
exp.files("videos").save_video(frames, to="compressed.mp4", fps=30, quality=5)
```

Additional keyword arguments are passed to imageio's writer (e.g., `quality`, `codec`, `bitrate`).

### Frame Format Support

`save_video()` automatically handles various frame formats:

```python

# Grayscale frames (H×W)
frames = [np.random.rand(480, 640) for _ in range(30)]
exp.files("videos").save_video(frames, to="grayscale.mp4")

# RGB frames (H×W×3)
frames = [np.random.rand(480, 640, 3) for _ in range(30)]
exp.files("videos").save_video(frames, to="rgb.mp4")

# Stacked array (N×H×W or N×H×W×C)
frames = np.random.rand(30, 480, 640, 3)
exp.files("videos").save_video(frames, to="stacked.mp4")
```

**Frame value ranges:**
- Float values (0.0 to 1.0) - automatically scaled to 0-255
- Uint8 values (0 to 255) - used directly
- Float32 values - automatically converted

**Note:** An empty frame list raises `ValueError: frame_stack is empty`.

## Storage Format

**Local mode** - Files stored with prefix-based organization:

```
.dash/
└── alice/                              # owner
    └── project/                        # project
        └── my-experiment/              # experiment name
            └── files/
                ├── models/
                │   ├── 7218065541365719/
                │   │   └── model.pth
                │   └── 7218065541366823/
                │       └── best_model.pth
                ├── visualizations/
                │   └── 7218065541367921/
                │       └── loss_curve.png
                └── config/
                    └── 7218065541368015/
                        └── config.json
```

Each file is stored as: `files/{prefix}/{snowflake_id}/{filename}`
- **prefix**: Logical organization path (e.g., "models", "configs", "visualizations")
- **snowflake_id**: Unique identifier generated for each file
- **filename**: Original filename

**Remote mode** - Files uploaded to S3, metadata in MongoDB:
- Files stored: `s3://bucket/files/{namespace}/{project}/{experiment}/{prefix}/{file_id}/filename`
- Metadata: path, size, SHA256 checksum, tags, description

**File size limit:** the ML-Dash server accepts up to 256MB per file and
rejects larger uploads with `413 Payload Too Large`. The SDK itself refuses
files over 100GB, which is the only limit in local mode.

---

**That's it!** You've completed all the core ML-Dash tutorials. Check out the API Reference for detailed method documentation.

---

Source: https://docs.dreamlake.ai/ml-dash/guides/images

# Image Saving

ML-Dash provides direct support for saving numpy arrays as images in PNG and JPEG formats.

## Overview

The `save_image()` method allows you to save numpy arrays directly without manually converting to image formats. This is perfect for:
- **MuJoCo/PyBullet**: Rendering frames from physics simulations
- **Computer Vision**: Saving model predictions, visualizations
- **Reinforcement Learning**: Saving agent observations
- **Any Numpy Arrays**: Camera feeds, generated images, etc.

## Basic Usage

```python
import numpy as np
from ml_dash import Experiment

with Experiment("vision/training").run as experiment:
    # Get or create a numpy array
    pixels = renderer.render()  # From MuJoCo, OpenCV, etc.

    # Save as PNG (lossless)
    experiment.files("frames").save_image(pixels, to="frame_001.png")

    # Save as JPEG (lossy, smaller files)
    experiment.files("frames").save_image(pixels, to="frame_001.jpg")
```

## Auto-Detection

The `save()` method automatically detects numpy arrays:

```python
# These are equivalent:
experiment.files("images").save(pixels, to="frame.png")
experiment.files("images").save_image(pixels, to="frame.png")
```

## Supported Array Types

### 1. uint8 Arrays (Most Common)

```python
# RGB image (H x W x 3)
pixels_rgb = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
experiment.files("images").save_image(pixels_rgb, to="rgb.png")

# Grayscale image (H x W)
pixels_gray = np.random.randint(0, 255, (480, 640), dtype=np.uint8)
experiment.files("images").save_image(pixels_gray, to="gray.png")

# RGBA image with transparency (H x W x 4)
pixels_rgba = np.random.randint(0, 255, (480, 640, 4), dtype=np.uint8)
experiment.files("images").save_image(pixels_rgba, to="rgba.png")
```

### 2. Normalized Float Arrays (0.0 to 1.0)

```python
# Normalized RGB (automatically converted to uint8)
pixels_float = np.random.rand(480, 640, 3)
experiment.files("images").save_image(pixels_float, to="normalized.png")
# Automatically: pixels_float * 255 -> uint8
```

### 3. Arbitrary Range Float Arrays

```python
# Any range - automatically normalized
pixels_arbitrary = np.random.rand(480, 640, 3) * 1000
experiment.files("images").save_image(pixels_arbitrary, to="scaled.png")
# Automatically: (value - min) / (max - min) * 255 -> uint8
```

## Format Support

### PNG (Lossless, Larger Files)

```python
# Supports transparency
experiment.files("images").save_image(rgba_array, to="transparent.png")

# Best for:
# - Screenshots
# - UI elements
# - Exact reproduction needed
# - Images with text/sharp edges
```

### JPEG (Lossy, Smaller Files)

```python
# Default quality (95) - high quality
experiment.files("photos").save_image(pixels, to="photo.jpg")

# Custom quality (1-100)
experiment.files("photos").save_image(pixels, to="low.jpg", quality=60)
experiment.files("photos").save_image(pixels, to="high.jpg", quality=98)

# Both .jpg and .jpeg extensions work
experiment.files("images").save_image(pixels, to="image.jpeg", quality=90)

# Best for:
# - Photos/renders from simulations
# - Large image sequences
# - When file size matters
# - Natural scenes
```

**JPEG Important Notes:**
- Automatically converts RGBA to RGB (alpha channel removed)
- Uses white background when converting transparent images
- Applies optimization for better compression

## Quality Parameter

Control JPEG compression quality (default: 95):

```python
# Maximum quality (largest file)
experiment.files("frames").save_image(pixels, to="frame.jpg", quality=100)

# High quality (default)
experiment.files("frames").save_image(pixels, to="frame.jpg", quality=95)

# Good quality (balanced)
experiment.files("frames").save_image(pixels, to="frame.jpg", quality=85)

# Lower quality (smaller file)
experiment.files("frames").save_image(pixels, to="frame.jpg", quality=70)

# Low quality (very small file)
experiment.files("frames").save_image(pixels, to="frame.jpg", quality=50)
```

**Quality Guidelines:**
- **95-100**: Nearly lossless, large files
- **85-90**: Great for most use cases, good balance
- **70-80**: Visible compression, smaller files
- **50-60**: Noticeable artifacts, very small files
- **Below 50**: Poor quality, not recommended

## MuJoCo Example

```python
import mujoco
import numpy as np
from ml_dash import Experiment

with Experiment("robotics/mujoco-renders").run as experiment:
    model = mujoco.MjModel.from_xml_string(xml_content)
    data = mujoco.MjData(model)
    renderer = mujoco.Renderer(model, height=480, width=640)

    for i in range(1000):
        # Simulate
        mujoco.mj_step(model, data)

        if i % 10 == 0:
            # Render frame
            renderer.update_scene(data)
            pixels = renderer.render()  # numpy array (480, 640, 3)

            # Save as JPEG with good compression
            experiment.files("robot/frames").save_image(
                pixels,
                to=f"frame_{i:05d}.jpg",
                quality=85
            )
```

## OpenCV Example

```python
import cv2
from ml_dash import Experiment

with Experiment("vision/camera-feed").run as experiment:
    cap = cv2.VideoCapture(0)

    for i in range(100):
        ret, frame = cap.read()  # numpy array

        if ret:
            # OpenCV uses BGR, convert to RGB
            frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)

            # Save frame
            experiment.files("camera/frames").save_image(
                frame_rgb,
                to=f"frame_{i:04d}.png"
            )

    cap.release()
```

## PIL/Pillow Integration

```python
from PIL import Image
import numpy as np
from ml_dash import Experiment

with Experiment("vision/processing").run as experiment:
    # Load image with PIL
    img = Image.open("input.jpg")

    # Convert to numpy
    img_array = np.array(img)

    # Process...
    processed = some_processing(img_array)

    # Save result
    experiment.files("processed").save_image(
        processed,
        to="output.png"
    )
```

## Saving Image Sequences

```python
with Experiment("video/frames").run as experiment:
    for frame_idx, frame in enumerate(video_frames):
        # Use zero-padded indexing for proper sorting
        experiment.files("video").save_image(
            frame,
            to=f"frame_{frame_idx:05d}.png"
        )
        # Creates: frame_00000.png, frame_00001.png, ...
```

## Buffering and Performance

Image saves are automatically buffered:

```python
with Experiment("high-freq/frames").run as experiment:
    # All saves are non-blocking!
    for i in range(1000):
        experiment.files("frames").save_image(
            frame,
            to=f"frame_{i:05d}.jpg",
            quality=85
        )
        # Returns immediately, queued for background upload

    # All frames uploaded when context exits
```

## Aligning with Tracks

Use consistent step indices:

```python
with Experiment("robotics/tracking").run as experiment:
    for step in range(1000):
        # Save frame with step index
        experiment.files("frames").save_image(
            pixels,
            to=f"frame_{step:05d}.jpg"
        )

        # Save track with same step index
        experiment.tracks("robot/position").append(
            step=step,
            x=x,
            y=y,
            z=z
        )

        # Now frames and tracks are aligned!
```

## Different Paths

Organize images in different directories:

```python
with Experiment("training/run1").run as experiment:
    # Raw frames
    experiment.files("frames/raw").save_image(raw_frame, to="frame.png")

    # Processed frames
    experiment.files("frames/processed").save_image(processed, to="frame.png")

    # Visualizations
    experiment.files("viz/predictions").save_image(pred_vis, to="pred.jpg")

    # Debug images
    experiment.files("debug/attention").save_image(attn_map, to="attn.png")
```

## Error Handling

```python
try:
    experiment.files("images").save_image(pixels, to="frame.png")
except ImportError:
    # PIL/Pillow not installed
    print("Please install Pillow: pip install Pillow")
except ValueError as e:
    # Invalid parameters
    print(f"Error: {e}")
```

## Format Comparison

| Aspect | PNG | JPEG |
|--------|-----|------|
| Compression | Lossless | Lossy |
| File Size | Larger | Smaller |
| Transparency | ✓ Yes | ✗ No |
| Quality | Perfect | Configurable |
| Best For | Graphics, text | Photos, renders |
| Speed | Slower | Faster |

## Best Practices

### 1. Choose Format Based on Content

```python
# PNG for graphics/UI
experiment.files("ui").save_image(ui_screenshot, to="screenshot.png")

# JPEG for photos/renders
experiment.files("renders").save_image(render, to="render.jpg", quality=85)
```

### 2. Use Quality 85 for Balanced JPEG

```python
# Good balance of quality and file size
experiment.files("frames").save_image(
    frame,
    to="frame.jpg",
    quality=85  # Recommended for most cases
)
```

### 3. Zero-Pad Frame Numbers

```python
# Good: Proper sorting
for i in range(1000):
    experiment.files("frames").save_image(
        frame,
        to=f"frame_{i:05d}.jpg"
    )
    # frame_00000.jpg, frame_00001.jpg, ...

# Bad: Wrong sorting
for i in range(1000):
    experiment.files("frames").save_image(
        frame,
        to=f"frame_{i}.jpg"
    )
    # frame_1.jpg, frame_10.jpg, frame_2.jpg (wrong order!)
```

### 4. Consistent File Extensions

```python
# Good: All same format
for i in range(100):
    experiment.files("frames").save_image(frame, to=f"frame_{i:05d}.jpg")

# Confusing: Mixed formats
experiment.files("frames").save_image(frame1, to="frame_1.jpg")
experiment.files("frames").save_image(frame2, to="frame_2.png")
```

### 5. Include Frame Info in Metadata

```python
experiment.files("frames",
    description="Training visualization frames",
    tags=["visualization", "epoch_10"]
).save_image(frame, to="frame.jpg")
```

## Requirements

Image saving needs Pillow and NumPy. Neither is installed with `ml-dash`:

```bash
pip install Pillow numpy
```

## API Reference

### `save_image(array, *, to, quality=95)`

Save numpy array as an image file.

**Parameters:**
- `array` (numpy.ndarray): Image array (HxW or HxWxC)
- `to` (str): Target filename with extension (.png, .jpg, .jpeg)
- `quality` (int, optional): JPEG quality 1-100 (default: 95)

**Returns:**
- Dict with file metadata (or `{"status": "queued"}` if buffered)

**Raises:**
- `ImportError`: If Pillow not installed
- `ValueError`: If `to` parameter missing or invalid array

**Examples:**

```python
# PNG
experiment.files("images").save_image(pixels, to="image.png")

# JPEG with quality
experiment.files("images").save_image(pixels, to="image.jpg", quality=85)

# With path
experiment.files("data/visualizations").save_image(
    vis_array,
    to="prediction.png"
)
```

## Complete Example

```python
import mujoco
import numpy as np
from ml_dash import Experiment

with Experiment(
    prefix="robotics/complete-demo",
    tags=["mujoco", "images", "tracks"],
    dash_url="http://localhost:3000"
).run as experiment:
    experiment.log("Starting robot simulation with image tracking")

    # Setup MuJoCo
    model = mujoco.MjModel.from_xml_string(xml_content)
    data = mujoco.MjData(model)
    renderer = mujoco.Renderer(model, height=480, width=640)

    steps = 400
    record_interval = 4

    for i in range(steps):
        # Control
        data.ctrl[0] = 4.0 * np.sin(i * 0.03)
        data.ctrl[1] = 2.5 * np.sin(i * 0.05)

        # Simulate
        mujoco.mj_step(model, data)

        # Record
        if i % record_interval == 0:
            # Render
            renderer.update_scene(data)
            pixels = renderer.render()  # numpy array

            # Save image (JPEG for smaller size)
            experiment.files("robot/frames").save_image(
                pixels,
                to=f"frame_{i:05d}.jpg",
                quality=85
            )

            # Track position (aligned with frame)
            ee_pos = data.site_xpos[model.site('end_effector').id].copy()
            experiment.tracks("robot/position").append(
                step=i,
                frame=f"frame_{i:05d}.jpg",  # Reference frame
                x=float(ee_pos[0]),
                y=float(ee_pos[1]),
                z=float(ee_pos[2])
            )

            experiment.log(f"Recorded frame_{i:05d}.jpg")

    experiment.log("Simulation complete!")
```

This creates a complete dataset with rendered frames and aligned position tracking!

---

Source: https://docs.dreamlake.ai/ml-dash/guides/tracks

# Track API

The Track API provides efficient time-series data tracking for robotics, reinforcement learning, and any sequential experiments.

## Overview

Tracks are perfect for:
- **Robotics**: Robot positions, joint angles, sensor readings
- **Reinforcement Learning**: Agent trajectories, rewards, states
- **Simulations**: Physics parameters over time
- **Sequential Data**: Any data that changes over time

## Basic Usage

```python
from ml_dash import Experiment

with Experiment("robotics/training").run as experiment:
    for step in range(1000):
        # Append data to a track
        experiment.tracks("robot/position").append(
            step=step,
            x=position[0],
            y=position[1],
            z=position[2]
        )
```

## Timestamp-Based Tracking

Tracks support three timestamp modes:

### 1. Auto-Generated Timestamps (Recommended)

When `_ts` is not provided, timestamps are automatically generated:

```python
with Experiment("my-project/exp").run as experiment:
    for i in range(100):
        # Auto-generate unique timestamps
        experiment.tracks("sensors/temperature").append(value=temperature)
        experiment.tracks("sensors/pressure").append(value=pressure)
```

### 2. Explicit Timestamps

Provide explicit timestamps when you need precise control:

```python
import time

with Experiment("my-project/exp").run as experiment:
    for i in range(100):
        timestamp = time.time()

        # Track with explicit timestamp
        experiment.tracks("sensors/temperature").append(value=temperature, _ts=timestamp)

        # Track with same timestamp (entries are merged)
        experiment.tracks("sensors/pressure").append(value=pressure, _ts=timestamp)
```

### 3. Timestamp Inheritance with `_ts=-1`

Use `_ts=-1` to inherit the last timestamp from the previous `tracks.append()` or `metrics.log()` call in the same thread. This is perfect for synchronizing multi-modal data:

```python
with Experiment("robotics/multi-modal").run as experiment:
    for step in range(1000):
        # First append - auto-generates timestamp
        experiment.tracks("robot/pose").append(position=[1.0, 2.0, 3.0])

        # Following appends - inherit the same timestamp
        experiment.tracks("camera/left").append(width=640, height=480, _ts=-1)
        experiment.tracks("camera/right").append(width=640, height=480, _ts=-1)
        experiment.tracks("robot/velocity").append(linear=[0.1, 0.0, 0.0], _ts=-1)
        experiment.tracks("sensors/lidar").append(ranges=[1.5, 2.0, 2.5], _ts=-1)

        # All 5 tracks now share the exact same timestamp!
```

`_ts=-1` also inherits across **metrics and tracks** — they share the same last timestamp per thread:

```python
# Set timestamp via track, inherit in metric
experiment.tracks("robot/pose").append(position=[1.0, 2.0, 3.0], _ts=100.0)
experiment.metrics("train").log(loss=0.5, _ts=-1)   # inherits 100.0

# Set timestamp via metric, inherit in track
experiment.metrics("train").log(loss=0.5)            # auto _ts, sets _last_timestamp
experiment.tracks("robot/pose").append(x=1.0, _ts=-1)  # inherits it
```

**Benefits of `_ts=-1`:**
- Cleaner code - no need to manually pass timestamps around
- Less error-prone - can't accidentally use wrong timestamp
- Perfect for robotics/ML multi-modal data (poses, images, sensors at same instant)
- Works across ALL tracks and metrics globally (per thread)

## Multiple Tracks

Track different aspects of your experiment:

```python
with Experiment("robotics/walker").run as experiment:
    for step in range(1000):
        # Robot position
        experiment.tracks("robot/position").append(
            step=step,
            x=pos[0],
            y=pos[1],
            z=pos[2]
        )

        # Joint angles
        experiment.tracks("robot/joints").append(
            step=step,
            joint1=angles[0],
            joint2=angles[1],
            joint3=angles[2]
        )

        # Control signals
        experiment.tracks("robot/control").append(
            step=step,
            motor1=ctrl[0],
            motor2=ctrl[1]
        )

        # Sensor readings
        experiment.tracks("robot/sensors").append(
            step=step,
            imu_x=imu[0],
            imu_y=imu[1],
            imu_z=imu[2],
            force=force_sensor
        )
```

## Numpy Array Serialization

Tracks automatically serialize numpy arrays:

```python
import numpy as np

with Experiment("rl/training").run as experiment:
    for episode in range(100):
        state = env.reset()  # numpy array

        # Numpy arrays are automatically converted to lists
        experiment.tracks("agent/states").append(
            episode=episode,
            state=state,  # numpy array - auto-serialized!
            reward=0.0
        )
```

## MuJoCo Example

Perfect for tracking robot simulations:

```python
import mujoco
import numpy as np

with Experiment("robotics/mujoco-sim").run as experiment:
    model = mujoco.MjModel.from_xml_string(xml_content)
    data = mujoco.MjData(model)
    renderer = mujoco.Renderer(model, height=480, width=640)

    for i in range(1000):
        # Apply control
        data.ctrl[0] = 4.0 * np.sin(i * 0.03)
        data.ctrl[1] = 2.5 * np.sin(i * 0.05)

        # Step simulation
        mujoco.mj_step(model, data)

        if i % 4 == 0:
            # Get end effector position
            ee_pos = data.site_xpos[model.site('end_effector').id].copy()

            # Track position
            experiment.tracks("robot/position").append(
                step=i,
                x=ee_pos[0],
                y=ee_pos[1],
                z=ee_pos[2]
            )

            # Track control
            experiment.tracks("robot/control").append(
                step=i,
                ctrl_1=float(data.ctrl[0]),
                ctrl_2=float(data.ctrl[1])
            )

            # Save frame aligned with track
            renderer.update_scene(data)
            pixels = renderer.render()
            experiment.files("frames").save_image(
                pixels,
                to=f"frame_{i:05d}.jpg"
            )
```

## Aligning Frames with Tracks

Use consistent step indices to align frames with track data:

```python
with Experiment("vision/tracking").run as experiment:
    for step in range(1000):
        # Track data
        experiment.tracks("agent/position").append(
            step=step,
            x=x,
            y=y
        )

        # Save frame with same step index
        experiment.files("frames").save_image(
            frame,
            to=f"frame_{step:05d}.jpg"
        )

        # Now frames and tracks are aligned by step index!
```

## Reinforcement Learning Example

```python
import gymnasium as gym

with Experiment("rl/cartpole").run as experiment:
    env = gym.make("CartPole-v1")

    for episode in range(100):
        state, info = env.reset()
        done = False
        total_reward = 0
        step = 0

        while not done:
            action = agent.act(state)
            next_state, reward, terminated, truncated, info = env.step(action)
            done = terminated or truncated

            # Track episode trajectory
            experiment.tracks("agent/trajectory").append(
                episode=episode,
                step=step,
                state=state.tolist(),  # numpy to list
                action=int(action),
                reward=float(reward),
                next_state=next_state.tolist()
            )

            state = next_state
            total_reward += reward
            step += 1

        # Track episode summary
        experiment.tracks("agent/episodes").append(
            episode=episode,
            total_reward=total_reward,
            steps=step
        )
```

## Buffering and Performance

Tracks use the background buffering system:

```python
with Experiment("high-freq/tracking").run as experiment:
    # All track appends are non-blocking
    for i in range(100000):
        experiment.tracks("sensor/data").append(
            step=i,
            value=sensor.read()
        )
        # Returns immediately! No blocking I/O

    # Automatically batched and uploaded in background
```

Configure track buffering:

```bash
export ML_DASH_TRACK_BATCH_SIZE=100  # Batch 100 track entries
export ML_DASH_FLUSH_INTERVAL=5.0    # Flush every 5 seconds
```

## Timestamp Merging

Entries with the same timestamp are automatically merged:

```python
# Using explicit timestamps
experiment.tracks("multi-sensor").append(temperature=25.0, _ts=12345.67)
experiment.tracks("multi-sensor").append(pressure=1013.0, _ts=12345.67)

# Result: Single entry with both fields
# {"timestamp": 12345.67, "temperature": 25.0, "pressure": 1013.0}
```

You can also use `_ts=-1` for merging:

```python
# First append sets the timestamp
experiment.tracks("multi-sensor").append(temperature=25.0, _ts=12345.67)

# Following appends inherit and merge
experiment.tracks("multi-sensor").append(pressure=1013.0, _ts=-1)
experiment.tracks("multi-sensor").append(humidity=60.0, _ts=-1)

# Result: Single entry with all three fields at timestamp 12345.67
```

## Best Practices

### 1. Use Consistent Indexing

```python
# Good: Use step index consistently
for step in range(1000):
    experiment.tracks("data").append(step=step, value=v
    )
    experiment.files("frames").save_image(frame, to=f"frame_{step:05d}.jpg")

# Bad: Inconsistent indexing makes alignment hard
for i in range(1000):
    experiment.tracks("data").append(index=i * 2, value=v
    )
    experiment.files("frames").save_image(frame, to=f"frame_{i}.jpg")
```

### 2. Include Step/Episode in Data

```python
# Good: Always include step/episode for easy querying
experiment.tracks("agent/rewards").append(
    episode=episode,
    step=step,
    reward=reward
)

# Less useful: Missing context
experiment.tracks("agent/rewards").append(
    reward=reward
)
```

### 3. Organize by Topic

```python
# Good: Clear topic hierarchy
experiment.tracks("robot/joints/arm").append(**data)
experiment.tracks("robot/joints/leg").append(**data)
experiment.tracks("robot/sensors/imu").append(**data)

# Less clear: Flat structure
experiment.tracks("arm_data").append(**data)
experiment.tracks("leg_data").append(**data)
```

### 4. Zero-Pad Filenames for Alignment

```python
# Good: Files sort correctly
experiment.files("frames").save_image(frame, to=f"frame_{i:05d}.jpg")
# frame_00000.jpg, frame_00001.jpg, frame_00002.jpg

# Bad: Sorting breaks
experiment.files("frames").save_image(frame, to=f"frame_{i}.jpg")
# frame_1.jpg, frame_10.jpg, frame_2.jpg  (wrong order!)
```

### 5. Store Frame References in Tracks

```python
for step in range(1000):
    frame_filename = f"frame_{step:05d}.jpg"

    # Save frame
    experiment.files("frames").save_image(frame, to=frame_filename)

    # Reference frame in track
    experiment.tracks("robot/position").append(
        step=step,
        frame=frame_filename,  # Link to frame
        x=x,
        y=y,
        z=z
    )
```

## Track Slicing and Iteration

The `slice()` method returns an iterable view of track data with timestamp-based indexing using floor matching.

### Basic Iteration

```python
with Experiment("robotics/analysis").run as experiment:
    # ... append data to tracks ...
    experiment.tracks.flush()

    # Create slice
    track_slice = experiment.tracks("robot/pose").slice()

    # Iterate through all entries
    for entry in track_slice:
        timestamp = entry["timestamp"]
        position = entry["position"]
        print(f"t={timestamp}: pos={position}")
```

### Timestamp Range Filtering

```python
# Slice specific time range
track_slice = experiment.tracks("robot/pose").slice(
    start_timestamp=10.0,
    end_timestamp=20.0
)

# Iterate through entries in range [10.0, 20.0]
for entry in track_slice:
    process(entry)
```

### Floor-Match Timestamp Queries

The slice object supports `findByTime()` with **floor matching**: returns the entry with the largest timestamp ≤ queried timestamp.

```python
# Create slice
track_slice = experiment.tracks("robot/pose").slice()

# If timestamps are [1.0, 3.0, 5.0, 7.0, 9.0]:

# Single timestamp queries
entry = track_slice.findByTime(5.5)  # Returns entry at timestamp 5.0 (floor match)
entry = track_slice.findByTime(5.0)  # Returns entry at timestamp 5.0 (exact match)
entry = track_slice.findByTime(6.9)  # Returns entry at timestamp 5.0 (floor match)
entry = track_slice.findByTime(7.0)  # Returns entry at timestamp 7.0 (exact match)

# Batch queries with list of timestamps
entries = track_slice.findByTime([1.0, 3.5, 7.0])  # Returns list of 3 entries
# entries[0] -> timestamp 1.0
# entries[1] -> timestamp 3.0 (floor match for 3.5)
# entries[2] -> timestamp 7.0

# Query before first timestamp raises ml_dash.StorageError
# track_slice.findByTime(0.5)  # StorageError: No entry found with timestamp <= 0.5

# Query after last timestamp returns last entry
entry = track_slice.findByTime(100.0)  # Returns entry at timestamp 9.0
```

### Practical Example: Robot Trajectory Analysis

```python
with Experiment("robotics/analysis").run as experiment:
    # ... data already logged ...

    # Analyze trajectory in specific time window
    trajectory = experiment.tracks("robot/pose").slice(0.0, 30.0)

    # Iterate through trajectory
    positions = []
    for entry in trajectory:
        positions.append(entry["position"])

    # Get robot state at specific times (single queries)
    state_at_5s = trajectory.findByTime(5.0)
    state_at_10s = trajectory.findByTime(10.0)
    state_at_15_5s = trajectory.findByTime(15.5)  # Floor match to closest ≤ 15.5

    # Or batch query multiple times at once
    states = trajectory.findByTime([5.0, 10.0, 15.5, 20.0, 25.0])
    for state in states:
        print(f"t={state['timestamp']}: pos={state['position']}")

    # Calculate metrics
    total_distance = calculate_distance(positions)
    print(f"Total distance: {total_distance:.2f}m")
    print(f"Number of waypoints: {len(trajectory)}")
```

### Synchronizing Multi-Modal Data

Combine slicing with timestamp inheritance for synchronized queries:

```python
with Experiment("robotics/sync").run as experiment:
    # Read multiple synchronized tracks
    pose_slice = experiment.tracks("robot/pose").slice(0.0, 10.0)
    camera_slice = experiment.tracks("camera/left").slice(0.0, 10.0)
    lidar_slice = experiment.tracks("sensors/lidar").slice(0.0, 10.0)

    # Query all tracks at same timestamp (floor match ensures sync)
    for pose_entry in pose_slice:
        t = pose_entry["timestamp"]
        camera_entry = camera_slice.findByTime(t)
        lidar_entry = lidar_slice.findByTime(t)

        # All entries at same timestamp (or floor-matched)
        process_multimodal(pose_entry, camera_entry, lidar_entry)
```

### Slice Features

**Iterator Protocol:**
- `for entry in slice: ...` - Iterate through entries
- `iter(slice)` - Get iterator
- Can iterate multiple times (data is cached)

**Timestamp Queries:**
- `slice.findByTime(timestamp)` - Get entry by timestamp (floor match)
- Optimized for sequential queries using internal index
- Raises `StorageError` (from `ml_dash`) if query timestamp is before first entry

**Length:**
- `len(slice)` - Get number of entries in slice

**Representation:**
- `repr(slice)` - Shows topic, start, and end timestamps

## API Reference

### `experiment.tracks(topic: str) -> TrackBuilder`

Returns a TrackBuilder for the specified topic.

**Parameters:**
- `topic` (str): Topic name (e.g., "robot/position")

**Returns:**
- TrackBuilder instance

### `TrackBuilder.append(**fields, _ts=None) -> TrackBuilder`

Append a data entry to the track. Keyword-only: each keyword becomes a field.

**Parameters:**
- `**fields`: Data fields to track
- `_ts` (float, optional): Timestamp. Omitted: generated from the current time. `-1`: reuse the previous timestamp. A number: use it as given.

**Examples:**

```python
# With automatic timestamp
experiment.tracks("sensor/temp").append(value=25.0)

# With explicit timestamp
experiment.tracks("sensor/temp").append(value=25.0, _ts=time.time())

# Multiple fields
experiment.tracks("sensor/temp").append(
    step=100,
    value=25.0
)

# From a dict
experiment.tracks("sensor/temp").append(**{"value": 25.0})
```

### `TrackBuilder.slice(start_timestamp: float = None, end_timestamp: float = None) -> TrackSlice`

Create an iterable slice of track data with timestamp-based indexing.

**Parameters:**
- `start_timestamp` (float, optional): Start timestamp (inclusive)
- `end_timestamp` (float, optional): End timestamp (inclusive)

**Returns:**
- `TrackSlice` object supporting iteration and timestamp indexing

**Examples:**

```python
# Full track slice
track_slice = experiment.tracks("robot/pose").slice()

# Time range slice
track_slice = experiment.tracks("robot/pose").slice(
    start_timestamp=0.0,
    end_timestamp=10.0
)

# Iterate
for entry in track_slice:
    print(entry["timestamp"], entry["position"])

# Floor-match timestamp query
entry = track_slice.findByTime(5.5)  # Returns entry with largest timestamp <= 5.5

# Get length
count = len(track_slice)
```

## Comparison with Metrics

| Feature | Tracks | Metrics |
|---------|--------|---------|
| Use Case | Time-series data, trajectories | Training metrics, losses |
| Structure | Flexible dict per entry | Flat key-value pairs |
| Timestamp | `_ts` field, explicit or auto | `_ts` field, explicit or auto |
| `_ts=-1` inheritance | Yes, shared with metrics | Yes, shared with tracks |
| Merging | Timestamp-based merging | No merging |
| Best For | Robotics, RL, sensors | Training loss, accuracy |

## Example: Complete Robot Tracking

```python
import mujoco
import numpy as np
from ml_dash import Experiment

with Experiment(
    prefix="robotics/complete-tracking",
    tags=["mujoco", "tracking"],
    dash_url="http://localhost:3000"
).run as experiment:
    experiment.log("Starting robot tracking experiment")

    # Initialize MuJoCo
    model = mujoco.MjModel.from_xml_string(xml_content)
    data = mujoco.MjData(model)
    renderer = mujoco.Renderer(model, height=480, width=640)

    steps = 1000
    record_interval = 4

    for i in range(steps):
        # Control
        ctrl_1 = 4.0 * np.sin(i * 0.03)
        ctrl_2 = 2.5 * np.sin(i * 0.05)
        data.ctrl[0] = ctrl_1
        data.ctrl[1] = ctrl_2

        # Simulate
        mujoco.mj_step(model, data)

        # Record
        if i % record_interval == 0:
            # Render
            renderer.update_scene(data)
            pixels = renderer.render()

            # Get state
            ee_pos = data.site_xpos[model.site('end_effector').id].copy()

            # Save frame
            experiment.files("robot/frames").save_image(
                pixels,
                to=f"frame_{i:05d}.jpg",
                quality=85
            )

            # Track position
            experiment.tracks("robot/position").append(
                step=i,
                x=float(ee_pos[0]),
                y=float(ee_pos[1]),
                z=float(ee_pos[2])
            )

            # Track control
            experiment.tracks("robot/control").append(
                step=i,
                ctrl_1=float(ctrl_1),
                ctrl_2=float(ctrl_2)
            )

            experiment.log(
                f"Step {i:3d}: pos=({ee_pos[0]:.4f}, "
                f"{ee_pos[1]:.4f}, {ee_pos[2]:.4f})"
            )

    experiment.log("Tracking complete!")
```

This creates a complete tracking dataset with aligned frames, positions, and control signals!

---

Source: https://docs.dreamlake.ai/ml-dash/guides/buffering

# Background Buffering

ML-Dash includes a comprehensive background buffering system that eliminates I/O blocking during training. All write operations (logs, metrics, tracks, files) are automatically batched and executed in background threads.

## Overview

The buffering system provides:
- **Non-blocking writes**: All operations return immediately
- **Automatic batching**: Groups writes for efficiency
- **Parallel uploads**: Uses ThreadPoolExecutor for files
- **Graceful error handling**: Training continues even if uploads fail
- **Progress feedback**: Shows flush status after training

## How It Works

```python
from ml_dash import Experiment

with Experiment("my-project/exp").run as experiment:
    # All of these return immediately (non-blocking)
    experiment.log("Training started")
    experiment.params.set(learning_rate=0.001)

    for epoch in range(100):
        for batch in range(1000):
            # Non-blocking metric writes
            experiment.metrics("train").log(
                epoch=epoch,
                batch=batch,
                loss=0.5
            )

    # Automatic flush on context exit
    # Shows: "[ML-Dash] Flushing buffered data..."
```

## Flush Triggers

Data is automatically flushed when:

1. **Time-based**: Every 5 seconds (default)
2. **Size-based**: When a queue reaches its batch size (100 logs or track entries, 1000 metric points by default)
3. **Manual**: When you call `experiment.flush()`
4. **Context exit**: When the experiment context manager exits

## Configuration

### Environment Variables

```bash
# Enable/disable buffering (default: true)
export ML_DASH_BUFFER_ENABLED=true

# Flush interval in seconds (default: 5.0)
export ML_DASH_FLUSH_INTERVAL=5.0

# Batch sizes
export ML_DASH_LOG_BATCH_SIZE=100      # default: 100
export ML_DASH_METRIC_BATCH_SIZE=1000  # default: 1000
export ML_DASH_TRACK_BATCH_SIZE=100    # default: 100

# File upload workers (default: 4)
export ML_DASH_FILE_UPLOAD_WORKERS=4
```

The settings are read from the environment when the `Experiment` is
constructed, so set them before you create it. There is no per-experiment
argument: `Experiment(..., buffer_config=...)` is not a parameter, and like any
unknown keyword it is silently ignored.

## Manual Flushing

Force an immediate flush at any time:

```python
with Experiment("my-project/exp").run as experiment:
    # Training loop
    for epoch in range(100):
        train_model()
        experiment.metrics("train").log(loss=loss)

    # Force flush before saving checkpoint
    experiment.flush()

    # Now safe to save model knowing all metrics are uploaded
    torch.save(model, "checkpoint.pt")
```

## Disabling Buffering

For debugging or special cases, you can disable buffering:

```python
import os
os.environ["ML_DASH_BUFFER_ENABLED"] = "false"  # before creating the Experiment

with Experiment(prefix="alice/project/exp").run as exp:
    # All writes are immediate (blocking)
    exp.log("Immediate write")
```

## Performance Benefits

### Without Buffering (Blocking)
```python
# Each write blocks for ~100-500ms
for i in range(1000):
    experiment.log(f"Step {i}")  # Blocks!
    # Total time: 1000 * 100ms = 100+ seconds
```

### With Buffering (Non-blocking)
```python
# Writes return immediately
for i in range(1000):
    experiment.log(f"Step {i}")  # Returns instantly!
    # Total time: <1 second
```

**Result**: 10-100x speedup for high-frequency logging!

## Progress Messages

When the experiment completes, you'll see:

```
[ML-Dash] Flushing buffered data...
[ML-Dash]   - 1000 log(s), 100 metric point(s), 50 track entry(ies), 10 file(s)
[ML-Dash]   Uploading 10 file(s)...
[ML-Dash]   [1/10] Uploaded frame_0001.jpg
[ML-Dash]   [2/10] Uploaded frame_0002.jpg
...
[ML-Dash] ✓ All data flushed successfully
```

## Error Handling

The buffering system handles errors gracefully:

```python
with Experiment("my-project/exp").run as experiment:
    # Even if network fails, training continues
    for i in range(10000):
        experiment.log(f"Step {i}")
        # If upload fails, warning is shown but training continues

    # Errors are logged, not raised
    # Your training won't crash due to I/O issues
```

## Thread Safety

The buffering system is fully thread-safe:

```python
from concurrent.futures import ThreadPoolExecutor

with Experiment("my-project/exp").run as experiment:
    def worker(i):
        experiment.log(f"Worker {i}")
        experiment.metrics("train").log(step=i, loss=0.5)

    # Safe to use from multiple threads
    with ThreadPoolExecutor(max_workers=10) as executor:
        executor.map(worker, range(1000))
```

## Best Practices

1. **Let it auto-flush**: Don't call `flush()` unless you need guarantees before checkpoints
2. **Use context managers**: Ensures all data is flushed on exit
3. **Monitor progress**: Watch the flush messages to understand batching behavior
4. **Adjust batch sizes**: Increase for very high-frequency logging
5. **Keep buffering enabled**: It's designed for production use

## Technical Details

### Architecture

- **Single background thread**: One daemon thread per experiment
- **Resource-specific queues**: Separate queues for logs, metrics, tracks, files
- **No timeout on close**: Waits indefinitely for all data to flush
- **Temp file cleanup**: Automatically cleans up temporary files after upload

### File Handling

When you save files via methods like `save_image()`, `save_json()`, etc.:

1. Content is written to a temporary file
2. File upload is queued in the buffer
3. Temporary file is kept until upload completes
4. Buffer manager cleans up temp file after successful upload
5. All cleanup happens automatically in the background

This ensures:
- No file handle leaks
- No disk space waste
- Proper cleanup even if uploads are delayed

## Troubleshooting

### Data not appearing immediately

This is expected! Data is buffered and flushed periodically. If you need immediate visibility:

```python
experiment.log("Important checkpoint")
experiment.flush()  # Force immediate upload
```

### Memory usage growing

If you're generating data faster than it can be uploaded:

```bash
# Reduce batch sizes or flush more frequently (set before creating the Experiment)
export ML_DASH_FLUSH_INTERVAL=2.0   # every 2 seconds instead of 5
export ML_DASH_LOG_BATCH_SIZE=50    # smaller batches
```

### Uploads failing

Check the warnings in console output. Common issues:
- Network connectivity
- Authentication expired (run `ml-dash login` again with the separately installed CLI; see [Authentication](/ml-dash/get-started/authentication.md))
- Server unavailable

The buffering system will retry and warn you, but training continues.

---

Source: https://docs.dreamlake.ai/ml-dash/examples

# Examples

  Complete scripts you can copy and run. Each one writes to `.dash/` in local
  mode, so you don't need an account. Add `dash_url="https://api.dash.ml"` to
  the `Experiment` to send the run to dash.ml as well.

    A minimal loop with parameters, per-epoch metrics, and logs.

    A full PyTorch run, from config to the best and final checkpoints.

    A grid sweep, one experiment per configuration under one project.

    Train several architectures and rank their results.

    Use log levels and metadata to find out what went wrong in a run.

## Tutorial scripts

The ml-dash repository has a numbered set of runnable tutorials in
[`examples/tutorials/`](https://github.com/fortyfive-labs/ml-dash/tree/main/examples/tutorials):

```bash
git clone https://github.com/fortyfive-labs/ml-dash
cd ml-dash/examples/tutorials

python 01_basic_experiment.py
python 02_logging_example.py
python 03_parameters_example.py
python 04_metrics_example.py
python 05_files_example.py
python 06_complete_training.py
python 07_project_root_example.py
python three_usage_styles.py

# Robotics: MuJoCo pose tracking
python robotics/mujoco_tracking.py
```

After a run, browse what it wrote under `.dash/`, or upload it with
`ml-dash upload` (see the [CLI Reference](/ml-dash/reference/cli.md#ml-dash-upload)).

---

Source: https://docs.dreamlake.ai/ml-dash/examples/simple-training

# Simple Training Loop

A basic training loop with logging, parameters, and metrics tracking.

```python
"""Simple training loop example."""
import random
from ml_dash import Experiment

def train_simple_model():
    with Experiment(
        prefix="alice/tutorials/simple-training",
        readme="Simple training example",
        tags=["tutorial", "simple"]
    ).run as experiment:
        experiment.params.set(
            learning_rate=0.001,
            batch_size=32,
            epochs=10,
            model="simple_nn"
        )

        experiment.log("Starting training", level="info")

        for epoch in range(10):
            train_loss = 1.0 / (epoch + 1) + random.uniform(-0.05, 0.05)
            val_loss = 1.2 / (epoch + 1) + random.uniform(-0.05, 0.05)
            accuracy = min(0.95, 0.5 + epoch * 0.05)

            experiment.metrics.log(
                epoch=epoch,
                train=dict(loss=train_loss, accuracy=accuracy),
                eval=dict(loss=val_loss, accuracy=accuracy)
            )

            experiment.log(
                f"Epoch {epoch + 1}/10 complete",
                level="info",
                metadata={"train_loss": train_loss, "val_loss": val_loss, "accuracy": accuracy}
            )

        experiment.log("Training complete!", level="info")

if __name__ == "__main__":
    train_simple_model()
```

---

Source: https://docs.dreamlake.ai/ml-dash/examples/pytorch-mnist

# PyTorch MNIST Training

Complete PyTorch MNIST training with full experiment tracking.

```python
"""PyTorch MNIST training with ML-Dash tracking."""
import torch
import torch.nn as nn
import torch.optim as optim
from torchvision import datasets, transforms
from ml_dash import Experiment

class SimpleNet(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc1 = nn.Linear(784, 128)
        self.fc2 = nn.Linear(128, 64)
        self.fc3 = nn.Linear(64, 10)
        self.relu = nn.ReLU()

    def forward(self, x):
        x = x.view(-1, 784)
        x = self.relu(self.fc1(x))
        x = self.relu(self.fc2(x))
        return self.fc3(x)

def train_mnist():
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    batch_size = 64
    epochs = 5
    learning_rate = 0.001

    transform = transforms.Compose([
        transforms.ToTensor(),
        transforms.Normalize((0.1307,), (0.3081,))
    ])
    train_loader = torch.utils.data.DataLoader(
        datasets.MNIST('./data', train=True, download=True, transform=transform),
        batch_size=batch_size, shuffle=True
    )
    test_loader = torch.utils.data.DataLoader(
        datasets.MNIST('./data', train=False, transform=transform),
        batch_size=batch_size
    )

    model = SimpleNet().to(device)
    optimizer = optim.Adam(model.parameters(), lr=learning_rate)
    criterion = nn.CrossEntropyLoss()

    with Experiment(
        prefix="alice/computer-vision/mnist-pytorch",
        readme="MNIST classification with PyTorch",
        tags=["mnist", "pytorch", "classification"]
    ).run as experiment:
        experiment.params.set(
            model={"architecture": "SimpleMLP", "layers": [784, 128, 64, 10]},
            training={"optimizer": "adam", "learning_rate": learning_rate,
                      "batch_size": batch_size, "epochs": epochs},
            device=str(device),
            dataset="MNIST",
        )

        best_accuracy = 0.0

        for epoch in range(epochs):
            model.train()
            train_loss, correct, total = 0.0, 0, 0

            for data, target in train_loader:
                data, target = data.to(device), target.to(device)
                optimizer.zero_grad()
                output = model(data)
                loss = criterion(output, target)
                loss.backward()
                optimizer.step()

                train_loss += loss.item()
                correct += output.argmax(dim=1).eq(target).sum().item()
                total += target.size(0)

            avg_train_loss = train_loss / len(train_loader)
            train_accuracy = correct / total

            model.eval()
            val_loss, correct, total = 0.0, 0, 0
            with torch.no_grad():
                for data, target in test_loader:
                    data, target = data.to(device), target.to(device)
                    output = model(data)
                    val_loss += criterion(output, target).item()
                    correct += output.argmax(dim=1).eq(target).sum().item()
                    total += target.size(0)

            avg_val_loss = val_loss / len(test_loader)
            val_accuracy = correct / total

            experiment.metrics.log(
                epoch=epoch,
                train=dict(loss=avg_train_loss, accuracy=train_accuracy),
                eval=dict(loss=avg_val_loss, accuracy=val_accuracy)
            )

            if val_accuracy > best_accuracy:
                best_accuracy = val_accuracy
                torch.save(model.state_dict(), "best_model.pth")
                experiment.files("models").save(
                    "best_model.pth",
                    description=f"Best model (accuracy: {best_accuracy:.4f})",
                    tags=["best"],
                    metadata={"epoch": epoch, "accuracy": best_accuracy}
                )

        torch.save(model.state_dict(), "final_model.pth")
        experiment.files("models").save("final_model.pth", tags=["final"])
        print(f"Best accuracy: {best_accuracy:.4f}")

if __name__ == "__main__":
    train_mnist()
```

---

Source: https://docs.dreamlake.ai/ml-dash/examples/hyperparameter-search

# Hyperparameter Search

Grid search over hyperparameters with full tracking.

```python
"""Hyperparameter search example."""
from itertools import product
import random
from ml_dash import Experiment

def train_with_config(lr, batch_size, experiment):
    for epoch in range(10):
        loss = 1.0 / (epoch + 1) * (lr / 0.01) + random.uniform(-0.05, 0.05)
        accuracy = min(0.95, 0.5 + epoch * 0.05 * (32 / batch_size))
        experiment.metrics.log(epoch=epoch, train=dict(loss=loss, accuracy=accuracy))
    return accuracy

def hyperparameter_search():
    learning_rates = [0.1, 0.01, 0.001]
    batch_sizes = [16, 32, 64]
    results = []

    for lr, bs in product(learning_rates, batch_sizes):
        with Experiment(
            prefix=f"alice/hyperparameter-search/search-lr{lr}-bs{bs}",
            readme=f"Grid search: lr={lr}, batch_size={bs}",
            tags=["grid-search", f"lr-{lr}", f"bs-{bs}"]
        ).run as experiment:
            experiment.params.set(learning_rate=lr, batch_size=bs, optimizer="sgd", epochs=10)
            experiment.log(f"Starting training with lr={lr}, bs={bs}")

            final_accuracy = train_with_config(lr, bs, experiment)
            experiment.log(f"Final accuracy: {final_accuracy:.4f}")
            results.append(dict(lr=lr, batch_size=bs, accuracy=final_accuracy))

    best = max(results, key=lambda x: x["accuracy"])
    print(f"Best: lr={best['lr']}, batch_size={best['batch_size']}, accuracy={best['accuracy']:.4f}")

if __name__ == "__main__":
    hyperparameter_search()
```

---

Source: https://docs.dreamlake.ai/ml-dash/examples/experiment-comparison

# Experiment Comparison

Track multiple experiments and compare results across architectures.

```python
"""Compare multiple experiments."""
from ml_dash import Experiment
import random

def train_model(architecture, experiment):
    base_acc = {"cnn": 0.85, "resnet": 0.90, "vit": 0.92}[architecture]
    epochs = 20
    for epoch in range(epochs):
        acc = min(base_acc, 0.5 + epoch * (base_acc - 0.5) / epochs + random.uniform(-0.02, 0.02))
        experiment.metrics("train").log(accuracy=acc, epoch=epoch)
    return acc

def compare_architectures():
    architectures = ["cnn", "resnet", "vit"]
    results = {}

    for arch in architectures:
        with Experiment(
            prefix=f"alice/architecture-comparison/comparison-{arch}",
            readme=f"Training {arch} on CIFAR-10",
            tags=["comparison", arch, "cifar10"]
        ).run as experiment:
            experiment.params.set(architecture=arch, dataset="cifar10", batch_size=128, epochs=20)
            experiment.log(f"Training {arch} architecture")

            final_acc = train_model(arch, experiment)
            experiment.log(f"Final accuracy: {final_acc:.4f}")
            results[arch] = final_acc

    for arch in sorted(results, key=results.get, reverse=True):
        print(f"{arch:10s}: {results[arch]:.4f}")

if __name__ == "__main__":
    compare_architectures()
```

---

Source: https://docs.dreamlake.ai/ml-dash/examples/logging-debugging

# Logging & Debugging

Comprehensive logging for debugging training runs.

```python
"""Debugging example with comprehensive logging."""
from ml_dash import Experiment
import random

def train_with_debug():
    with Experiment(
        prefix="alice/debugging/debug-training",
        readme="Training with debug logging",
        tags=["debug"]
    ).run as experiment:
        experiment.params.set(learning_rate=0.001, batch_size=32, model="debug_net")
        experiment.log("Training experiment started", level="info")
        experiment.log("Initializing model", level="debug")

        for epoch in range(5):
            experiment.log(f"Starting epoch {epoch + 1}", level="debug")
            loss = 1.0 / (epoch + 1)

            if epoch == 2:
                experiment.log(
                    "Learning rate may be too high",
                    level="warn",
                    metadata={"current_lr": 0.001, "suggested_lr": 0.0001}
                )

            if random.random() < 0.2:
                experiment.log(
                    "Gradient clipping applied",
                    level="warn",
                    metadata={"gradient_norm": 15.5, "max_norm": 10.0}
                )

            experiment.metrics("train").log(loss=loss, epoch=epoch)
            experiment.log(f"Epoch {epoch + 1} complete", level="info", metadata={"loss": loss})

        experiment.log("Training complete", level="info")

if __name__ == "__main__":
    train_with_debug()
```

---

Source: https://docs.dreamlake.ai/ml-dash/reference/api

# ML-Dash API Reference

Complete API reference for ML-Dash Python SDK.

## Table of Contents

- [Experiment](#experiment)
  - [Constructor](#experiment-constructor)
  - [Lifecycle Management (run)](#lifecycle-management)
  - [Properties](#experiment-properties)
- [Parameters (params)](#parameters)
- [Logging](#logging)
- [Metrics](#metrics)
- [Files](#files)
- [Auto-Start (dxp)](#auto-start-dxp)
- [Complete Examples](#complete-examples)

---

## Experiment

The `Experiment` class is the main entry point for ML-Dash. It represents a single machine learning experiment run.

### Experiment Constructor

```python
Experiment(
    prefix: Optional[str] = None,
    *,
    readme: Optional[str] = None,
    tags: Optional[List[str]] = None,
    bindrs: Optional[List[str]] = None,
    metadata: Optional[Dict[str, Any]] = None,
    # Mode configuration
    dash_url: Optional[Union[str, bool]] = None,
    dash_root: Optional[str] = ".dash",
)
```

#### Prefix Format

The prefix is a universal key that identifies your experiment:

```
{owner}/{project}/path.../[name]
```

- **owner**: First segment (e.g., your username)
- **project**: Second segment (e.g., project name)
- **path**: Remaining segments form the folder structure
- **name**: Derived from the last segment

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prefix` | `str` | `None` | Universal key in format `owner/project/name` |
| `readme` | `str` | `None` | Human-readable description of the experiment, stored as its description on the server |
| `tags` | `List[str]` | `None` | Tags for categorization and search |
| `bindrs` | `List[str]` | `None` | Binders for advanced organization |
| `metadata` | `Dict[str, Any]` | `None` | Additional structured metadata |
| `dash_url` | `str \| bool` | `None` | Server URL. `True` uses `ML_DASH_API_URL`, or `https://api.dash.ml` if unset. `None` means no server |
| `dash_root` | `str` | `".dash"` | Local storage directory. `None` means no local copy |

Any other keyword argument is passed to the run configuration (`RUN`).
Unknown keywords are not an error, so a misspelled argument, or
`description=` instead of `readme=`, is silently ignored.

#### Mode Configuration

`dash_url` and `dash_root` together choose where data goes:

| `dash_url` | `dash_root` | Mode | Writes to |
|---|---|---|---|
| `None` (default) | `".dash"` (default) | local | the local directory only |
| a URL or `True` | `".dash"` (default) | hybrid | the server **and** the local directory |
| a URL or `True` | `None` | remote | the server only |

```python
# Local (the default): no server, no login
Experiment(prefix="alice/my-project/my-experiment")

# Hybrid: server plus a local copy in .dash/
Experiment(prefix="alice/my-project/my-experiment", dash_url="https://api.dash.ml")

# Remote only
Experiment(prefix="alice/my-project/my-experiment", dash_url="https://api.dash.ml", dash_root=None)
```

The chosen mode is available as `experiment.mode` (an `OperationMode`).

---

### Lifecycle Management

Experiments are managed through the `run` property, which returns a `RunManager` instance. The RunManager supports three usage patterns:

#### 1. Context Manager (Recommended)

Automatically starts and completes/fails the experiment:

```python
with Experiment(prefix="alice/proj/exp").run as exp:
    exp.log("Training started")
    exp.params.set(lr=0.001)
    # Experiment automatically completes on successful exit
    # or fails if an exception occurs
```

#### 2. Decorator Pattern

Perfect for wrapping training functions:

```python
exp = Experiment(prefix="alice/proj/exp")

@exp.run
def train_model(experiment):
    experiment.log("Training...")
    experiment.params.set(lr=0.001)
    return "done"

result = train_model()
```

#### 3. Manual Control

Explicit start/complete for fine-grained control:

```python
exp = Experiment(prefix="alice/proj/exp")

exp.run.start()
try:
    exp.log("Training...")
    exp.params.set(lr=0.001)
    exp.run.complete()
except Exception:
    exp.run.fail()
```

#### RunManager Methods

| Method | Description | Status Set |
|--------|-------------|------------|
| `run.start()` | Start the experiment | `RUNNING` |
| `run.complete()` | Mark experiment as successfully completed | `COMPLETED` |
| `run.fail()` | Mark experiment as failed | `FAILED` |
| `run.cancel()` | Mark experiment as cancelled | `CANCELLED` |

---

### Experiment Properties

| Property | Type | Description |
|----------|------|-------------|
| `experiment.name` | `str` | Experiment name (last prefix segment) |
| `experiment.project` | `str` | Project name (second prefix segment) |
| `experiment.owner` | `str` | Owner namespace (first prefix segment) |
| `experiment.readme` | `str` | Experiment description, as passed to `readme=` |
| `experiment.tags` | `List[str]` | Experiment tags |
| `experiment.mode` | `OperationMode` | `LOCAL`, `HYBRID`, or `REMOTE` |
| `experiment.id` | `str` | Experiment ID (remote mode only, after start) |
| `experiment.data` | `dict` | Full experiment data (remote mode only, after start) |

---

## Parameters

Access experiment parameters through the `params` property (not a method).

### Setting Parameters

```python
# Set simple parameters
exp.params.set(
    learning_rate=0.001,
    batch_size=32,
    epochs=100
)

# Set nested parameters (auto-flattened)
exp.params.set(
    model={
        "architecture": "resnet50",
        "layers": 50,
        "pretrained": True
    },
    optimizer={
        "type": "adam",
        "lr": 0.001
    }
)

# Update specific nested parameters
exp.params.set(model={"lr": 0.0001})  # Only updates model.lr
```

### Getting Parameters

```python
# Get flattened parameters (dot notation)
params = exp.params.get()
# Returns: {"learning_rate": 0.001, "model.architecture": "resnet50", ...}

# Get nested parameters (hierarchical structure)
params = exp.params.get(flatten=False)
# Returns: {"learning_rate": 0.001, "model": {"architecture": "resnet50", ...}}
```

### Parameters API

| Method | Returns | Description |
|--------|---------|-------------|
| `params.set(**kwargs)` | `ParametersBuilder` | Set/merge parameters (supports nested dicts) |
| `params.get(flatten=True)` | `dict` | Get parameters (flattened or nested) |

**Note:** Parameters are automatically flattened for storage using dot notation:
- Input: `{"model": {"lr": 0.001}}`
- Stored as: `{"model.lr": 0.001}`

---

## Logging

Log messages with different severity levels and optional metadata.

### Basic Logging

```python
# Simple log
exp.log("Training started")

# Log with level
exp.log("Training started", level="info")
exp.log("Warning: Low GPU memory", level="warning")
exp.log("Error occurred", level="error")
```

### Logging with Metadata

```python
# Traditional style
exp.log(
    "Epoch completed",
    level="info",
    metadata={"epoch": 1, "loss": 0.5, "accuracy": 0.85}
)

# Or pass metadata as kwargs
exp.log("Epoch completed", level="info", epoch=1, loss=0.5, accuracy=0.85)
```

### Fluent Logging API

```python
# Fluent style logging
exp.logs.info("Training started", metadata={"epoch": 1})
exp.logs.error("Failed to load data", error_code=500)
exp.logs.warn("GPU memory low", memory_available="1GB")
```

### Log Levels

| Level | Description |
|-------|-------------|
| `debug` | Detailed diagnostic information |
| `info` | General informational messages (default) |
| `warning` | Warning messages for potential issues |
| `error` | Error messages for failures |

---

## Metrics

Track time-series metrics like loss, accuracy, etc.

### Basic Usage

Log train and eval metrics together:

```python
# Log all metrics for an epoch in one call
exp.metrics.log(
    epoch=epoch,
    train=dict(loss=train_loss, accuracy=train_acc),
    eval=dict(loss=val_loss, accuracy=val_acc)
)
```

### Prefix-Based Logging

Log metrics using namespace prefixes:

```python
# Log train metrics with prefix; put epoch/step in each call
exp.metrics("train").log(loss=0.5, accuracy=0.85, epoch=epoch)

# Log eval metrics with prefix
exp.metrics("eval").log(loss=0.6, accuracy=0.82, epoch=epoch)
```

A bare `exp.metrics.log(epoch=epoch)` writes to a separate unnamed series and
is not attached to the `train`/`eval` rows.

### Buffer API

For high-frequency logging (per-batch), use the buffer API:

```python
for batch in dataloader:
    loss = train_step(batch)
    acc = compute_accuracy(batch)

    # Buffer per-batch values (not written to disk yet)
    exp.metrics("train").buffer(loss=loss, accuracy=acc)

# At end of epoch, compute and log summary statistics
exp.metrics.buffer.log_summary(epoch=epoch)  # default: mean, plus epoch
```

### Multiple Aggregations

```python
# Default (just mean)
exp.metrics.buffer.log_summary()

# Multiple aggregations
exp.metrics.buffer.log_summary("mean", "std", "min", "max", "count")

# Percentiles
exp.metrics.buffer.log_summary("p50", "p90", "p95", "p99")
```

### Reading Metrics

```python
# Read metric data
data = exp.metrics("train_loss").read(start_index=0, limit=100)
# Returns: {
#     "data": [...],
#     "startIndex": 0,
#     "endIndex": 99,
#     "total": 1000,
#     "hasMore": True
# }

# Get statistics
stats = exp.metrics("train_loss").stats()
# Returns: {
#     "count": 1000,
#     "firstValue": {...},
#     "lastValue": {...},
#     ...
# }
```

### Metrics API

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `metrics(prefix)` | `str` | `MetricBuilder` | Create/get metric builder with prefix |
| `metrics.log(**data)` | Flexible data fields | `MetricBuilder` | Log metric data point |
| `metrics("prefix").log(**data)` | Flexible data fields | `MetricBuilder` | Log with prefix |
| `metrics("prefix").buffer(**data)` | Flexible data fields | `None` | Buffer values for summary |
| `metrics.buffer.log_summary(*aggs)` | aggregation names | `None` | Log summary statistics |
| `metrics.flush()` | - | `None` | Flush pending metrics |
| `metrics("prefix").read(start_index, limit)` | int, int | `dict` | Read data points |
| `metrics("prefix").stats()` | - | `dict` | Get metric statistics |

---

## Files

Upload, download, and manage files associated with experiments.

### Basic File Upload

```python
# Upload a file
result = exp.files("models").save("./model.pt")

# Upload with metadata
result = exp.files("models").save(
    "./model.pt",
    description="Best model checkpoint",
    tags=["best", "checkpoint"],
    metadata={"epoch": 50, "accuracy": 0.95}
)
```

### Enhanced File Operations

#### Save JSON Objects

```python
# Save dict/object as JSON
config = {
    "model": "resnet50",
    "lr": 0.001,
    "batch_size": 32
}

result = exp.files("configs").save_json(config, to="config.json")
```

#### Save PyTorch Models

```python
import torch

# Save PyTorch model
model = torch.nn.Linear(10, 5)
result = exp.files("models").save_torch(model, to="model.pt")

# Save state dict
result = exp.files("models").save_torch(model.state_dict(), to="model.pth")
```

#### Save Pickle Objects

```python
# Save any Python object as pickle
data = {"results": [1, 2, 3], "metadata": {"version": "1.0"}}
result = exp.files("data").save_pkl(data, to="data.pkl")
```

#### Save Matplotlib Figures

```python
import matplotlib.pyplot as plt

# Create plot
plt.plot([1, 2, 3], [1, 4, 9])
plt.title("Sample Plot")

# Save current figure
result = exp.files("plots").save_fig(to="plot.png")

# Save specific figure with custom DPI
fig, ax = plt.subplots()
ax.plot([1, 2, 3])
result = exp.files("plots").save_fig(
    fig=fig,
    to="plot.pdf",
    dpi=150,
    bbox_inches='tight'
)
```

#### Save Videos

```python
import numpy as np

# Create video frames (grayscale or RGB)
frames = [np.random.rand(480, 640) for _ in range(30)]

# Save as MP4 (default 20 FPS)
result = exp.files("videos").save_video(frames, to="output.mp4")

# Save with custom FPS
result = exp.files("videos").save_video(frames, to="output.mp4", fps=30)

# Save as GIF
result = exp.files("videos").save_video(frames, to="animation.gif")

# Save with custom codec and quality
result = exp.files("videos").save_video(
    frames,
    to="high_quality.mp4",
    fps=30,
    codec='libx264',
    quality=8
)
```

### File Organization with Bindrs

```python
# Upload file with bindrs for advanced organization
result = exp.files("models",
    bindrs=["v1", "best", "production"],
).save("./model.pt", description="Production model v1")
```

### Listing Files

```python
# List all files
files = exp.files().list()

# List files by prefix
files = exp.files("models").list()

# List files by tags
files = exp.files(tags=["checkpoint"]).list()
```

### Downloading Files

```python
# Download to current directory with original filename
path = exp.files(file_id="123").download()

# Download to custom path
path = exp.files(file_id="123").download(to="./my_model.pt")
```

### File Management

```python
# Update file metadata
result = exp.files(
    file_id="123",
    description="Updated description",
    tags=["new", "tags"],
    metadata={"version": "2.0"}
).update()

# Delete file (soft delete)
result = exp.files(file_id="123").delete()
```

### Files API

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `file(**kwargs)` | See below | `FileBuilder` | Create file builder |
| `save()` | - | `dict` | Upload file |
| `save_json(content, filename)` | `Any`, `str` | `dict` | Save JSON object as file |
| `save_torch(model, filename)` | `Any`, `str` | `dict` | Save PyTorch model as file |
| `save_pkl(content, filename)` | `Any`, `str` | `dict` | Save Python object as pickle file |
| `save_fig(fig, filename, **kwargs)` | `Optional[Any]`, `str`, `**kwargs` | `dict` | Save matplotlib figure as file |
| `save_video(frames, filename, fps, **kwargs)` | `Union[List, Any]`, `str`, `int`, `**kwargs` | `dict` | Save video frame stack as file |
| `list()` | - | `List[dict]` | List files |
| `download(pattern, to)` | `Optional[str]` | `str` | Download file |
| `update()` | - | `dict` | Update file metadata |
| `delete()` | - | `dict` | Delete file |

**FileBuilder kwargs:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `str` | Logical path/prefix (e.g., "models", "configs") |
| `description` | `str` | File description |
| `tags` | `List[str]` | File tags |
| `bindrs` | `List[str]` | File bindrs |
| `metadata` | `dict` | File metadata |
| `file_id` | `str` | File ID (for download/update/delete) |
| `dest_path` | `str` | Destination path (for download) |

---

## Auto-Start (dxp)

The `ml_dash.auto_start` module provides a pre-configured, auto-started experiment singleton named `dxp` for quick prototyping and scratch work.

### Overview

The `dxp` singleton is:
- **Pre-configured**: Name is "dxp", project is "scratch", storage is local (`.dash`)
- **Auto-started**: Ready to use immediately on import - no need to call `.run.start()`
- **Auto-cleanup**: Automatically completed on Python exit via `atexit` handler
- **Fully-featured**: Works exactly like a normal `Experiment` instance

### Import

```python
from ml_dash.auto_start import dxp
```

### Usage

#### Basic Usage

```python
from ml_dash.auto_start import dxp

# Ready to use immediately - already started!
exp.log("Starting quick experiment")
exp.params.set(lr=0.001, batch_size=32)

# Log metrics
exp.metrics("train").log(loss=0.5, step=0)
exp.metrics("train").log(loss=0.4, step=1)

# Upload files
exp.files("models").save("model.pt")

# Automatically completed on Python exit
```

#### Interactive/Notebook Usage

Perfect for Jupyter notebooks and interactive Python sessions:

```python
from ml_dash.auto_start import dxp

# Quick parameter tracking
exp.params.set(
    model="resnet50",
    lr=0.001,
    batch_size=32,
    optimizer="adam"
)

# Log training progress
for epoch in range(10):
    loss = train_epoch()
    exp.metrics("train").log(loss=loss, epoch=epoch)
    exp.log(f"Epoch {epoch} completed", loss=loss)

# Save results
exp.files("results").save_json(results, to="results.json")
```

#### Prototyping Scripts

Great for quick experiments and throwaway scripts:

```python
from ml_dash.auto_start import dxp
import torch

# Track experiment
exp.params.set(model_name="simple_cnn", dataset="mnist")
exp.log("Training started")

# Train model
model = train_model()

# Save model
exp.files("models").save_torch(model, to="model.pt")

# Log final metrics
exp.metrics("train").log(accuracy=0.95, step=10)
exp.log("Training completed")

# No cleanup needed - automatically handled!
```

### Configuration

The `dxp` singleton has a fixed configuration:

| Property | Value | Changeable |
|----------|-------|------------|
| Name | `"dxp"` | No (read-only) |
| Project | `"scratch"` | No (read-only) |
| Storage Mode | Local (`.dash`) | No (fixed at initialization) |
| Local Path | `".dash"` | No (fixed at initialization) |
| Parameters | Empty (initially) | Yes (during lifecycle) |
| Tags | Empty (initially) | No |
| Description | None | No |

### Lifecycle

Unlike normal experiments, `dxp` handles lifecycle automatically:

```python
from ml_dash.auto_start import dxp

# Already started - no need to call .run.start()
assert dxp._is_open  # True

# Use normally
exp.log("Working...")
exp.params.set(foo="bar")

# Automatically completed on Python exit
# No need to call .run.complete()
```

### Manual Lifecycle Control

You can still manually control the lifecycle if needed:

```python
from ml_dash.auto_start import dxp

# Close manually if needed
dxp.run.complete()

# Can reopen
dxp.run.start()

# Or mark as failed
dxp.run.fail()
```

### Comparison with Regular Experiment

| Feature | Regular Experiment | dxp Singleton |
|---------|-------------------|---------------|
| Import | `from ml_dash import Experiment` | `from ml_dash.auto_start import dxp` |
| Configuration | User-defined | Fixed (dxp/scratch/local) |
| Lifecycle | Manual or context manager | Auto-started, auto-completed |
| Use Case | Production experiments | Quick prototyping, notebooks |
| Storage | Local or remote | Local only (`.dash`) |
| Reusable | Create multiple instances | Single global instance |

### Best Practices

1. **Use for Prototyping**: `dxp` is perfect for quick experiments and scratch work
2. **Not for Production**: Use regular `Experiment` for production code
3. **Notebook Sessions**: Ideal for Jupyter notebooks and interactive sessions
4. **Single Session**: Best for single-run scripts; for multiple runs, use regular `Experiment`
5. **Local Development**: Great for local development and debugging

### Example: Complete Prototype

```python
from ml_dash.auto_start import dxp
import torch
import torch.nn as nn

# Setup
exp.params.set(
    model="simple_cnn",
    lr=0.001,
    epochs=10,
    batch_size=64
)

exp.log("Starting prototype experiment")

# Define and train model
model = nn.Sequential(
    nn.Conv2d(1, 32, 3),
    nn.ReLU(),
    nn.MaxPool2d(2),
    nn.Flatten(),
    nn.Linear(32 * 13 * 13, 10)
)

for epoch in range(10):
    loss = train_epoch(model)
    acc = evaluate(model)

    exp.metrics("train").log(loss=loss, accuracy=acc, epoch=epoch)
    exp.log(f"Epoch {epoch}", loss=loss, accuracy=acc)

# Save results
exp.files("models").save_torch(model.state_dict(), to="final.pt")
exp.log("Experiment completed!")

# Automatically saved on exit!
```

---

## Complete Examples

### Complete Training Workflow

```python
from ml_dash import Experiment

# Create experiment
with Experiment(
    prefix="alice/image-classification/resnet50-training",
    readme="ResNet50 on CIFAR-10",
    tags=["resnet", "cifar10", "baseline"]
).run as exp:

    # 1. Set hyperparameters
    exp.params.set(
        model={
            "architecture": "resnet50",
            "pretrained": True,
            "num_classes": 10
        },
        training={
            "optimizer": "adam",
            "lr": 0.001,
            "batch_size": 64,
            "epochs": 100
        }
    )

    # 2. Save configuration
    config = {
        "model": "resnet50",
        "dataset": "cifar10",
        "lr": 0.001
    }
    exp.files("configs").save_json(config, to="config.json")

    # 3. Training loop
    exp.log("Training started", level="info")

    for epoch in range(100):
        # Train one epoch
        train_loss, train_acc = train_epoch()  # Your training code
        val_loss, val_acc = validate()  # Your validation code

        # Log metrics
        exp.metrics("train").log(loss=train_loss, accuracy=train_acc, epoch=epoch)
        exp.metrics("eval").log(loss=val_loss, accuracy=val_acc, epoch=epoch)

        # Log progress
        if epoch % 10 == 0:
            exp.log(
                f"Epoch {epoch} completed",
                level="info",
                train_loss=train_loss,
                val_acc=val_acc
            )

        # Save checkpoints
        if val_acc > best_acc:
            exp.files("models").save_torch(
                model.state_dict(),
                to=f"checkpoint_epoch_{epoch}.pt"
            )
            exp.log(f"New best model saved at epoch {epoch}", level="info")

    # 4. Save final model
    exp.files("models").save_torch(model, to="final_model.pt")

    exp.log("Training completed", level="info")
```

### Hyperparameter Search

```python
from ml_dash import Experiment
import itertools

# Define search space
learning_rates = [0.001, 0.0001, 0.00001]
batch_sizes = [32, 64, 128]

for lr, bs in itertools.product(learning_rates, batch_sizes):
    # Create experiment for each combination
    with Experiment(
        prefix=f"alice/hyperparam-search/search-lr{lr}-bs{bs}",
        tags=["search", "grid"]
    ).run as exp:

        exp.params.set(
            learning_rate=lr,
            batch_size=bs,
            model="resnet18"
        )

        # Train with these hyperparameters
        final_acc = train(lr=lr, batch_size=bs)

        exp.metrics("train").log(accuracy=final_acc, step=1)
        exp.log(f"Search completed: lr={lr}, bs={bs}, acc={final_acc}")
```

### Decorator Pattern for Training Functions

```python
from ml_dash import Experiment

# Create experiment instance
exp = Experiment(
    prefix="alice/my-project/training-run"
)

@exp.run
def train_model(experiment):
    """Training function with automatic experiment management."""

    # Set parameters
    experiment.params.set(
        lr=0.001,
        epochs=50,
        model="resnet50"
    )

    # Training loop
    for epoch in range(50):
        loss = 1.0 / (epoch + 1)  # Simulated loss
        experiment.metrics("train").log(loss=loss, epoch=epoch)
        experiment.log(f"Epoch {epoch}: loss={loss:.4f}")

    # Save model
    experiment.files("models").save_json(
        {"final_loss": loss},
        to="results.json"
    )

    return {"final_loss": loss}

# Run training (experiment automatically managed)
result = train_model()
print(f"Training completed: {result}")
```

### Remote Mode with Team Collaboration

```python
from ml_dash import Experiment

# Connect to shared ML-Dash server
with Experiment(
    prefix="alice/shared-project/team-experiment",
    dash_url="http://ml-dash-server:3000",
    readme="Collaborative experiment",
    tags=["team", "production"]
).run as exp:

    # All data automatically synced to remote server
    exp.params.set(
        researcher="Alice",
        experiment_type="baseline",
        model="bert-base"
    )

    exp.log("Running on remote server", level="info")

    # Metrics stored in MongoDB
    exp.metrics("train").log(loss=0.5, step=100)

    # Files stored in S3
    exp.files("models").save_json(
        {"config": "bert-base"},
        to="model_config.json"
    )

    exp.log("Data synced to team server", level="info")
```

---

## Error Handling

Experiments handle errors gracefully:

```python
try:
    with Experiment(
        prefix="alice/test/my-experiment"
    ).run as exp:
        exp.log("Starting work")
        exp.params.set(test_param="value")

        # Simulate error
        raise ValueError("Something went wrong")

except ValueError as e:
    print(f"Error: {e}")
    # Experiment is automatically marked as FAILED
    # All data is still saved
```

The experiment status will be set to `FAILED` automatically, and all logs, parameters, and metrics are preserved for debugging.

---

## Best Practices

1. **Use Context Managers**: Prefer `with exp.run as exp:` for automatic lifecycle management
2. **Descriptive Names**: Use clear, descriptive experiment names and project names
3. **Add Tags**: Use tags for easy filtering and organization
4. **Log Liberally**: Log important events, errors, and milestones
5. **Structured Metadata**: Use metadata for searchable, structured information
6. **Organize Files**: Use logical prefix paths for file organization
7. **Version Control**: Use bindrs and tags to track model/data versions
8. **Remote for Teams**: Use remote mode for team collaboration and data persistence

---

## API Summary

### Quick Reference

```python
from ml_dash import Experiment

# Create experiment
exp = Experiment(prefix="alice/proj/exp")

# Lifecycle
with exp.run as exp:                    # Context manager
    exp.run.start()                     # Manual start
    exp.run.complete()                  # Manual complete
    exp.run.fail()                      # Mark as failed
    exp.run.cancel()                    # Mark as cancelled

# Parameters
exp.params.set(lr=0.001, bs=32)         # Set parameters
params = exp.params.get()                # Get flattened
params = exp.params.get(flatten=False)   # Get nested

# Logging
exp.log("message")                       # Simple log
exp.log("message", level="info")         # With level
exp.log("msg", epoch=1, loss=0.5)        # With metadata

# Metrics
exp.metrics("train").log(loss=0.5, step=1)          # Log with prefix
exp.metrics.log(epoch=1, train=dict(loss=0.5))      # Log with groups
exp.metrics("train").buffer(loss=0.5)               # Buffer for summary
exp.metrics.buffer.log_summary("mean", "std")       # Log summaries
exp.metrics.flush()                                 # Flush pending
data = exp.metrics("train").read(0, 100)            # Read data
stats = exp.metrics("train").stats()                # Get stats

# Files
exp.files("models").save("model.pt")
exp.files("configs").save_json(config, to="config.json")
exp.files("models").save_torch(model, to="model.pt")
files = exp.files("models").list()
path = exp.files(file_id="123").download()
exp.files(file_id="123").delete()

# Auto-Start (dxp) - Quick prototyping
from ml_dash.auto_start import dxp

exp.log("Already started!")              # Ready to use immediately
exp.params.set(lr=0.001)                 # Set parameters
exp.metrics("train").log(loss=0.5)       # Log metrics
exp.files("models").save("model.pt")     # Upload files
# Auto-completed on Python exit
```

---

Source: https://docs.dreamlake.ai/ml-dash/reference/cli

# CLI Reference

  The `ml-dash` command logs you in, inspects projects and experiments, and
  moves experiment data to and from an ML-Dash server. This page covers CLI
  0.1.1.

The CLI is a separate program from the Python SDK. Install it with the
standalone installer or `npm install -g @dreamlake/ml-dash` (see
[Install](/ml-dash.md#cli)). `pip install ml-dash` no longer installs it (since SDK
0.7.0).

| Command | Description |
|---|---|
| [`login`](#ml-dash-login) | Authenticate with the OAuth device flow |
| [`logout`](#ml-dash-logout) | Clear the stored token |
| [`profile`](#ml-dash-profile) | Show the current user and configuration |
| [`list`](#ml-dash-list) | List projects, experiments, and tracks on the server |
| [`create`](#ml-dash-create) | Create a project |
| [`remove`](#ml-dash-remove) | Delete a project and everything in it |
| [`upload`](#ml-dash-upload) | Upload locally stored experiments to the server |
| [`download`](#ml-dash-download) | Download experiments from the server to local storage |
| [`api`](#ml-dash-api) | Send a raw GraphQL query or mutation |
| [`update`](#ml-dash-update) | Update the CLI itself |
| [`version`](#ml-dash-version) | Print the CLI version |

Run `ml-dash <command> --help` for the exact flags of your installed version.

## Common options

| Flag | Description |
|---|---|
| `--dash-url`, `--api-url` URL | Server to talk to. Defaults to `remote_url` in `~/.dash/config.json`, then `https://api.dash.ml`. Accepted by every command that contacts the server. |
| `-h`, `--help` | Show help for the command |

---

## `ml-dash login`

```bash
ml-dash login [--dash-url URL] [--auth-url URL] [--no-browser]
```

| Flag | Description |
|---|---|
| `--dash-url`, `--api-url` | ML-Dash server to log in to |
| `--auth-url` | OAuth authorization server (default `https://auth.vuer.ai`) |
| `--no-browser` | Print the code and URL, but don't open a browser |

Starts the device authorization flow. It prints a code, a URL, and a QR code,
waits up to 10 minutes for you to approve in a browser, exchanges the result
for an ML-Dash token, and stores it. See [Authentication](/ml-dash/get-started/authentication.md)
for where the token goes and how the SDK reads it.

## `ml-dash logout`

```bash
ml-dash logout
```

Clears the stored token from the keychain and from the `~/.dash/` token files.

## `ml-dash profile`

```bash
ml-dash profile [--dash-url URL] [--json] [--cached]
```

| Flag | Description |
|---|---|
| `--json` | Output as JSON |
| `--cached` | Read the stored token only, without fetching from the server |

Shows your username, name, email, server URL, token expiry, and whether the
data came from the server or the cached token.

---

## `ml-dash list`

```bash
ml-dash list [-p PROJECT] [-n NAMESPACE] [--status STATUS] [--tags TAGS]
             [--detailed] [--tracks] [--topic-filter TOPIC] [--dash-url URL] [-v]
```

| Flag | Description |
|---|---|
| `-p`, `--project` (aliases `--prefix`, `--pref`, `--proj`) | List experiments in this project. Without it, lists projects. Accepts glob patterns: always quote them, e.g. `-p 'tom/tut*'` |
| `-n`, `--namespace` | Namespace for all queries. Defaults to your own |
| `--status` | Filter experiments: `COMPLETED`, `RUNNING`, `FAILED`, or `ARCHIVED` |
| `--tags` | Filter experiments by tags (comma-separated) |
| `--detailed` | Show more columns |
| `--tracks` | List the tracks in one experiment. Needs `-p namespace/project/experiment` |
| `--topic-filter` | Filter tracks by topic, e.g. `'robot/*'` |
| `-v`, `--verbose` | Verbose output |

Results come 50 per page. In a terminal, move between pages with `n` / `→` /
`Space` / `Enter` (next) and `p` / `b` / `←` (previous). Any other key quits.
When output is piped, `list` prints the first page and notes that more results
are available.

A glob without a namespace is expanded against your own namespace:

| Input | Searches |
|---|---|
| `tes*` | `<your-namespace>/tes*/*` |
| `tom/tes*` | `tom/tes*/*` |
| `tom/test/exp*` | `tom/test/exp*` |

```bash
ml-dash list                                   # your projects
ml-dash list -n alice                          # alice's projects
ml-dash list -p my-project                     # experiments in a project
ml-dash list -p 'tom/tes*' --status RUNNING    # glob across projects
ml-dash list --tracks -p tom/test/run-1 --topic-filter 'robot/*'
```

## `ml-dash create`

```bash
ml-dash create -p PROJECT [-d DESCRIPTION] [--dash-url URL]
```

| Flag | Description |
|---|---|
| `-p`, `--project` | `project` or `namespace/project`. Without a namespace, your own is used |
| `-d`, `--description` | Optional description |

If the project already exists, `create` prints a warning and exits
successfully.

## `ml-dash remove`

```bash
ml-dash remove -p PROJECT [-y] [--dash-url URL]
```

| Flag | Description |
|---|---|
| `-p`, `--project` | `project` or `namespace/project` |
| `-y`, `--yes` | Skip the confirmation prompt |

> **Warning:** `remove` deletes the project and all of its experiments, metrics, files, and
> logs. It cannot be undone.

---

## `ml-dash upload`

```bash
ml-dash upload [PATH] [options]
```

Uploads experiments that the SDK wrote in local mode. `PATH` is the local
storage directory and defaults to `./.dash`.

| Flag | Description |
|---|---|
| `-p`, `--project` (aliases `--prefix`, `--pref`, `--proj`) | Only upload experiments matching this prefix or glob, e.g. `'tom/*/exp*'` |
| `-t`, `--target` | Upload under this prefix on the server instead, e.g. `alice/shared-project` |
| `--skip-logs`, `--skip-metrics`, `--skip-files`, `--skip-params` | Leave that kind of data out |
| `--dry-run` | Show what would be uploaded without uploading |
| `--strict` | Fail on any validation error. By default, invalid data is skipped |
| `--batch-size N` | Batch size for logs and metrics (default 100) |
| `--resume` | Resume an interrupted upload |
| `--state-file FILE` | State file for `--resume` (default `.dash-upload-state.json`) |
| `--tracks FILE` | Upload a single track data file (e.g. `robot_position.jsonl`). Needs `--remote-path` |
| `--remote-path PATH` | Where the track goes, e.g. `namespace/project/exp/robot/position` |
| `-v`, `--verbose` | Show detailed progress |

```bash
ml-dash upload                                  # everything in ./.dash
ml-dash upload ./.dash -p 'tom/*/exp*'          # a subset
ml-dash upload --dry-run -v                     # preview
ml-dash upload -t alice/shared-project          # into another project
ml-dash upload --tracks robot_position.jsonl --remote-path tom/proj/exp/robot/position
```

## `ml-dash download`

```bash
ml-dash download [PATH] [options]
```

Downloads experiments into a local storage directory (`PATH`, default
`./.dash`) in the same layout local mode writes.

| Flag | Description |
|---|---|
| `-p`, `--project` (aliases `--prefix`, `--pref`, `--proj`) | Project or glob to download, e.g. `alice/my-project`, `'tut*'` |
| `--experiment NAME` | Only this experiment. Needs `--project` |
| `--skip-logs`, `--skip-metrics`, `--skip-files`, `--skip-params` | Leave that kind of data out |
| `--dry-run` | Preview without downloading |
| `--overwrite` | Overwrite experiments that already exist locally |
| `--resume` | Resume an interrupted download |
| `--state-file FILE` | State file for `--resume` (default `.dash-download-state.json`) |
| `--batch-size N` | Batch size for logs and metrics (default 1000, max 10000) |
| `--max-concurrent-metrics N` | Parallel metric downloads (default 5) |
| `--max-concurrent-files N` | Parallel file downloads (default 3) |
| `--tracks PATH` | Download one track instead, e.g. `namespace/project/exp/robot/position` |
| `-f`, `--format` | Track export format (default `jsonl`) |
| `-o`, `--output FILE` | Track output file (default: named after the topic) |
| `-v`, `--verbose` | Detailed progress |

```bash
ml-dash download -p alice/my-project
ml-dash download ./backup -p alice/my-project --experiment exp-one
ml-dash download -p 'alice/tut*' --dry-run
ml-dash download --tracks alice/proj/exp/robot/position -f jsonl -o joints.jsonl
```

---

## `ml-dash api`

```bash
ml-dash api (--query QUERY | --mutation MUTATION) [--jq PATH] [--dash-url URL]
```

| Flag | Description |
|---|---|
| `-q`, `--query` | GraphQL query |
| `-m`, `--mutation` | GraphQL mutation |
| `--jq PATH` | Pull out one value with a dot path, e.g. `.me.username` |

- A bare body is wrapped for you: `me { username }` is sent as `{ me { username } }`.
- Single quotes are converted to double quotes, so you can write
  `user(title: 'hello')` inside a double-quoted shell string.
- `--jq` paths start from the response data. There is no top-level `data` key,
  so write `.me.username`, not `.data.me.username`.

```bash
ml-dash api --query "me { username name email }"
ml-dash api --query "me { username }" --jq ".me.username"
```

## `ml-dash update`

```bash
ml-dash update [--check] [--version VERSION] [--json]
```

| Flag | Description |
|---|---|
| `--check` | Report whether an update exists. Change nothing |
| `--version` | Install this exact release instead of the latest |
| `--json` | Output as JSON |

Updates through the channel you installed from. An npm install is updated with
`npm install -g @dreamlake/ml-dash@<version>`. A standalone binary downloads the
new build, checks its sha256 and size against the release manifest, runs it
once, and only then replaces itself. `update` refuses to downgrade. It also
refuses to touch a copy it doesn't own (Homebrew, Nix, pipx, a `node_modules`
tree) and tells you which tool to use instead.

## `ml-dash version`

```bash
ml-dash version        # also: ml-dash --version, ml-dash -V
```

---

## Files and environment variables

| | Used for |
|---|---|
| `~/.dash/config.json` | `remote_url`, an optional `api_key` (used instead of the stored login), `auth_url`, and the device-flow secret |
| `~/.dash/tokens.encrypted`, `~/.dash/encryption.key` | The token, when no keychain is used |
| `ML_DASH_CONFIG_DIR` | Use a different directory than `~/.dash` for the CLI. The Python SDK always reads `~/.dash` |
| `ML_DASH_NO_KEYCHAIN=1` | Never use the OS keychain. Store and read the token in the encrypted file |

## Troubleshooting

**`ml-dash: command not found` after upgrading the SDK.** Since SDK 0.7.0, pip
doesn't install the CLI. Install it as shown in [Install](/ml-dash.md#cli).
`python -m ml_dash.cli` no longer exists.

**Authentication errors.** Run `ml-dash profile`. It reports an expired token.
Then run `ml-dash logout && ml-dash login`.

**The SDK can't find your login but the CLI can.** The SDK and the CLI must
agree on where the token lives. See
[Using the token from Python](/ml-dash/get-started/authentication.md#using-the-token-from-python).

---

Source: https://docs.dreamlake.ai/ml-dash/reference/llm-readable

# LLM-Readable Docs

These docs are built to be read by agents as easily as by people. Every page
has a markdown twin, and the whole corpus is published in the formats LLM
tooling already looks for — so you can point your agent at ML-Dash and have it
answer accurately. The ML-Dash pages are part of the DreamLake
docs, so they ship in the same site-wide files.

## Fetch a single page

Append `.md` to any docs URL to get the raw markdown — no nav, no chrome:

```bash
curl https://docs.dreamlake.ai/ml-dash/guides/experiments.md
```

Every page also advertises its markdown twin in the HTML head:

```html
<link rel="alternate" type="text/markdown" href="/ml-dash/guides/experiments.md" />
```

## The whole site, two ways

- **[`/llms.txt`](https://docs.dreamlake.ai/llms.txt)** — a short, linked index
  of every page ([llmstxt.org](https://llmstxt.org) standard). The entry point
  an agent reads first to decide what to fetch. ML-Dash pages are listed
  alongside the rest of the DreamLake docs.
- **[`/llms-full.txt`](https://docs.dreamlake.ai/llms-full.txt)** — every page
  concatenated into one markdown file. Drop the entire product into a context
  window in a single request.

## Import it as a skill

The docs are also packaged as the [`dreamlake` Agent Skill](https://docs.dreamlake.ai/skills/dreamlake.zip)
— a `SKILL.md` plus one markdown reference file per page. It covers the whole
DreamLake docs site; the ML-Dash pages are the `reference/ml-dash*.md` files.
Download it and unpack it wherever you like:

```bash
curl -L https://docs.dreamlake.ai/skills/dreamlake.zip -o dreamlake.zip
unzip dreamlake.zip -d ./agent-skills
```

The archive holds a single `dreamlake/` folder. Move that folder into the
directory your agent loads skills from, or import it however your agent takes
skills. If it has no skill mechanism, give it access to the whole folder and
point it at `./agent-skills/dreamlake/SKILL.md` — reading the markdown is a
fallback rather than an installed skill, and the relative links from `SKILL.md`
into `reference/` only resolve if the rest of the folder comes with it.

> **Note:** **Always current.** Every surface above — the `.md` pages, both `llms` files,
> and the skill — is generated from the same source on each deploy, so none of
> them can drift from what you read on the site.

---

Source: https://docs.dreamlake.ai/dev/notes/notes-select-text

# Agent text selection

## 2026-09-26

The CLI adds `notes select --text` while preserving positional CSS lookup.
Matching is literal, unique by default, optionally scoped by section and occurrence (`-o`/`--occurrence`). Positive
values count from the start and negative values from the end; zero is invalid. The CLI suppresses attributed read highlights during resolution and
publishes one `seek` with the snapshot hash. The existing presence route rejects
stale ranges and uses the normal collaboration ACL. No content mutation occurs.

Section responses retain UTF-16 `start`/`end` and add a code-point `range` plus
whole-source `hash`. This avoids downloading a prefix just to translate offsets.
The CLI fails closed on older section responses. Existing RTC awareness and
remote-cursor rendering require no protocol or UI changes.

Affected public skills: `dreamlake-cli` and `dreamlake-notes`. Sources are CLI
Notes collaboration docs and workspace Notes docs; regenerate both and synchronize
the public repository after committing source. CLI release, server deployment,
docs, public skills and fresh native/npm installed readback are recorded below.

### Validation

- CLI full suite: 1,393 passed, one existing skip; docs tests: two passed.
- Selection tests cover exact Unicode ranges, missing/duplicate refusal,
  occurrence, scoped requests, identity, stale source, old server metadata,
  invalid receipts and compatible CSS lookup.
- Server body/presence/relay tests: 65 passed; the optional subprocess check
  additionally executes the real CLI against Fastify HTTP and confirms no source
  writes. Run it with the companion CLI source:

```bash
DREAMLAKE_SELECT_CLI=/absolute/path/to/dreamlake-cli/src/cli/index.ts pnpm -C dreamlake-server exec vitest run src/routes/notesBody.test.ts
```

- Native skill packaging passed isolated binary build/install/readback/conflict/update.
- Existing UI cursor/activity tests: five passed. A local served fixture replayed
  the accepted HTTP receipt (timestamps refreshed for inspection) through the
  production awareness-to-cursor renderer. The matched passage highlighted with
  the agent label, expired, and left the human cursor at 0:0. This is component
  acceptance, not a live authenticated RTC end-to-end check. No user note was used.

Release order: server section metadata before or with CLI publication, then
matching docs and public skill source synchronization. Before publication,
regenerate skills against combined current docs to preserve concurrent changes.
The initial local checks above preceded deployment. Current release receipts follow.

### Negative occurrence follow-up

`-o -1` selects the last match; `-o -2` selects the second-last in the selected
scope. Receipts retain a positive resolved occurrence. Focused tests cover negative
bounds, Unicode section offsets and real CLI argument parsing into the HTTP route.

Receipts now return the exact matched text, scope and resolved match number/count
in plain text and JSON, so callers can confirm what was selected without a reread.

### Plain-text default

Notes guides now explicitly require plain text for ordinary human and coding-agent
workflows, including selection receipts and examples. JSON remains opt-in for
explicit structured consumers; scripted revision/concurrency examples retain it
where parsing is required. Regenerate the public Notes and CLI references from
these source docs. No command behavior or release status changes.

### Release receipts — 2026-09-26

- Workspace #788 merged at `13b781e29a70015e94349000ff1bb0856e64543c`; full server CI passed.
- CLI #152 merged at `53ddc4e76eb6a5c3c71b46dbe892788bfbd0b1d4` (0.32.0).
- Staging deployment `36286624357` succeeded. Live acceptance verified scoped `-o -1` selecting match 3 of 3, ambiguity/bounds/stale refusal, real RTC presence, visible highlighting and expiry, and unchanged source/hash/revision. The dedicated staging fixture was cleaned up.
- Docs 0.1.29 deployed as `6ab8779284f6d68e90619a79`; production and permanent version pages matched generated source exactly.
- CLI docs 0.32.0 deployed as `6ab8767768ad7d5a3ab2cc9f`; live pages matched generated source exactly.
- Public skills #63 merged at `766c740`; a fresh public clone matched all 46 generated files and committed source revisions.
- Production server deployment `36287150511` and CLI 0.32.0 publication `36287434262` completed successfully; final live and downloaded-package verification is recorded below.

Production acceptance passed at 2026-09-27T02:07Z against `13b781e`:
scoped `--section next-steps -o -1` selected the last `simulation`, match 3 of 3,
at global code-point range `[108,118)`. The CLI refused ambiguity, no match,
out-of-range negative occurrence and stale hashes. Live authenticated RTC/browser
highlighting matched the receipt, and source/hash/revision stayed unchanged.
Production deployment `36287150511` and staging deployment `36286624357` both
completed successfully at the same `13b781e29a70015e94349000ff1bb0856e64543c`
commit. Health checks passed, and production highlight expiry was also verified.
CLI 0.32.0 publication `36287434262` completed successfully from
`53ddc4e76eb6a5c3c71b46dbe892788bfbd0b1d4`. Fresh native and npm installs both
reported 0.32.0 and matched all 44 bundled skill files; the native checksum and
size matched the public manifest. The downloaded native binary repeated the live
production selection/RTC/browser/expiry checks with unchanged source/hash/revision.
The distribution check passed for `latest`, `stable`, the installer, and all eight
platform binaries. Both synthetic notes returned 404 after soft deletion, the
temporary share was revoked, and test tabs/worktrees were cleaned up.