# 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**.