Repository navigation
Sentry v2.0.1 — Windows Stable
An update from v2.0.0. It adds a choice of run depth (Fast or Full), a default run time limit, reasoning effort for every agent and new sentry cli settings commands, and fixes three bugs found by a QA run. There is no database migration: your projects, runs, history and provider settings are kept. Already on v2.0.0? Follow “Update an existing installation” below. Fresh installs follow the numbered steps in order.
Supported installation: Windows 11 x64 + WSL2, Ubuntu preferred. This is an unsigned ZIP with online Linux bootstrap, not an MSI/MSIX or offline installer. Setup requires internet and the Linux prerequisites below. Provider credentials are configured in Desktop; provider usage charges are separate.
What's new in 2.0.1
- Run depth: choose Fast (at most 3 planned checks) or Full (the default, as many as the time window allows, up to 8) on the project page or with
run start --depth fast|full. Both use the same window and the same extra passes, and the depth is shown on the run and in Findings by revision. - Run time limit: Settings → Runtime sets the window every run gets: 3 hours (default), 6 hours, No limit (7 days) or a custom value from 10 minutes. It is a ceiling, not a target, and it decides which extra passes still have time. The longest window a run can be given is now 7 days (it was 12 hours).
- Reasoning effort per agent in Settings → Providers, shown on the Environment page and on the project page's agent cards.
- CLI:
settings show,settings effort <agent> <level|default>andsettings run-limit <default|3h|6h|none|90m|12h>;run listandrun statusreport each run'sdepthandtimeLimitMs; the help lists every command. - Fixes: a symlink whose target contains a backslash is copied exactly on Linux and macOS; a finding title can no longer forge a status line in the human-readable log; a stored artifact whose path names the data root is refused before its database row is deleted.
- Interface: the ChatGPT sign-in choice is a two-button control; more Bulgarian translations; calmer yellow stripes where an agent hit a warning; the Details page no longer shows elapsed time.
1. WSL2 and Ubuntu
Run in PowerShell:
wsl.exe --list --verboseIf Ubuntu already exists, is initialized, and shows VERSION 2, keep it and continue. Otherwise run in PowerShell as Administrator:
wsl.exe --install -d UbuntuRestart if Windows requests it. Then use normal PowerShell:
wsl.exe --set-version Ubuntu 2
wsl.exe -d UbuntuComplete the Linux username/password prompts, then type exit to return to PowerShell. You do not need to remove WSL to install or update Sentry. See Microsoft WSL installation.
2. Linux prerequisites — commands from PowerShell
Skip this block if the selected Ubuntu already has Node >=22, pnpm 9.12.3, systemd user services, bubblewrap, and socat. Otherwise paste it into PowerShell. It installs packages inside Ubuntu using WSL root and the official NodeSource Node 22 repository when needed. If your distro has another name, change the Ubuntu selection in these blocks consistently.
& {
$ErrorActionPreference = 'Stop'
function Invoke-UbuntuRoot {
param([string[]]$LinuxArguments)
& wsl.exe -d Ubuntu -u root -- @LinuxArguments
if ($LASTEXITCODE -ne 0) { throw 'Ubuntu prerequisite installation stopped. Resolve the error before continuing.' }
}
function Get-UbuntuVersion {
param([string]$Tool)
try {
$version = & wsl.exe -d Ubuntu -- $Tool --version 2>$null
if ($LASTEXITCODE -eq 0) { return ([string]$version).Trim() }
} catch { }
return ''
}
Invoke-UbuntuRoot -LinuxArguments @('apt-get', 'update')
Invoke-UbuntuRoot -LinuxArguments @('apt-get', 'install', '-y', 'ca-certificates', 'curl', 'bubblewrap', 'socat', 'systemd', 'systemd-sysv')
$nodeVersion = Get-UbuntuVersion -Tool 'node'
if ($nodeVersion -notmatch '^v(\d+)\.' -or [int]$Matches[1] -lt 22) {
Invoke-UbuntuRoot -LinuxArguments @('install', '-d', '-m', '700', '/root/.cache/sentry-bootstrap')
Invoke-UbuntuRoot -LinuxArguments @('curl', '-fsSL', 'https://deb.nodesource.com/setup_22.x', '-o', '/root/.cache/sentry-bootstrap/node22.sh')
Invoke-UbuntuRoot -LinuxArguments @('bash', '/root/.cache/sentry-bootstrap/node22.sh')
Invoke-UbuntuRoot -LinuxArguments @('apt-get', 'install', '-y', 'nodejs')
}
$pnpmVersion = Get-UbuntuVersion -Tool 'pnpm'
if ($pnpmVersion -cne '9.12.3') {
Invoke-UbuntuRoot -LinuxArguments @('npm', 'install', '--global', 'pnpm@9.12.3')
}
$nodeVersion = Get-UbuntuVersion -Tool 'node'
if ($nodeVersion -notmatch '^v(\d+)\.' -or [int]$Matches[1] -lt 22 -or
(Get-UbuntuVersion -Tool 'pnpm') -cne '9.12.3') {
throw 'Node >=22 or pnpm 9.12.3 is unavailable inside Ubuntu. Installation stopped.'
}
& wsl.exe -d Ubuntu -- systemctl --user show-environment
if ($LASTEXITCODE -ne 0) {
throw 'Ubuntu systemd user services are unavailable. Follow the systemd guidance below, then rerun this block.'
}
Write-Host 'Ubuntu prerequisites installed. Continue with Install Sentry below.'
}If systemd user services are unavailable, follow Microsoft systemd guidance, preserving existing WSL configuration, and rerun the check.
3. Fresh install — download, verify, setup, and open
Paste the entire block into normal PowerShell from any folder, including System32. It automatically downloads the exact ZIP and checksum, verifies the pinned ZIP hash, manifest hash, full source identity, and every distribution file before executing the launcher, extracts into a separate version/source directory, sets up the matching runtime, provisions the pinned tools, and opens Desktop. A failure stops subsequent steps. Existing matching installation files are verified and reused; a tampered directory is refused.
& {
$ErrorActionPreference = 'Stop'
$name = 'sentry-2.0.1-3db5b49985a8-windows-x64'
$expectedHash = '29d06240ce5079161144b9879481c6ccdcfffa282b95ecf224bdfbd16c9a53ce'
$expectedManifest = '326ec379f62723cd2b4874e28abae8b748eb72b1495575d738a4e5be195d4619'
$source = '3db5b49985a8218350d227e9dbe87ff232f35a5e'
$download = Join-Path $env:USERPROFILE 'Downloads\Sentry-v2.0.1'
$destination = Join-Path $env:LOCALAPPDATA 'Sentry\releases'
$installation = Join-Path $destination $name
$zip = Join-Path $download ($name + '.zip')
$checksum = $zip + '.sha256'
$url = 'https://github.com/Mert1026/Sentry/releases/download/v2.0.1/'
New-Item -ItemType Directory -Path $download, $destination -Force | Out-Null
Write-Host 'Downloading the official ZIP and checksum...'
Invoke-WebRequest -UseBasicParsing -Uri ($url + $name + '.zip') -OutFile $zip
Invoke-WebRequest -UseBasicParsing -Uri ($url + $name + '.zip.sha256') -OutFile $checksum
if (-not (Test-Path -LiteralPath $zip -PathType Leaf) -or
-not (Test-Path -LiteralPath $checksum -PathType Leaf)) {
throw 'The ZIP or checksum file is missing. Installation stopped.'
}
$sidecarHash = ((Get-Content -LiteralPath $checksum -Raw).Trim() -split '\s+')[0]
$actualHash = (Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash
if ($sidecarHash -notmatch '^[a-fA-F0-9]{64}$' -or
$sidecarHash -ine $expectedHash -or $actualHash -ine $expectedHash) {
throw 'Checksum verification failed. Installation stopped.'
}
if (-not (Test-Path -LiteralPath $installation)) {
Expand-Archive -LiteralPath $zip -DestinationPath $destination
}
$manifestPath = Join-Path $installation 'distribution.json'
if ((Get-FileHash -LiteralPath $manifestPath -Algorithm SHA256).Hash -ine $expectedManifest) {
throw 'Distribution manifest mismatch. Installation stopped.'
}
$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
if ($manifest.sourceCommit -cne $source -or $manifest.version -cne '2.0.1' -or
$manifest.runtimeProtocol -ne 1 -or $manifest.targetPlatform -cne 'windows-x64') {
throw 'Release identity mismatch. Installation stopped.'
}
foreach ($file in $manifest.files.PSObject.Properties) {
$path = Join-Path $installation $file.Name
if ((Get-FileHash -LiteralPath $path -Algorithm SHA256).Hash -ine $file.Value) {
throw ('Distribution file mismatch: ' + $file.Name)
}
}
Write-Host 'Approved checksum, manifest, source identity and files verified.'
$launcher = Join-Path $installation 'sentry.ps1'
foreach ($step in @('version', 'setup', 'tools', 'open')) {
Write-Host ('Sentry: ' + $step)
if ($step -in @('setup', 'tools')) {
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File $launcher $step -Distro Ubuntu
} else {
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File $launcher $step
}
if ($LASTEXITCODE -ne 0) {
throw ('Sentry ' + $step + ' stopped. Resolve the reported error, then paste this block again.')
}
}
Write-Host ('Installed at: ' + $installation)
Write-Host 'Check Environment is Connected. Provider requests can incur charges.'
$env:Path += ";$env:LOCALAPPDATA\Sentry\bin"
Write-Host "Use sentry open, sentry status, sentry doctor or sentry version from any folder."
}Keep the installed directory under %LOCALAPPDATA%\Sentry\releases; it is the application. Configure Settings → Providers, then check Environment is Connected and provider readiness. Installation/readiness checks do not start paid QA. A capabilities handshake alone does not establish runtime/provider readiness.
4. Update an existing installation — v2.0.0 to v2.0.1
This is the update most people need. There is no automatic updater: you run one verified block, which downloads the exact new ZIP and checksum, verifies them, sets up the matching Linux runtime, installs the pinned tools and registers the new sentry command.
What is kept: your projects, managed copies, runs, findings, evidence, exports, history and provider settings. What does not happen: no database migration, no change to your credentials, no deleting WSL or user data. The old v2.0.0 archive and runtime stay in place until you remove them.
- Finish active QA/re-tests or cancel them, and wait until they settle. Check Environment for your actual distro and data root.
- Stop Sentry and back up your data. Run the stopped-backup block below in PowerShell. It uses the standard current-user locations; change
$distroand$linuxDataif yours differ, and make sure there is room for a full backup. The backup is your only safe way back (see “Going back” below). - Run the same complete v2.0.1 install block from step 3. It selects the new archive through setup and command registration. Do not extract over the old version.
- Check the result in a new PowerShell window with the commands after the backup block. The version must be 2.0.1 and the source commit must match the identity at the bottom of this page.
If your older installation has no registered sentry command, replace & sentry stop in the backup block with & powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\path\to\previous-installation\sentry.ps1" stop, using its actual absolute path.
& {
$ErrorActionPreference = 'Stop'
# Use the distro and absolute data root shown by Sentry Environment.
$distro = 'Ubuntu'
$linuxData = (& wsl.exe -d $distro -- sh -c 'printf "%s/.local/share/sentry" "$HOME"').Trim()
if ($LASTEXITCODE -ne 0 -or -not $linuxData.StartsWith('/')) { throw 'Cannot determine Linux data root.' }
# If Environment shows a custom root, replace $linuxData above with that root.
& sentry stop
if ($LASTEXITCODE -ne 0) { throw 'Sentry must stop before backup.' }
& wsl.exe -d $distro -- sh -c 'if pgrep -f "[a]pps/runtime/dist/host.js" >/dev/null; then exit 1; fi'
if ($LASTEXITCODE -ne 0) { throw 'A runtime is still active. Close every Sentry instance first.' }
$backup = Join-Path ([Environment]::GetFolderPath('MyDocuments')) ('Sentry Backup ' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
New-Item -ItemType Directory -Path $backup -ErrorAction Stop | Out-Null
$linuxBackup = (& wsl.exe -d $distro -- wslpath -u ($backup.Replace('\', '/'))).Trim()
if ($LASTEXITCODE -ne 0 -or -not $linuxBackup.StartsWith('/')) { throw 'Backup path translation failed.' }
& wsl.exe -d $distro -- tar -czf ($linuxBackup + '/runtime-data.tar.gz') -C $linuxData .
if ($LASTEXITCODE -ne 0) { throw 'Linux backup failed. Do not upgrade yet.' }
& wsl.exe -d $distro -- tar -tzf ($linuxBackup + '/runtime-data.tar.gz') > $null
if ($LASTEXITCODE -ne 0) { throw 'Linux backup verification failed.' }
$profile = Join-Path $env:APPDATA '@qa\desktop'
if (-not (Test-Path -LiteralPath $profile -PathType Container)) { throw 'Desktop profile not found; check the actual profile location.' }
Copy-Item -LiteralPath $profile -Destination (Join-Path $backup 'desktop-profile') -Recurse -ErrorAction Stop
foreach ($part in @('launcher', 'bin')) {
$path = Join-Path $env:LOCALAPPDATA ('Sentry\' + $part)
if (Test-Path -LiteralPath $path) { Copy-Item -LiteralPath $path -Destination (Join-Path $backup $part) -Recurse -ErrorAction Stop }
}
Write-Host ('Stopped backup saved at: ' + $backup)
}After installing:
sentry version
sentry status
sentry doctor
sentry open
sentry cli capabilities --json
sentry cli project list --json
sentry cli settings showVersion must be 2.0.1, the source must match the identity below, and Environment must be Connected. capabilities must list runDepth and settings. In Desktop, Settings → Runtime has a Run time limit, each agent card in Settings → Providers has a Reasoning effort, and the project page has a Run depth choice. Check that your own projects and runs are listed.
Going back to v2.0.0. Keep the stopped backup and the previous archive until you are satisfied. Going back is only safe from the backup: a run started with Fast depth under 2.0.1 stores a field that 2.0.0 does not know, and 2.0.0 reads run records strictly, so 2.0.0 may fail to list such runs. To go back, stop Sentry, restore the backup taken before the update, then run the v2.0.0 install block. Do not run 2.0.0 over data that 2.0.1 has written.
Updating from 1.x instead. Use the same blocks, but note that the 1.x → 2.x update has a one-way database migration that drops issue, retest and merge history (see the v2.0.0 notes). The backup is your only way back from that.
5. Everyday launcher commands
These are individual command examples. Once setup registers Sentry, they work from any folder in a new PowerShell or Command Prompt window.
| Command | Purpose |
|---|---|
sentry open |
Open Desktop; required before operational CLI commands. |
sentry stop |
Request graceful shutdown; wait for active work first. |
sentry version |
Display installed archive version and full source identity. |
sentry status |
Show archive identity/process summary; use Environment for runtime readiness. |
sentry doctor |
Show diagnostics guidance without paid requests. |
sentry setup -Distro Ubuntu |
Install/repair this archive's matching runtime; requires idle components. |
sentry tools -Distro Ubuntu |
Provision pinned provider tools; requires idle components. |
sentry register-command |
Register this selected archive's command after moving its directory. |
sentry help |
Show launcher commands. |
sentry cli --help |
Show operational CLI syntax. |
If an already-open PowerShell cannot find the command:
$env:Path += ";$env:LOCALAPPDATA\Sentry\bin"
sentry version
sentry openIf you move the archive, invoke its full launcher path to register the new location:
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $env:LOCALAPPDATA "Sentry\releases\sentry-2.0.1-3db5b49985a8-windows-x64\sentry.ps1") register-commandAdjust that path to where you moved it. sentry update deliberately refuses in pinned archives; updates use the new release's verified installation block.
6. CLI examples — project import and readiness
The following are individual examples, not a script to execute top to bottom. Replace proj_ID, run_ID, rev_ID, and find_ID with actual IDs returned by commands. Replace source paths with existing folders. Keep Desktop open; credentials stay in Settings → Providers and are never supplied to the CLI.
sentry open
sentry cli capabilities --json
sentry cli agent list --json
sentry cli agent doctor opencode --json
sentry cli agent doctor deepseek --json
sentry cli agent doctor glm --json
sentry cli project add "C:\Projects\SampleApp" --json
sentry cli project list --json
sentry cli project show proj_ID --json
sentry cli project revisions proj_ID --json
sentry cli project doctor proj_ID --json
sentry cli project update proj_ID "C:\Projects\SampleApp" --jsonProject add/update returns data.projectId and data.revisionId. Import copies files into managed WSL storage and creates an immutable revision; the source folder remains yours. Generated caches are skipped, but .gitignore is not an import policy. Large imports may require multiple copies; both Windows backing-drive capacity and Linux free space matter. Removing managed projects does not immediately shrink WSL's virtual disk; Desktop's reclamation action is separate OS maintenance.
7. CLI examples — Full QA, Targeted QA, and polling
Choose one start example. These execute real providers and may incur charges. --agents selects the provider set. Configure them first. Full scans the project; Targeted limits included relative paths. --instructions supplies additional run guidance.
sentry cli run start proj_ID --mode full --agents opencode,deepseek,glm --json
sentry cli run start proj_ID --mode targeted --agents deepseek --paths src/auth,src/api --json
sentry cli run start proj_ID --mode full --agents opencode --instructions "Check input validation" --wait --timeout-ms 1800000 --json
sentry cli run list proj_ID --json
sentry cli run show run_ID --json
sentry cli run status run_ID --jsonStart is asynchronous by default: retain data.runId and data.operationId, then poll status. The runtime owns execution after the CLI exits. --wait observes the run until terminal status. --timeout-ms sets that run's time window (1000–604800000 ms, up to 7 days); omitted uses the default from Settings → Runtime, 3 hours if none was saved. An uncertain start response may mean the paid run already exists: inspect run list/Desktop before any retry. Do not blindly retry RUN_MAY_HAVE_STARTED. Closing a CLI process does not cancel a canonical run.
8. CLI examples — results, JSON/log exports, cancellation, deletion
Retrieve results after a terminal status. Exports use the canonical runtime bytes and write the chosen local output file; create its parent directory first.
$reports = Join-Path ([Environment]::GetFolderPath("MyDocuments")) "Sentry Reports"
New-Item -ItemType Directory -Path $reports -Force | Out-Null
sentry cli run result run_ID --json
sentry cli run export run_ID --format json --out (Join-Path $reports "result.json") --json
sentry cli run export run_ID --format log --out (Join-Path $reports "result.log") --jsonUse these only when you intend to cancel/remove the selected item:
sentry cli run cancel run_ID --json
sentry cli project delete proj_ID --yes --jsonDeletion permanently removes Sentry-managed project data and history while preserving the original source folder. Active-work safety gates still apply. Cancellation is explicit and separate from deletion.
9. CLI examples — run depth, settings, findings, re-test, profiles and toolchains
These are individual examples. Re-test, profile building and Full or Fast runs use real providers and may incur charges; settings commands and reads do not.
# Run depth: Fast plans at most 3 checks, Full (the default) up to 8
sentry cli run start proj_ID --mode full --depth fast --wait --json
sentry cli run list proj_ID # fast runs are marked FAST
# Settings: reasoning effort per agent and the default run time limit
sentry cli settings show --json
sentry cli settings effort glm xhigh --json
sentry cli settings effort deepseek off --json
sentry cli settings effort chatgpt default --json
sentry cli settings run-limit 6h --json # default | 3h | 6h | none | 90m | 12h
# Findings by revision, re-test, profiles, toolchains
sentry cli project findings proj_ID --json
sentry cli run start proj_ID --retest run_ID:find_ID --wait --json
sentry cli run start proj_ID --retest run_ID:find_ID,run_ID:find_ID --retest-with all --agents opencode,deepseek --json
sentry cli run start proj_ID --mode full --agents chatgpt --profile --tools --json
sentry cli project profile proj_ID --json
sentry cli project profile-build proj_ID --json
sentry cli toolchain status --json
sentry cli toolchain install pack_ID version --jsonEach agent accepts only its own reasoning-effort levels: OpenCode and ChatGPT low, medium, high; GLM low to max (xhigh, max included); DeepSeek off, low, high, max. default removes the setting. The CLI can change only these two settings; credentials and everything else stay in Desktop. A re-test takes up to 12 findings and answers each PASSED (resolved), NOT PASSED (still there) or COULD NOT COMPLETE; --depth does not apply to re-tests. The 1.x issue, retest and run merge commands no longer exist.
10. Automation contract and errors
Always use --json for automation: stdout contains one JSON envelope; stderr contains human diagnostics. Parse stdout and branch on ok / error.code, never message wording. Capture the process exit status before running another command. run result returns canonical structured content inside data.result.
$responseText = sentry cli project list --json
$exitCode = $LASTEXITCODE
$response = $responseText | ConvertFrom-Json
if ($exitCode -ne 0 -or -not $response.ok) { throw ($response.error.code + ": " + $response.error.message) }
$response.data.projectsOptional informational client identity:
$env:SENTRY_CLI_CLIENT_NAME = "Automation client"
$env:SENTRY_CLI_CLIENT_VERSION = "1.0.0"
sentry cli capabilities --json| Exit | Meaning |
|---|---|
| 0 | Command success. |
| 1 | Internal/transport/protocol failure, including Desktop not running. |
| 2 | Invalid arguments or forbidden command. |
| 3 | Project/run/finding/source not found. |
| 4 | Conflict/retryable state, uncertain start, or response/export size limit. |
| 5 | Findings present for applicable completed execution commands. |
| 6 | Execution/provider readiness failure. |
| 7 | Partial execution. |
| 8 | Cancelled execution. |
An accepted asynchronous start is not proof the QA finished successfully. Use run status, run show, and run result. Common codes: SENTRY_DESKTOP_NOT_RUNNING → open Desktop; PROVIDER_NOT_READY → Settings/Environment; RUN_NOT_COMPLETE → poll; ACTIVE_RUN_EXISTS/PROJECT_LOCKED → settle active work; EXPORT_TOO_LARGE → canonical export exceeds the transport limit. JSON is never silently truncated. The canonical raw export limit is 6,000,000 bytes.
Production uses the Desktop named-pipe broker and the shared WSL runtime. It never creates a separate database and never selects direct/development transport from an environment override. Development simulation and the retired merge, verifier, issue and retest commands are unavailable in the packaged CLI. Client names and pipe scope are informational, not authentication; the documented trust boundary includes same-user processes and does not claim a custom current-user-only pipe ACL. See the complete CLI contract and command reference, also included as CLI.md in the ZIP.
Artifact identity and verification
- Version: 2.0.1; target: windows-x64; runtime protocol: 1.
- Source: 3db5b49985a8218350d227e9dbe87ff232f35a5e.
- Git tree:
d1a1449b50e4bdb815a898d1d68af7b32e343e90. - ZIP:
sentry-2.0.1-3db5b49985a8-windows-x64.zip. - ZIP SHA256:
29d06240ce5079161144b9879481c6ccdcfffa282b95ecf224bdfbd16c9a53ce. - Manifest SHA256:
326ec379f62723cd2b4874e28abae8b748eb72b1495575d738a4e5be195d4619. - Complete verified manifest inventory: 336 files, including the production CLI and local guides.
Verification covers the hosted quality, launcher and Windows archive jobs on the release pull request, a clean build of this exact source, ZIP extraction and verification of the manifest and all 336 files, and a check that the packaged CLI's help lists the new settings and --depth commands and none of the removed 1.x commands. This is a prepared Windows/WSL host, not clean-machine provisioning. The update from a published v2.0.0 installation through this page's block was not separately exercised, and no paid-provider campaign or elevated disk compaction was run for this release. GLM and DeepSeek reasoning effort has not been exercised against the live providers: if a run fails after setting one, set that agent back to Default. No old tag or release asset is replaced.
Runtime protocol 1, provider/model/tool pins (OpenCode 1.18.32, DeepSeek SDK 0.1.5-rc.2, Claude Code 2.1.270), credential encryption boundaries and the database schema are unchanged. One data difference: a project whose symlinks have a literal backslash in the target gets a different revision hash on its next import, because the copy is now faithful on Linux and macOS. Native Linux Desktop, macOS, signed installers, offline bootstrap and automatic updating remain outside this release.
See v2.0.1 notes and the installation/recovery guide. Included INSTALL.md and CLI.md link to this exact source.