Skip to content

Quickstart

You will create a workspace, generate keys, push a build and update a test device. Allow about 40 minutes.

1. Install the CLI

npm install --global @verdel/cli
verdel --version
# verdel 4.12.1 (darwin-arm64)

The CLI is a single static binary also available as a Homebrew formula, a winget package and a deb or rpm. Check your install with verdel doctor; it reports clock skew, proxy settings and whether your network allows the upload endpoint.

2. Create keys

verdel keys init --workspace acme-desktop
# root key   written to ./keys/root.ed25519   (move this offline now)
# targets key written to ./keys/targets.ed25519
# public metadata uploaded: root.json v1, expires 2027-11-05

Move the root key to offline storage immediately, for example a hardware token. Verdel never receives private keys, so a lost root key cannot be recovered; it can only be replaced through a rotation you perform yourself.

3. Describe a channel

Add a verdel.toml to your repository. The smallest useful policy has one channel and the default rings.

[app]
id        = "acme-notes"
platforms = ["windows-x64", "macos-universal", "linux-x64"]

[channel.stable]
rings   = ["canary:1", "early:5", "broad:25", "all:100"]
hold    = "6h"
halt_if = { crash_rate = 0.5, install_failure = 2.0 }

4. Push a build

verdel push ./dist/AcmeNotes-2.8.0-x64.msi \
  --channel stable --version 2.8.0 --notes RELEASE_NOTES.md
# uploaded 118.4 MB in 9.1 s, 4 tiles reused from 2.7.3
# delta from 2.7.3: 6.2 MB, from 2.7.2: 11.8 MB
# manifest signed, release 2.8.0 is in ring canary (1%)

5. Check from a device

Use the agent in your app, or ask the API directly to see what a device on 2.7.3 would receive:

curl -s "https://nl5.enotcloud.com/api/v1/check?app=acme-notes&channel=stable&version=2.7.3&os=windows&arch=x64&device=d_test_01"

Test devices can be forced into any ring with verdel devices assign d_test_01 --ring canary, so you can see the update before the canary ring is opened to real users.

6. Widen the rollout

Do nothing and the rings advance on their hold timers if the halt thresholds are not crossed. To move faster, run verdel release advance acme-notes@2.8.0; to stop, run verdel release halt with a reason, which is shown to everyone in the workspace.

Next