Skip to main content

New project

DAGZ isn't integrated into your project yet. This walks through the full setup for one engineer on the team; everyone else then follows Existing project.

1. Local environment​

DAGZ can be managed with the zb command-line tool. It runs the local daemon (which stores execution baselines and serves the dashboard) and provides commands to inspect jobs, tests, and coverage.

Install the binary:

curl -LsSf https://dagz.run/install.sh | bash

Start the local daemon in the background:

zb daemon up --bg

The daemon binds to loopback and to the Docker bridge by default, so containers on the default bridge reach it without --network=host. See the daemon config reference for ports, alternative bridge addresses, and extra listen interfaces.

Run zb at any time to see current status and recommended next steps:

zb

You'll see the status of your local environment and current project:

$ zb
=== DAGZ STATUS ===

environment:
  active:        local
  status:        daemon up
  uv:            installed

project: not in a git repo or DAGZ project

recommended next steps:
  cd into a project directory and re-run `zb`

(see `zb --help` for all commands)

2. Choose your run mode​

On macOS, install dagz in a Docker container and run tests there, while running the zb daemon natively on the host. The pytest plugin is unsupported on macOS and may not work correctly.

On Linux, run natively, or use the same Docker setup as on macOS for environment isolation.

3. Install dagz natively (Linux)​

Set up a Python virtual environment for your project:

cd YOUR_PYTHON_PROJECT
uv venv -p 3.12                       # supported: 3.10, 3.11, 3.12
uv pip install -r requirements.txt    # if you have a requirements file
uv pip install -e .                   # if your project is a package
zb                                    # show current state and next steps

Install dagz:

uv pip install dagz

4. Install in Docker (macOS)​

Run your tests in a Docker container that has your project's dependencies and dagz installed. Point pytest at the host daemon via DAGZ_URL:

docker run -it --rm \
  --user "$(id -u):$(id -g)" \
  --env DAGZ_URL=http://host.docker.internal:29111 \
  --add-host=host.docker.internal:host-gateway \
  -v "${PWD}:${PWD}:ro" \
  -w "${PWD}" \
  python:3.12-slim \
  bash

--add-host=host.docker.internal:host-gateway is required on Linux Docker. On macOS, Docker Desktop wires host.docker.internal automatically, so the flag is redundant but harmless.

For a worked example with pandas (Postgres + MariaDB inside the container, dagz pre-installed), see the pandas example.

5. Run tests​

Optional: configure DAGZ for your project​

DAGZ works with zero configuration. To customize, run:

zb init
zb

You can now edit .dagz/config.yaml. The file includes inline docs, and the Configuration reference covers every option.

Run your tests​

pytest --dagz

Useful flags for first runs:

  • --dagz-debug shows detailed logs from the plugin and runtime.
  • --dagz-workers=N sets the number of workers. The default is based on your hardware.

See pytest --help for the full list, and the pytest options reference for details.

6. Make a change and run again​

pytest --dagz

Preview which tests would be selected without running them:

zb select-tests

To see why each test was selected, add --trace:

zb select-tests --trace

7. Open the dashboard​

Visit http://localhost:29111 to see test results, which tests were skipped and why, and performance trends over time.

Supported platforms​

  • Linux: fully supported for both the pytest plugin and the zb CLI / daemon.
  • macOS: the zb CLI and local daemon work, but the pytest plugin is unsupported and may not work correctly. Run tests in a Linux Docker container against the daemon on your Mac (see section 4 above).
  • Windows: not supported.

Deployment options​

Individual use​

The local env is intended for one person's machine. Run zb eula to see the full license terms.

Team deployments​

For production environments and scale requirements, DAGZ provides a Helm chart and a Docker Compose file for deploying a team server on Kubernetes or a single host. Once it's deployed, connect to it with zb login.

Contact us at [email protected] for information on team deployments, pricing, and enterprise features.