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.