Kiro IDE and Kiro CLI can each be redirected to a self-hosted update server so you control which versions reach your fleet. The two products use separate, independent mechanisms — configure whichever surfaces your organization runs.
Control which Kiro IDE versions reach your users by hosting a self-managed update site. Set the UpdateUrl managed policy to point Kiro at your server, serve per-platform JSON manifests, and host the installer binaries anywhere reachable over HTTPS.
Set the UpdateUrl policy to your server's base URL.
Use macOS managed preferences to set the policy:
sudo defaults write dev.kiro.desktop UpdateUrl -string "https://updates.example.com"
Or deploy via an MDM profile targeting the dev.kiro.desktop domain.
| Requirement | Detail |
|---|---|
| Scheme | https:// only. Non-HTTPS or malformed values are logged and Kiro falls back to the built-in default. |
| Trailing slash | Stripped automatically. |
| When it applies | Resolved at startup — restart Kiro for the change to take effect. |
| UpdateMode | UpdateMode=none always wins and disables updates entirely, regardless of UpdateUrl. |
Kiro requests a JSON manifest at a per-platform path built from the base URL, channel, OS, and architecture:
| Platform | Path |
|---|---|
| macOS | {base}/{quality}/metadata-darwin-{arch}-{quality}.json |
| Linux | {base}/{quality}/metadata-linux-{arch}-{quality}.json |
| Windows | {base}/{quality}/metadata-{win-variant}-{quality}.json |
Where:
{quality} is the release channel — always stable for self-hosted update servers{arch} is x64 or arm64{win-variant} is win32-{arch} plus an install-type suffix: -system (default), -user, or -archive (portable)Examples:
https://updates.example.com/stable/metadata-darwin-arm64-stable.jsonhttps://updates.example.com/stable/metadata-win32-x64-user-stable.jsonhttps://updates.example.com/stable/metadata-linux-x64-stable.jsonKiro appends ?bg=true on automatic background checks. Your server can safely ignore this parameter.
Kiro reads the first entry in releases. Here is an example manifest:
{ "currentRelease": "1.2.0", "releases": [ { "version": "1.2.0", "updateTo": { "version": "1.2.0", "pub_date": "2026-07-10", "notes": "Kiro-darwin-arm64-1.2.0", "name": "Kiro-darwin-arm64-1.2.0", "url": "https://updates.example.com/releases/stable/darwin-arm64/signed/1.2.0/kiro-ide-1.2.0-stable-darwin-arm64.zip" } } ] }
| Field | Description |
|---|---|
currentRelease | Latest release version string |
releases[0].version | Compared against the installed version — an update is offered only if this is greater |
releases[0].updateTo.url | Download URL for the signed binary. Must be HTTPS. Does not need to share the manifest's host. |
updateTo.pub_date | Publish date in YYYY-MM-DD format |
updateTo.name / notes | Metadata shown to the user in the update prompt |
| Platform | Binary type |
|---|---|
| macOS | Signed .zip — downloaded, installed, and relaunched automatically |
| Windows | .exe installer — Kiro downloads and launches it directly |
| Linux | Archive URL — Kiro opens it in the default browser for manual install |
Release to a pilot group first, then roll out organization-wide after a validation period.
Step 1: Mirror the release
When a new Kiro version is published, download the installer binaries from prod.download.desktop.kiro.dev and create manifests pointing to your hosted copies.
Step 2: Pilot group
Configure your pilot group's machines with UpdateUrl pointing to a manifest that advertises the new version:
{ "currentRelease": "1.3.0", "releases": [ { "version": "1.3.0", "updateTo": { "version": "1.3.0", "pub_date": "2026-07-15", "notes": "Kiro-darwin-arm64-1.3.0", "name": "Kiro-darwin-arm64-1.3.0", "url": "https://updates.example.com/releases/stable/darwin-arm64/signed/1.3.0/kiro-ide-1.3.0-stable-darwin-arm64.zip" } } ] }
Step 3: Validate
Monitor the pilot group for issues over your validation period (commonly 3–7 days).
Step 4: Broad rollout
Update the manifests on your production endpoint to advertise the new version. All remaining users receive the update on their next check.
To hold your fleet on a specific version, set releases[0].version to the version your fleet currently runs. Kiro only offers an update when the manifest version is greater than the installed version, so advertising the same version effectively pins it.
This controls the auto-update check only — it does not prevent a user from manually installing a different version. To fully lock versions, combine pinning with network controls that block access to the official download server.
Set UpdateMode=none via managed policy (same delivery mechanism as UpdateUrl). When UpdateMode is none, Kiro skips all update checks regardless of the UpdateUrl value.
You can combine the UpdateUrl policy with firewall rules to ensure Kiro can only reach your internal update server. Block outbound access to prod.download.desktop.kiro.dev and allow your custom endpoint only. This guarantees that no user bypasses your version governance.
Redirect Kiro CLI updates to your own server by setting a managed update.baseUrl policy value. On a managed machine, an enforced policy takes precedence over other release-URL configuration.
Set the update.baseUrl policy to your release server root.
Deploy update.baseUrl as a forced value in the dev.kiro.cli managed preference domain through an MDM configuration profile.
Non-forced (user-level) values in this domain are ignored, so a local defaults write does not take effect on a managed machine.
A base URL may include a path prefix (for example, https://artifacts.example.com/mirrors/kiro-cli). Trailing slashes are normalized. Values that fail URL validation are ignored in favor of the default release server.
An enforced update.baseUrl policy takes precedence over other release-URL configuration.
Kiro CLI fetches release metadata from your server to decide whether to update. The file it requests and the schema it expects differ by platform, so a mirror must serve the right file for each platform you support. Each packages[].download is a path resolved relative to your base URL.
macOS requests a cumulative version registry at <base>/index.json:
{ "supported": [ { "architecture": "universal", "targetTriple": "universal-apple-darwin", "variant": "full", "fileType": "dmg" } ], "versions": [ { "version": "2.13.0", "packages": [ { "kind": "dmg", "os": "macos", "architecture": "universal", "targetTriple": "universal-apple-darwin", "variant": "full", "fileType": "dmg", "download": "2.13.0/KiroCLI.dmg", "sha256": "0000000000000000000000000000000000000000000000000000000000000000", "size": 52428800, "channel": "stable" } ], "rollout": { "start": 1731000000, "end": 1731600000 }, "updateConditions": [{ "allowedAutoUpdateProductNames": ["Kiro CLI"] }] } ] }
The registry is cumulative — it lists every version released to the channel, and requires a top-level supported array describing the build targets you publish. Every supported item requires architecture and variant (targetTriple, os, and fileType are optional selection fields); macOS ships a DMG. rollout is a { start, end } window in epoch seconds, and updateConditions gate automatic updates — the product value Kiro CLI is the case-sensitive wire value. Replace sha256 and size with your artifact's digest and byte count.
A mirror must serve the metadata file for each platform plus the artifact files its packages[].download paths declare:
<base>/index.json # cumulative version registry <base>/<version>/<artifact> # artifact files at the paths packages[].download declare
download paths resolve relative to <base>, so a mirror controls its own artifact layout by writing matching paths in the metadata it hosts.
By default, Kiro CLI only updates to a version newer than the one installed, so you govern rollout through the metadata your mirror serves (on Windows, --force can override this):
Before rollout.start, Kiro CLI does not select the version. At or after the start, a plain kiro-cli update bypasses staged percentage selection, while kiro-cli update --rollout follows it. Both manual forms ignore updateConditions. Automatic updates follow rollout timing and enforce updateConditions. To pin, don't publish a versions[] entry higher than the release your fleet runs.
Set app.disableAutoupdates to disable automatic updates:
kiro-cli settings app.disableAutoupdates true
On Windows, defining the KIRO_NO_AUTO_UPDATE environment variable with any value also disables background updates.
The options for kiro-cli update differ by platform:
Supports --non-interactive, --relaunch-dashboard, and --rollout. It does not accept --check or --force.
Pair the update.baseUrl policy with firewall rules so Kiro CLI can only reach your mirror. Block outbound access to the default CLI download endpoints and allow your mirror's host instead:
prod.download.cli.kiro.dev — CLI downloads and updatesdesktop-release.q.us-east-1.amazonaws.com — CLI installer downloadsBlocking the default download endpoints prevents Kiro CLI's built-in updater and installer from falling back to them. Use additional software-distribution controls if your organization must prevent users from installing releases through other sources.
Managed updates