winget install --id=hdosys.herdr-sandbox -e Herdr Sandbox launches disposable Windows Sandbox development environments, provisions native Windows toolchains, and connects an independently installed compatible Herdr client to the guest over SSH.
Disposable Windows workstations for coding agents.
Run coding agents in a prepared, isolated, native Windows environment without loading your main machine with project SDKs, build tools, agent processes, and experimental runtime state. Your selected work stays available on the host. The Windows environment is disposable.
Start a Sandbox from a project and keep working in your normal host terminal. Reuse that guest while it is productive, or recreate it when you want a clean workstation again.
Why · Get started · Configuration · Commands · Stacks · Troubleshooting · Engineering · How it works · Security · Optional workflows · Development · Docs
https://github.com/user-attachments/assets/b6c02367-683b-4a1f-94e6-b662149d89d9
Work from the normal host terminal while Herdr connects to coding agents inside Windows Sandbox. Detach and reconnect to the same OpenCode session without switching to an RDP workflow.
Coding agents can install dependencies, compile projects, run experiments, and accumulate temporary state much faster than a manually maintained developer machine can be cleaned. Herdr Sandbox separates the work worth keeping from the environment used to produce it.
The host keeps source, identity, configuration, cache, and diagnostics. The guest owns compilation, agent execution, and disposable runtime state.
| Keep on the host | Recreate in Windows Sandbox |
|---|---|
| Selected projects and optional persistent worktrees | Coding agents and their processes |
| Approved agent configuration and shared models | Native Windows compilers, SDKs, and tools |
| Verified package cache and diagnostics | Build processes, experiments, and guest-local temporary state |
The goal is not to preserve a long-lived machine. It is to preserve the developer workflow: keep what matters, replace the execution environment, and continue from the normal terminal.
Herdr Sandbox applies the host and guest split as a product boundary, not just a packaging detail:
flowchart LR
Host["Host terminalsandbox (Go)"]
HostHerdr["Host Herdrremote provision + attach"]
Projects[("Selected projects")]
Worktrees[("Optional persistentHerdr worktrees")]
Models[("Optional sharedAI models")]
Config["Approved agent config"]
subgraph Guest["Disposable Windows Sandbox"]
Provision["PowerShell 5.1provisioning"]
Agents["Agents + nativetoolchains"]
Herdr["Versioned Herdrsidecar + server"]
end
Host -->|launch + lifecycle| Provision
Host -->|final config + verified SSH target| HostHerdr
Projects <-->|narrow writable mappings| Agents
Worktrees <-->|dedicated writable mapping| Agents
Models <-->|shared writable mapping| Agents
Config -->|verified SSH only| Agents
Provision --> Agents
HostHerdr -->|provision + validate| Herdr
HostHerdr <-->|console-backed attach| Herdr
Go makes lifecycle decisions; PowerShell performs Windows-specific provisioning.
> [!IMPORTANT] > Windows Sandbox separates this work from the normal Windows installation, but selected projects remain writable and guest administrators can access explicitly transferred credentials. Networking is enabled. Keep backups and normal supply-chain controls; see Security boundaries before using untrusted code.
ssh.exe on host PATH), and internet access for cache misses.PATH.If Windows Sandbox is not enabled, run the following from elevated Windows PowerShell and restart Windows:
Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All
Herdr Sandbox requires Herdr Extended. Its WinGet ID remains hdosys.herdr-win.
Install both packages with:
winget install hdosys.herdr-win hdosys.herdr-sandbox
Update both:
winget upgrade hdosys.herdr-win hdosys.herdr-sandbox
Herdr Extended provides the Windows server and remote provisioning used by Herdr Sandbox. It remains a separate package.
Download and verify the latest Herdr Extended and Herdr Sandbox setups, then install Herdr Extended first. GitHub displays the SHA-256 digest for each release asset.
Open a new terminal and confirm:
herdr --version
sandbox --version
The Herdr result must contain the exact herdr-ext marker.
> [!WARNING] > The Herdr Extended and Herdr Sandbox installers are currently unsigned. For direct > downloads, use the linked releases and verify their GitHub SHA-256 digests.
Installer and uninstall behavior
%LOCALAPPDATA%\Programs\Herdr Sandbox binary directory and replaces that complete directory during upgrade.%APPDATA%\herdr-sandbox\config.json and user.ps1 are created only when absent and survive upgrades and normal uninstall. Select Also delete config.json and user.ps1 only when that removal is intended.Portable ZIP and source build
Download herdr-sandbox__windows_amd64.zip, verify its GitHub SHA-256 asset digest, and extract all four files into one directory. Keep the three support files beside sandbox.exe, then run .\sandbox.exe or add that directory to user PATH.
From the repository root:
go run ./cmd/task verify
The checked build writes the same four files to build\bin. Use that executable directly or add the directory to user PATH.
Before the first up, open the user-owned global configuration:
sandbox config
Review memory, agent configuration sync, optional packages, and host folder
mappings before exposing them to the guest. The command creates config.json
only when absent. See Configuration for a practical example
and the complete field reference.
From the project root, choose a stack, inspect the plan, and start:
sandbox init --stack go
sandbox plan
sandbox up
Omit --stack for a prompt or repeat it to combine compatible entries from
Supported stacks. init writes
.herdr-sandbox\provision.ps1 without replacing an existing profile. plan is
read-only. up provisions the guest and attaches Herdr in the normal host
terminal; the visible Sandbox bootstrap console needs no input.
After detaching, the guest stays ready:
sandbox status
sandbox attach
sandbox down
Use sandbox up --no-attach from a headless caller, then attach later from a real
terminal. Plain ssh sandbox remains available for diagnostics.
Project profiles own per-project tools. config.json and user.ps1 own global
choices. Setup never overwrites either user-owned file.
Open the user-owned configuration:
sandbox config
The command creates config.json only when absent. Setup, portable first use, and
sandbox config refresh the app-owned config.sample.json and
config.schema.json references without replacing user configuration. Global
PowerShell additions belong in user.ps1:
%APPDATA%\herdr-sandbox\config.json
%APPDATA%\herdr-sandbox\config.sample.json
%APPDATA%\herdr-sandbox\config.schema.json
%APPDATA%\herdr-sandbox\user.ps1
New configurations include "$schema": "./config.schema.json", so compatible
editors discover the adjacent schema without a network request. Existing
configurations are never rewritten. The schema checks JSON structure only;
sandbox plan remains authoritative for paths, overlaps, package policy, and
credentials.
config.json is strict JSON. A complete practical example:
{
"$schema": "./config.schema.json",
"cacheDirectory": "D:\\HerdrSandboxCache",
"worktreeDirectory": "D:\\HerdrWorktrees",
"modelsDirectory": "D:\\Models",
"memoryMB": 32768,
"audio": false,
"audioInput": false,
"tailscale": false,
"mobileSSHAuthorizedKeys": [],
"configurationSync": {
"pullHostGitRepositoriesOnUp": false,
"pullHostGitRepositoriesOnDown": false
},
"codingAgentSync": {
"opencode": true,
"claudeCode": true,
"codex": true,
"githubCopilot": true,
"pi": true
},
"credentialSync": {
"opencode": false,
"claudeCode": false,
"codex": false,
"githubCLI": false,
"pi": false,
"tradingView": false
},
"workspaces": {
"project": "D:\\Projects\\project"
},
"mounts": {
"docs": {
"path": "D:\\Shared\\docs",
"readOnly": true
},
"scratch": {
"path": "D:\\Shared\\scratch",
"readOnly": false
}
},
"workspaceDiscovery": {
"root": "D:\\Projects",
"exclude": [
"^archive$"
]
},
"wingetPackages": {
"remove": [],
"add": [
"SST.opencode",
"Anthropic.ClaudeCode",
"OpenAI.Codex",
"GitHub.Copilot"
],
"versions": {}
}
}
Replace paths with existing folders. User-chosen keys such as client and docs
become the final guest folder names.
Review the effective configuration and resolved tool versions with sandbox plan
before up. Package changes can apply to a compatible ready guest without
replacing it.
Complete config.json field reference
Workspace and mount names use letters, numbers, ., _, or -, start with a
letter or number, and are at most 64 characters.
| Field | Value and effect |
|---|---|
$schema | Optional editor hint. When present, it must be ./config.schema.json. |
cacheDirectory | Absolute dedicated cache root, created when absent. "" uses task-owned temporary cache state. Never point it at shared data. |
worktreeDirectory | Existing dedicated host directory mapped read-write to C:\Worktrees. "" disables it. |
modelsDirectory | Existing dedicated host directory mapped read-write to C:\Models. "" disables it. |
memoryMB | Integer Sandbox memory limit in MiB, minimum 2048. --memory-mb overrides one run. |
audio | Boolean enabling guest audio output. |
audioInput | Boolean enabling guest microphone input. |
tailscale | Boolean enabling Herdr's stable tagged Tailscale identity. |
mobileSSHAuthorizedKeys | Array of at most eight unique device-owned Ed25519 public keys. A nonempty array requires tailscale: true. |
configurationSync.pullHostGitRepositoriesOnUp | Opt-in boolean allowing fast-forward-only pulls of detected host Git config repositories during up. Defaults to false. |
configurationSync.pullHostGitRepositoriesOnDown | Opt-in boolean allowing the same pull policy during down. Defaults to false. |
codingAgentSync.opencode | Boolean streaming OpenCode configuration into the guest. Defaults to true. |
codingAgentSync.claudeCode | Boolean streaming Claude Code configuration into the guest. Defaults to true. |
codingAgentSync.codex | Boolean streaming Codex configuration into the guest. Defaults to true. |
codingAgentSync.githubCopilot | Boolean streaming GitHub Copilot configuration into the guest. Defaults to true. |
codingAgentSync.pi | Boolean streaming Pi configuration into the guest. Defaults to true. |
credentialSync.opencode | Boolean streaming an existing OpenCode API credential. |
credentialSync.claudeCode | Boolean streaming an existing Claude Code credential. |
credentialSync.codex | Boolean streaming an existing Codex credential. |
credentialSync.githubCLI | Boolean streaming an existing GitHub CLI credential. |
credentialSync.pi | Boolean streaming an existing Pi credential. |
credentialSync.tradingView | Boolean streaming existing TradingView session cookies. |
workspaces. | Existing absolute project-directory string mapped read-write to C:\Workspaces\. |
mounts..path | Existing absolute generic-directory string mapped to C:\Mounts\. |
mounts..readOnly | Required boolean. true blocks guest writes through that mapping. |
workspaceDiscovery.root | Existing parent directory whose direct child directories become workspaces. "" disables discovery. |
workspaceDiscovery.exclude | Array of at most 64 unique Go RE2 patterns matched against direct child names. |
wingetPackages.remove | Array of supported Base package IDs to remove from the default set. |
wingetPackages.add | Array of supported Base package IDs to add. It defaults to the four coding-agent packages shown above. |
wingetPackages.versions. | Exact WinGet version string for a selected package. Omit it for newest-stable resolution. |
sandbox init writes direct calls into .herdr-sandbox\provision.ps1 so
sandbox plan can inspect requirements without executing project code. Advanced
profiles may call the supported functions in
provisioning\stacks.ps1 and add idempotent Windows
PowerShell 5.1 for project-specific tools. Keep application dependencies and
lockfiles in their normal project owners.
The first C/C++, Rust/MSVC, or Handy run may briefly show Microsoft Visual Studio Installer while Herdr Sandbox prepares a verified Build Tools layout in its cache. Nothing is installed into the host development environment.
Agent configuration sync
Configuration transfer is enabled by default for OpenCode, Claude Code, Codex,
GitHub Copilot CLI, and Pi. Set an individual codingAgentSync field to false
to disable that source. Credential transfer is a separate opt-in through
credentialSync. Missing host
credentials leave the guest unchanged. Turning an entry off stops later
transfers but does not revoke a credential already present in a retained guest;
closing the Sandbox remains the cleanup boundary. GitHub CLI config.yml and
TradingView stack/privacy settings remain usable without transferring accounts
or session cookies. Review these
choices before the first up. Approved files travel over verified SSH; a
Git-backed configuration root also transfers repository metadata and object
history, which may contain old secrets. Disable any root whose complete history is
not safe for the guest. Private SSH and GPG keys, conversations, logs, caches, and
machine-bound credentials stay on the host. Agent installation remains a separate
wingetPackages.add choice. sandbox plan lists configuration and credential
selections separately.
{
"credentialSync": {
"opencode": false,
"claudeCode": false,
"codex": false,
"githubCLI": false,
"pi": false,
"tradingView": false
}
}
When enabled, registered configuration repositories fast-forward before up and
after down. Local edits are never rebased, stashed, or overwritten; divergence
and authentication failures are reported for the user to resolve.
Mappings and optional settings
mounts for reference material. Writable mappings expose host
data to every guest administrator process.modelsDirectory must be a dedicated existing AI-model folder. Every guest
administrator can read and modify it; Herdr Sandbox verifies its own VoxCPM2
files again before activation.workspaceDiscovery selects only direct child directories and supports explicit
exclusion patterns. The nearest profiled project is included automatically.KhronosGroup.VulkanRT only for the experimental vGPU-backed runtime path.
It does not install a Vulkan SDK or host driver.Persistent Herdr worktrees
Set worktreeDirectory to an existing dedicated host folder when Herdr-created
linked checkouts should survive fresh Sandboxes. Use Herdr for their complete
lifecycle:
| Goal | Command | Result |
|---|---|---|
| Create and open | herdr worktree create --cwd "" --branch "" --base "" | Creates a linked checkout and opens its workspace. |
| Discover | herdr worktree list --cwd "" --json | Lists checkouts and open workspace IDs. |
| Reopen | herdr worktree open --cwd "" --path "" | Reopens an existing checkout after a fresh Sandbox. |
| Remove | herdr worktree remove --workspace "" | Removes the checkout but keeps its branch. |
These are guest-native linked worktrees. Keep the main workspace at the same guest
path, use Herdr rather than host Git for lifecycle operations, and remove linked
worktrees before removing their main workspace. sandbox clean and uninstall
preserve the dedicated root.
Command output is plain, deterministic, and redirect-safe. Results go to stdout and errors go to stderr.
| Command | Behavior |
|---|---|
sandbox config | Creates and opens user configuration without replacing an existing file. |
sandbox version or sandbox --version | Prints the release, sortable UTC build freshness, and abbreviated source revision. |
sandbox plan | Shows the validated plan and ready-guest differences without changing state. |
sandbox init [--stack NAME]... | Creates a project profile, interactively when no stack is supplied. |
sandbox up [--memory-mb MB] [--timeout DURATION] [--no-attach] | Starts or reprovisions a compatible guest and normally attaches. |
sandbox pull-host-config | Fast-forwards explicitly registered configuration repositories without touching a guest. |
sandbox attach | Attaches to a ready Herdr Sandbox guest without reprovisioning. |
sandbox status | Reports health, progress, diagnostics, and the next action. Returns zero only when the state is ready. |
sandbox mobile | Prints the mobile SSH profile and secret-free QR code. |
sandbox down | Stops only the guest started by Herdr Sandbox and preserves opted-in Tailscale state. |
sandbox clean | Removes inactive run data only after verifying it is safe to delete. |
Lifecycle commands remove stale data only after verifying that no owned Sandbox
process still uses it. Changed or uncertain state is preserved and reported.
Settings that change host mappings or the isolation boundary require
sandbox down before the next up. sandbox up has a four-hour
launch-to-terminal-ready timeout by default. A positive --timeout DURATION
replaces it for one run, while caller cancellation can still stop the operation
sooner.
Start with the one stack that matches the project. Repeat --stack only to combine
compatible entries. The exclusive all selection installs every generic stack
and is intended for exhaustive environments rather than the usual first run.
Complete built-in stack catalog
| Selection | Guest tooling |
|---|---|
all | Every generic built-in: Android, Audio, Bun, Cargo Nextest, C/C++, .NET, Go, HyperFrames, Java, Just, Node/Playwright, NSIS, Nushell, Playwright CLI, Python AI with current stable Python and uv, Rust/MSVC, TradingView, and Zig; checkout-specific Handy and Herdr remain separate |
android | Current Android SDK command-line tools, Platform Tools/ADB, and the shared current stable Microsoft OpenJDK stack |
audio | REAPER plus AudioGridder Server and clients, with production VST execution inside the Sandbox |
cpp | C and C++ with current stable Visual Studio Build Tools, Windows 11 SDK, and CMake |
dotnet | Current stable .NET SDK family |
go | Go |
hyperframes | Node.js 22+, full FFmpeg/FFprobe, managed Chrome Headless Shell, and manually activated HyperFrames skills for OpenCode |
java | Current stable Microsoft OpenJDK family |
node | Latest stable Node.js, Playwright, and Chromium |
nsis | NSIS compiler for building Windows installers |
nushell | Latest stable Nushell command-line shell |
playwright-cli | Playwright CLI without a bundled browser |
python | Latest stable Python |
python-ai | Current stable Python and uv for CPU inference, notebooks, and API-based projects |
rust | Rust with MSVC Build Tools |
tradingview | TradingView Desktop and TVControl; host login transfer requires credentialSync.tradingView |
zig | Zig |
Project profiles may also call direct Bun, Cargo Nextest, Just, and uv helpers.
The all expansion uses the Python AI composition as its single Python and uv
owner, avoiding redundant standalone calls.
Omitted external-tool versions resolve to the current official stable release at
provisioning time. Explicit project versions remain exact and never fall back.
Checkout-specific Handy and Herdr shortcuts
These repository-specific shortcuts remain outside all:
| Shortcut | Intended setup |
|---|---|
handy | The current Handy Windows checkout, including Bun, Rust/MSVC, CMake, Vulkan SDK, and WebView2 |
herdr | Herdr and Herdr-Win checkouts, including Python, Rust/MSVC, Zig, Bun, Cargo Nextest, Just, and Git for Windows sh |
Dependencies and application commands remain project-owned. sandbox plan
expands each composition without executing the profile.
If custom project provisioning fails, the error names the workspace and its
.herdr-sandbox\provision.ps1 profile before preserving the original cause.
See SECURITY.md for vulnerability reporting, the complete threat
model, and practical guidance for credential-free or externally network-restricted
use.
Guest processes have administrator access inside Windows Sandbox. Only select host folders deliberately, prefer read-only mounts, and treat every credential copied into the network-enabled guest as accessible to its workloads.
Start with sandbox status; it preserves a running guest, removes stale data only
when it is safe, and reports the next action.
| Symptom | Action |
|---|---|
| Windows Sandbox is unavailable | Enable Containers-DisposableClientVM from elevated Windows PowerShell, restart Windows, and confirm hardware virtualization is enabled. |
up refuses an existing Sandbox | Run sandbox status and follow its next action. Use down only when it identifies the app-owned guest. |
| Automatic attach is unavailable in a headless process | Run sandbox up --no-attach, then use sandbox attach from a real terminal. |
ssh sandbox no longer connects | Run sandbox status. If the guest is gone, run sandbox up to create a verified target. |
| Legacy global Base is refused | Preserve %APPDATA%\herdr-sandbox\base.ps1, move only deliberate additions to user.ps1/config/project ownership, archive the legacy file under a non-reserved name, and retry. |
| Host configuration pull fails | Resolve the named repository's local state, upstream, authentication, network, or timeout problem, or disable the relevant automatic hook. |
| Guest Herdr provisioning fails | Confirm current Herdr-Win, host ssh.exe, and ssh sandbox, then inspect the failed phase with sandbox status. |
| Initial provisioning is slow | The first run downloads selected toolchains; C/C++, Rust/MSVC, and Handy also prepare a Visual Studio layout. Later runs reuse the cache. |
Audio, mobile, and Tailscale troubleshooting
| Symptom | Action |
|---|---|
| Audio or microphone is unavailable | Set audio or audioInput to true, run sandbox down, then start a fresh guest. |
| The host AudioGridder client does not find the Sandbox server | Start AudioGridder Server in the guest, use :0 from sandbox status, and confirm the VST was installed through guest project or user provisioning. |
| Mobile access is not ready | Check tailscale, mobileSSHAuthorizedKeys, tailnet access to TCP 2222, and the URI from sandbox mobile. |
| The mobile SSH host key changed | Refuse the connection. The fingerprint must survive fresh Sandboxes for the same host user; inspect protected identity and Tailscale state rather than accepting an unexpected key. |
| Tailscale enrollment is refused | Confirm the opt-in, retained package, dedicated tag, and a current non-reusable, non-ephemeral, pre-authorized key. |
Android wireless debugging
Select android, provision the guest, then use the pairing and debugging endpoints
shown by an Android 11 or newer device:
sandbox init --stack android
sandbox up
adb pair :
adb connect :
adb devices -l
The two ports can differ. Pairing keys remain disposable guest state. Windows
Sandbox has no supported arbitrary USB passthrough, so use a host toolchain for
USB, fastboot, recovery, or restricted-network workflows.
Playwright CLI with the guest Edge profile
Select playwright-cli. The stack prepares Microsoft's official
Playwright Extension
for the existing Edge profile:
sandbox init --stack playwright-cli
After enabling the extension, copy its displayed
PLAYWRIGHT_MCP_EXTENSION_TOKEN=... line. During provisioning, the visible
Sandbox bootstrap opens a window where you paste that line once. It makes the
token available to the agents created in that disposable guest. Leaving the
window empty keeps Playwright's manual connection approval. Then attach
automation to the same Edge profile:
playwright-cli.cmd -s=edge-main attach --extension=msedge
# Run Playwright CLI commands here.
playwright-cli.cmd -s=edge-main detach
A fresh Sandbox has a fresh Edge profile, so enabling the extension and pasting its new token remain one-time steps in that guest. Do not create a second browser or profile for this integration.
AudioGridder VST server
The audio stack runs VSTs inside Windows Sandbox while the normal host DAW uses
the AudioGridder client. Install the matching client release reported by
provisioning on the host, select the stack, and add desired VST installers to
project or user provisioning. Use
C:\Program Files\VstPlugins for VST2 and
C:\Program Files\Common Files\VST3 for VST3.
After sandbox up, start AudioGridder Server in the guest and configure the
host client with :0 from sandbox status. Set global "audio": true
only when guest-local REAPER playback should be audible.
Mobile Herdr over Tailscale
This opt-in lets a phone or tablet access Herdr over an existing tailnet to review
notifications, answer agent questions, and run project commands. It exposes a
key-only mobile Herdr endpoint on TCP 2222. Prepare a dedicated least-privilege tag
and ACL, generate an Ed25519 key on each mobile device, and create one
non-reusable, non-ephemeral, pre-authorized Tailscale auth key for
tag:herdr-sandbox. Never grant mobile peers management port 22.
The dedicated mobile SSH endpoint disables forwarding, so it is not a built-in proxy for project web servers.
Add only device public keys to config.json:
{
"tailscale": true,
"mobileSSHAuthorizedKeys": [
"ssh-ed25519 phone"
]
}
Pass the Tailscale key once without placing it in configuration or shell history:
$keyPointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR(
(Read-Host 'One-off tagged Tailscale auth key' -AsSecureString)
)
try {
$env:HERDR_SANDBOX_TAILSCALE_AUTH_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($keyPointer)
sandbox up
} finally {
Remove-Item Env:HERDR_SANDBOX_TAILSCALE_AUTH_KEY -ErrorAction SilentlyContinue
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($keyPointer)
}
Use sandbox mobile to print the secret-free URI, QR code, and host-key
fingerprint. Later fresh guests restore the protected identity without another
auth key. Keep the tailnet device and node-key expiry unchanged while relying on
that identity.
HyperFrames activation and shared models
The HyperFrames stack resolves the latest stable CLI and full FFmpeg release
when the profile does not request versions. Provisioning runs HyperFrames doctor,
checks its managed browser, stages the current skills outside normal agent discovery,
and proves a software H.264 encode with libx264. From the intended project
directory, start one HyperFrames-enabled OpenCode session with:
hyperframes-opencode
Ordinary opencode sessions do not load the HyperFrames skill metadata. Browser
GPU acceleration and FFmpeg hardware encoding are separate; the Sandbox profile
does not claim a hardware encoder.
To persist AI models, create one shared model folder and set modelsDirectory
to its absolute host path. Herdr Sandbox maps it read/write at C:\Models, where
guest tools can download models. HyperFrames TTS uses Supertonic 3 by default,
with original ONNX models, CPU inference, 16 threads, 10 denoising steps, sequential
chunks of at most 300 characters, and no batching. The built-in voices are M1-M5
and F1-F5. The direct CLI defaults to German and M1:
tts.ps1 --text "Dies ist eine maschinell erzeugte Sprachaufnahme." --voice M1 --output narration.wav
For HyperFrames requests, set lang to de and select the desired voice. Speech
is machine-generated and must be disclosed as such; the model's OpenRAIL-M license
and use restrictions apply. VoxCPM2 remains available via --provider voxcpm2,
including its narrator reference, --voice WAV, and --design choices.
A local bundle that includes Qwen3 also enables --provider qwen3. Supertonic/M1
remains the default; Qwen uses Ryan unless --voice selects another preset:
tts.ps1 --provider qwen3 --voice ryan --lang de --text "Dies ist ein Sprachtest." --output qwen.wav
This private evaluation option uses standalone qwen3-tts.cpp with a Q8_0
CustomVoice model and an F16 vocoder, not llama.cpp or ONNX and not all-INT8.
Its runtime redistribution rights are unconfirmed, so the engine bundle remains
local-only. Selecting Qwen never changes the default or silently substitutes it
when Supertonic is unavailable.
Until a public engine release includes Supertonic, select the verified local bundle
explicitly in the host config.json:
"ttsBundle": "C:\\Workspaces\\hyperframes-voxcpm2\\dist\\hyperframes-voxcpm2-local-windows-x64.zip"
Keep its adjacent .sha256 file. An empty ttsBundle selects the latest stable
hyperframes-voxcpm2
release, which must contain the same Supertonic contract. Invalid local input never
falls back to a download. Provisioning installs the bundle's hash-locked Python
dependencies in a dedicated guest environment and verifies the model files before
activation. Models persist in the shared root, including roughly 5 GB for the
selectable VoxCPM2 engine and 400 MB for Supertonic. Neither engine uses Sandbox
vGPU or Vulkan. Empty modelsDirectory disables this integration.
The repository uses one Go task runner for formatting, tests, stable builds, real Windows Sandbox checks, and release packaging.
Packaging uses the same task runner and writes the installer and portable ZIP to
build\dist. See ARCHITECTURE.md for the full verification
architecture.
Verification and packaging command reference
go run ./cmd/task verify
go run ./cmd/task verify-integration
go run ./cmd/task release VERSION
go run ./cmd/task provisioning-preflight
go run ./cmd/task native-current-sandbox
go run ./cmd/task package-current-sandbox v0.0.RELEASE_ID
go run ./cmd/task native-all-stacks
verify is the fast local check: formatting, Go modernization, Staticcheck,
nilness analysis, PowerShell parsing, focused tests, go vet, and the stable
build\bin artifact.verify-integration adds external PowerShell and Git behavior for nightly or
explicitly requested assurance.release VERSION accepts only a clean committed checkout contained in its
configured upstream. It validates the matching changelog section, confirms the
source commit stays unchanged and the tag is unused, then creates and pushes
the annotated tag consumed by release automation. It does not rerun tests,
installation, or provisioning.provisioning-preflight checks production provisioning parsers plus available
Java, Android, and Visual Studio inputs in the active Sandbox before a slower
native or installed-candidate run. It does not install or update tools.native-current-sandbox replays real Base and every project stack inside the
active development Sandbox, then proves a task-owned REAPER client connection
to AudioGridder server 0 without launching a nested Sandbox or restarting its
existing SSH and Herdr processes. Run it explicitly when deployment evidence is
useful before discarding a working guest; release does not invoke it.package-current-sandbox covers fresh install, same-version repair, a
current-layout immediate-predecessor upgrade, installed-payload provisioning,
configuration and development-environment preservation, and quiet uninstall
cleanup.native-all-stacks provisions a fresh real Windows Sandbox and exercises the
complete toolchain, managed SSH, REAPER-to-AudioGridder connection, and a real
NSIS compile without installing a release candidate.PRODUCT.mdARCHITECTURE.mdSECURITY.mdCHANGELOG.mdBACKLOG.mdherdr-sandbox is licensed under the Apache License, Version 2.0. The
same file retains the BSD notice for the bundled rsc.io/qr component.