Getting Started

🚀 Getting Started with Waldiez¶

You can use Waldiez in one of the following ways — pick the one that works best for you:

1. 🌐 Use the Playground – no installation required
2. 🐍 Install from PyPI – for full control and customization
3. 🐳 Use Docker – no setup, great for reproducibility
4. 📦 Use the JupyterLab extension – for interactive notebooks
5. 🖥️ Use the Visual Studio Code extension – for a familiar IDE experience
6. 🎬 Use Waldiez Studio – for a FastAPI-based web UI

🌐 1. Use the Playground (No Installation Required)¶

You can visit the Playground at: https://waldiez.github.io

You can:

• 🧩 Design and edit Waldiez flows visually
• 🔗 Share flows with others
• ✅ Test layout and logic before running locally

🐍 2. Install from PyPI (Recommended for Full Functionality)¶

If you want to create, convert, and run Waldiez flows locally — with full flexibility — install Waldiez using pip.

This option gives you:

• ✅ Full access to the Python API and CLI
• 🧪 Integration with JupyterLab and Waldiez Studio
• 🖥️ Local development with VS Code

📦 Basic Installation¶

(Optional but highly recommended) Create and activate a virtual environment¶

python3 -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\Activate.ps1 on Windows
# Upgrade pip (optional)
python -m pip install --upgrade pip
# Install the core Waldiez package
pip install waldiez

➕ Optional Extras¶

Install with extras depending on how you want to work:

# JupyterLab integration
pip install waldiez[jupyter]  # or pip install waldiez-jupyter

# Waldiez Studio (FastAPI-based web UI)
pip install waldiez[studio]  # or pip install waldiez-studio

# Both
pip install waldiez[studio,jupyter]

🐳 3. Use Docker (No Setup Required)¶

If you don’t want to install Python or manage dependencies, you can use Waldiez directly from prebuilt container images.

This option gives you:

• ✅ Full functionality without installing anything
• 📦 Easy integration in CI, testing, or isolated dev environments
• 🔁 Reproducible setup across teams

🪟 Windows (PowerShell with Docker or Podman Desktop)¶

$flow = "C:\Users\YourName\Documents\flow.waldiez"
$output = "C:\Users\YourName\Documents\waldiez_output"

# Convert a flow to Python
docker run --rm `
  -v "$flow:/flow.waldiez" `
  -v "$output:/output" `
  waldiez/waldiez convert --file /flow.waldiez --output /output/flow.py

# Convert and run it
docker run --rm `
  -v "$flow:/flow.waldiez" `
  -v "$output:/output" `
  waldiez/waldiez run --file /flow.waldiez --output /output/output.py

🐧 Linux/macOS/WSL (Docker or Podman)¶

# Convert a flow to a Python script
docker run --rm \
  -v $(pwd)/flow.waldiez:/flow.waldiez \
  -v $(pwd)/output:/output \
  waldiez/waldiez convert --file /flow.waldiez --output /output/flow.py

# Convert to a Jupyter Notebook instead
docker run --rm \
  -v $(pwd)/flow.waldiez:/flow.waldiez \
  -v $(pwd)/output:/output \
  waldiez/waldiez convert --file /flow.waldiez --output /output/flow.ipynb

# Convert and immediately run it
docker run --rm -it \
  -v $(pwd)/flow.waldiez:/flow.waldiez \
  -v $(pwd)/output:/output \
  waldiez/waldiez run --file /flow.waldiez --output /output/output.py

📦 4. Use the JupyterLab Extension (for Interactive Notebooks)¶

If you're already working in JupyterLab or prefer a notebook-based environment, you can use the official Waldiez extension.

This gives you:

• 🖥️ A visual flow editor directly inside JupyterLab
• 📤 Export flows to .py or .ipynb
• ▶️ Run flows from within the notebook environment

🚀 Install with Jupyter support¶

If you installed Waldiez from PyPI, add the [jupyter] extra:

# Option 1: Fresh install
pip install waldiez[jupyter]

# Option 2: Add it to an existing install
pip install waldiez-jupyter

If you’re using the waldiez/jupyter Docker image, the Waldiez extension is already preinstalled. To launch it, run:

docker run -it -p 8888:8888 -v ${PWD}/notebooks:/home/user/notebooks waldiez/jupyter

This will start a JupyterLab server and mount the notebooks directory from your host machine to the container. You can then open your browser at http://localhost:8888 and start using Waldiez.

▶️ Launch the Waldiez UI inside JupyterLab¶

Once installed, you can either:

# Use the CLI to open JupyterLab with the extension:
waldiez lab

# Or just launch JupyterLab normally:
jupyter lab

❓ Extension not loading?¶

Make sure you're running JupyterLab from the same environment where Waldiez is installed. If needed, you can reinstall or enable the extension manually:

jupyter labextension install waldiez
# can also check the currently installed and enabled extensions with:
jupyter labextension list

from waldiez import WaldiezRunner

# Load your flow from a file
runner = WaldiezRunner.load("flow.waldiez")

# Run it and write the output to a script
runner.run(output_path="output.py")

🖥️ 5. Use the Visual Studio Code Extension (Familiar IDE Experience)¶

If you’re a VS Code user, you can work with Waldiez flows right inside your IDE using the official extension.

This gives you:

• 🧩 A drag-and-drop flow editor inside VS Code
• 📂 Open .waldiez files directly
• 💾 Save, edit, and share flows as files
• Convert and run flows if a valid python interpreter exists.

📥 Install the Extension¶

You can install the extension directly from the VS Code Marketplace:

1. Open the Extensions panel (Ctrl+Shift+X or Cmd+Shift+X on MacOS)
2. Search for: Waldiez and install it

Marketplace link:
🔗 https://marketplace.visualstudio.com/items?itemName=Waldiez.waldiez-vscode

Source code repo:
🔧 https://github.com/waldiez/vscode

🎬 6. Use Waldiez Studio (FastAPI-based Web UI)¶

Waldiez Studio is a lightweight local web application that allows you to:

• 🧩 Create and edit flows using a visual UI
• ▶️ Run flows and see output directly in the browser
• 📤 Export flows to Python or Jupyter formats

🚀 Installing Waldiez Studio¶

If you're using PyPI, install the [studio] extra:

pip install waldiez[studio]
# or
pip install waldiez-studio

If you’re using Docker, pull the waldiez/studio image:

docker pull waldiez/studio

🚀 Running Waldiez Studio¶

You can run Waldiez Studio using the command line:

waldiez studio --help

# example output (from typer ❤️):

# Usage: waldiez studio [OPTIONS]

# --host                TEXT        The host to run the server on [default: localhost]
# --port                INTEGER     The port to run the server on [default: 8000]
# --reload --no-reload              Reload the server on file changes [default: no-reload]
# --log-level
#                      [CRITICAL|ERROR|WARNING|INFO|DEBUG]  The log level [default: INFO]
# --domain-name         TEXT        [default: localhost]
# --trusted-hosts       TEXT        [default: []]
# --trusted-origins     TEXT        [default: []]]
# --force-ssl --no-force-ssl        Force SSL [default: no-force-ssl]
# --version                         Show the version
# --help -h                         Show this message and exit.

A typical usage would be:

waldiez studio --host 0.0.0.0 --port 8000

You can then open your browser and navigate to: 🔗 http://localhost:8000

waldiez studio --trusted-hosts example.com

🧪 Advanced Usage¶

🐍 Using the Python API¶

You can load, convert, and run .waldiez flows directly in Python.

Export a flow¶

from waldiez import WaldiezExporter

flow_path = "/path/to/flow.waldiez"
output_path = "/path/to/output.py"  # or .ipynb

exporter = WaldiezExporter.load(flow_path)
exporter.export(output_path)

Run a flow¶

from waldiez import WaldiezRunner
from waldiez import WaldiezRunner

flow_path = "/path/to/flow.waldiez"
output_path = "/path/to/output.py"

runner = WaldiezRunner.load(flow_path)
runner.run(output_path=output_path)

🧰 Using the Command Line

Waldiez also includes a CLI for converting and running flows:

# Convert a .waldiez flow to a Python script or Jupyter notebook
waldiez convert --file /path/to/flow.waldiez --output /path/to/output.py

# Convert and run (with optional --force if output exists)
waldiez run --file /path/to/flow.waldiez --output /path/to/output.py --force

➡️ That's it! Now that you're set up, learn how to use Waldiez →