Install it

dqx is a single binary, about 62 MB - it carries its own runtime, so there is nothing else to install for dqx itself. It needs a backend to drive - Docker Desktop unless you have chosen otherwise - and it will tell you what else is missing rather than failing halfway.

curl -fsSL https://dqx.dolphiq.nl/install.sh | bash

macOS today

Both Mac architectures are published. Linux and Windows builds exist and are tested but are not published yet - dqx self-update says so plainly rather than failing at a download.

What it checks before you start

The first dqx install in a project checks the machine, not just the project. A clean Mac otherwise gets through cloning, composer and npm and then fails at up with a Docker socket error, having never said the word "install".

It looks for, and offers to install:

• the backend - Docker Desktop, or DDEV, Lerd or Herd if the project pins one
• mkcert and its root certificate, so https:// on a local domain is green rather than a warning
• a resolver for the suffixes dqx serves - .dqx by default

It names every command before running it. Nothing is installed behind your back.

Keeping it up to date

dqx self-update

It reads the release manifest, compares versions, and replaces the binary in place. A dashboard that is running is restarted onto the new binary.

You are told when there is one. dqx up, install, sync and switch print one line when a newer release is out, dqx doctor has a latest line, and the dashboard shows a strip above its header. The manifest is read at most every six hours, with a short timeout, so a command is never slower for it and nothing is said without a network. It is never printed into --json, into a pipe or in CI; DQX_NO_UPDATE_CHECK=1 turns it off. A checkout and a build of one are never told - they update by pulling.

What it verifies before it does. The manifest publishes a sha256 per asset. dqx hashes what it downloaded and refuses to install anything that does not match, before the file is made executable and before it is moved into place - so the current binary survives a bad download untouched. It also refuses a manifest that publishes no checksum at all, and it will only fetch an asset from the same host the manifest itself came from: a manifest may point within its own host and nowhere else.

TLS alone is not that. It says the bytes arrived from that host unmodified; it says nothing about what the host is serving, and an update replaces the binary every other command runs through.

If DQX_RELEASE_MANIFEST is set - staging and the tests use it - dqx prints the host it is reading, because an override decides what gets installed and should never be silent.

An older version

When the newest release breaks something for you, go back one while it is fixed:

dqx self-update --previous        # the release before the one you run
dqx self-update --to 1.58.0       # a release by its number

Without a working dqx, the install script takes the same number:

curl -fsSL https://dqx.dolphiq.nl/install.sh | bash -s -- --to 1.58.0

The host keeps the last five releases; Releases has the line for each, and https://dqx.dolphiq.nl/releases.json lists exactly which. A number it no longer keeps is refused with the ones it does. An older release is checked against its sha256 like the newest.

Going back is said as such (Going back 1.59.0 → 1.58.0.). The update notice then stays quiet about the release you left, and speaks again once a newer one is out; dqx doctor shows the hold. Plain dqx self-update returns to the newest. A project whose requires is above the release you pick gets a warning first: that dqx will refuse to work on it until you update again.

Per project

Nothing to install. In a project that already uses dqx:

cd ~/projects/some-project
dqx install

That clones what is missing, generates the environment, starts it, and runs the project's own install steps. It checks it can reach every repository before it starts, so a missing SSH key fails in the first second rather than the tenth minute.

A project's config is code

Those install steps come from the project's own .dq/config.yml, and dqx run runs its commands: the same way - through a shell inside its container, with your SSH agent and your mounted home directory in reach. Installing a repository you have just cloned trusts that repository the way npm install does. dqx doctor lists what a config would run, so you can read it first.

If something goes wrong

"dqx cannot be opened because the developer cannot be verified." The binary carries an ad-hoc signature rather than a Developer ID one - it is built and signed by the release pipeline, which has no Apple account and no way to notarise. macOS then decides by how the file arrived: fetched with curl it is not flagged, saved through a browser it gets com.apple.quarantine and Gatekeeper refuses it. Use the command at the top of this page and it never arises. If it already has:

xattr -d com.apple.quarantine ~/Downloads/dqx-darwin-arm64
chmod +x ~/Downloads/dqx-darwin-arm64

Nothing about the file changes - the same binary, minus the note saying where it came from.

It installed but the shell cannot find it. The installer puts the binary in ~/.local/bin. If that is not on your PATH, add it:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && exec zsh

self-update says your platform is not published. Linux and Windows builds exist and pass their tests, but nothing publishes them yet. Building from a checkout works everywhere: bun install && bun run link.

You are reading this on staging. The install line carries the address of the site it is on, so a staging page installs the staging build and that binary keeps reading staging's manifest. Deliberate: somebody testing a release is not silently updated back to the previous one.

You are working on dqx itself. A checkout can take over the dqx on your PATH and give it back again - see Running your checkout. dqx version --where says which of the three you are running.

Anything else - dqx doctor checks the machine as well as the project, and names what it finds rather than what it suspects.

How the Mac binaries are built

Cross-compiled on Linux, which is less of a trick than it sounds: bun takes the runtime for the target and appends the bundle, and the result is a Mach-O arm64 carrying the ad-hoc signature Apple Silicon requires to run anything at all. Verified by building one in the release image and running it on a Mac - config get, sites and generate all answered, embedded templates included.

Removing it

Removing dqx covers the binary, its state, the router, and the two things it asks of your system that outlive it.