Why Veln’s default cooling period is 2 hours and 10 observations

When Veln blocks an install with a "cooling" message, the message points to two thresholds: the version is younger than min_version_age (default 2 hours) and has fewer than min_installs community observations (default 10). This post explains why those defaults are what they are and how to tune them for your environment.

What the gate enforces

The cooling gate runs before any other Veln check. For each package version about to be installed, the gate evaluates:

• Publication age. How long ago did this version appear on the registry?
• Community observations. How many independent Veln users have already installed this version?

If both are above the configured thresholds, the version proceeds to the next stage of analysis. If either is below, the install is held with a HOLD verdict, telling the developer the version is too new or too unobserved to auto-approve, and offering an approval path for cases where they have other reasons to trust the version.

Why two hours

Two hours is a deliberate compromise.

Shorter is more permissive. Below an hour, the gate doesn't meaningfully differentiate "version published just now" from "version published a few minutes ago, with no observations yet." Most malicious versions targeting fast-CI installs land within minutes; a sub-hour threshold catches some of them but lets through the ones that wait.

Longer is more disruptive. Above four hours, legitimate hotfix releases routinely fall into cooling for the entire workday for time-zone-dispersed teams. The friction starts to outweigh the benefit for most projects.

Two hours covers the median case where a malicious version is detected and pulled within the first hour or two, while leaving legitimate releases enough time to accumulate observations from teams in other time zones before becoming installable elsewhere.

Why ten observations

Ten observations is a per-package check that complements the time threshold.

The minimum signal value of a single observation. Each Veln user who installs a version contributes one observation. One observation tells you the package downloaded, executed install scripts (if any), and didn't immediately crash. It tells you nothing about whether the package was malicious — that's other checks. Ten observations provides a baseline of "this version has been touched by enough independent installs that visible misbehavior would have surfaced."

Why not 100? For low-volume packages, 100 observations can take days. The gate would block legitimate use of small packages excessively. Ten is a number that popular packages reach within minutes and small packages reach within a day, balancing across the volume spectrum.

Why not 3? Three observations is statistically thin. A coordinated attacker could plausibly accumulate three observations themselves to defeat the threshold. Ten raises the bar enough that self-observation is impractical without an obvious pattern.

When to lower the thresholds

Some environments warrant more permissive defaults.

Single-developer projects with low install volume. If you're the only Veln user for a private internal package, you may never reach ten observations. Lower min_installs to a number that fits your install pattern, or use approval paths for internal-package installs rather than cooling.

Air-gapped environments. Cooling depends on the platform's view of community observations. In air-gapped or self-hosted-platform setups, you may want shorter cooling because the platform isn't observing as widely.

Hotfix-heavy projects. Some projects routinely consume just-released versions because they coordinate closely with upstream. Lower thresholds for those specific dependencies, leaving the global default in place for everything else.

When to raise the thresholds

Some environments warrant stricter defaults.

Production CI for safety-critical software. Doubling the cooling window (4 hours, 25 observations) is a reasonable hardening for production deploys where a 4-hour wait on a new version is acceptable. Pair with explicit approval paths for emergencies.

High-target organizations. Organizations whose CI pipelines are likely targets — anyone in finance, defense, or with publicly visible large-scale infrastructure — should consider stricter thresholds combined with mandatory review on any new dependency addition.

How approval paths interact with cooling

Cooling is not absolute. When a HOLD fires, a reviewer can approve the install explicitly with a justification note. Approvals are recorded, scoped to the package version, and surface in the Console's audit trail.

For most teams, the right mode is: cooling defaults catch routine new-version installs and force them through review; the developer or a reviewer explicitly approves when there's a known reason to install the new version anyway. The audit trail captures the decision.

Tuning syntax

Thresholds are set per-policy in your project's veln.toml (or globally in ~/.veln/config.toml):

[policy]
min_version_age = "2h"      # default
min_installs = 10           # default

For a stricter production policy:

[policy.production]
min_version_age = "6h"
min_installs = 25

Per-environment overrides activate based on VELN_ENV. Production CI sets VELN_ENV=production; the stricter thresholds apply automatically without affecting developer machines.

What the defaults are not

The cooling defaults are not a substitute for content review of a package's actual code. They are a delay-based defense that buys time for everyone else's review to complete. They don't tell you whether a package is malicious; they tell you whether it has been around long enough that someone else might have noticed if it was.

Pair cooling with the other Veln checks — community consensus, obfuscation detection, sandbox behavioral analysis — for the full picture. Cooling alone catches a lot; cooling with the other layers catches more.

Takeaway

Veln's cooling defaults — 2 hours, 10 observations — are calibrated against the median attack profile and the operational tolerance of routine releases. Most teams should leave them in place. Adjust if your environment has unusual install volumes or risk profiles, and use approval paths to handle the cases where you need to install a brand-new version anyway.