Install and update
Install a published Windows or qualified Linux release, verify your download, update safely and uninstall without losing projects.
On this page
Install the current public release: 0.1.5
These instructions match the currently published 0.1.5 downloads, not the prepared 0.1.6 DEB packages. Choose Windows 11 x64 or Ubuntu 26.04 AMD64/ARM64. Windows ARM64, Windows 10 and Ubuntu 24.04 are not qualified for these public desktop payloads. The ARM64 portable build requires glibc 2.43.
Keep projects and backups outside the app directory. Verify every file against the current downloads and signature guide. Do not run a mismatched file or bypass unexplained OS security warnings. A detached signature is not Microsoft publisher reputation or engineering certification.
Verify before running
Use the download signature for the exact original filename and compare the complete checksum. The Linux native-installer signature authenticates the additional native installation identity; it does not replace download verification. Stop if either verification fails.
Windows 0.1.5: install and first launch
Download TraceForge-0.1.5-windows-x64.exe and its .sig.json signature from Downloads. Compare the complete SHA-256 in PowerShell:
Get-FileHash "$HOME\Downloads\TraceForge-0.1.5-windows-x64.exe" -Algorithm SHA256
Save and close TraceForge, run the verified installer, and confirm its destination and shortcut prompts. Launch TraceForge from the installed shortcut as an ordinary user. Open a copy of a .kicad_pro project, then its schematic or board. Expected result: the native project workspace, not a payment form.
The Agent and Plan views require Microsoft Edge WebView2 Runtime. If UI_WEBVIEW_UNAVAILABLE appears, save work and repair/install the official Microsoft runtime, then restart TraceForge. Never replace DLLs from an unknown website. No Node.js, compiler or private developer Codex account is required.
Linux: signed per-user installation
Use Ubuntu 26.04 on the matching architecture. Do not select another CPU architecture or claim the separate Ubuntu 24.04 backend proves this desktop archive runs there.
Download the portable lifecycle installer, its download signature, the matching native archive from Downloads, and its separate native-installer signature:
Keep original filenames. Verify the portable installer and archive download signatures before running/extracting them. The native-installer signature is a different envelope from the .sig.json download signature; do not substitute one for the other. Both CPU architectures use the same portable installer.
This public portable installer uses the distribution's Python 3 and python3-cryptography package. Use the supported distribution package if Python cannot import cryptography; no source checkout or developer account is required. Review administrator/package-manager prompts rather than silently changing shared system prerequisites.
From the downloads directory, choose ARCH=amd64 for x86-64, or ARCH=arm64 for AArch64:
ARCH=arm64
ARCHIVE="$PWD/traceforge-kicad-native-linux-$ARCH-0.1.0.tar.gz"
KEY="$PWD/traceforge-release-ed25519-20260929.pub"
BOOTSTRAP="$PWD/TraceForge-Linux-Setup-0.1.5.pyz"
PREFIX="$HOME/.local/opt/traceforge"
python3 -B "$BOOTSTRAP" --prefix "$PREFIX" install \
--package "$ARCHIVE" --version 0.1.5 \
--signature "$ARCHIVE.native-signature.json" --trusted-public-key "$KEY" \
--source-sha 68fcdef0848364ea0a81dce6436d14e7efb39b1a \
--tree-sha 4c86793f8d4b8d18a161d9289a728a9a67263a61 \
--upstream-ref 10.0.5 \
--upstream-commit 18fb9289ff0efdca53c0352ed81a0973f0a6b58c \
--platform linux --architecture "$ARCH"
python3 -B "$BOOTSTRAP" --prefix "$PREFIX" register-desktop
"$PREFIX/bin/traceforge-kicad"
An unmanaged destination is deliberately rejected: choose an empty prefix, not deletion of an existing installation. The archive's internal 0.1.0 filename is distinct from qualified release 0.1.5 and the exact source identity above. Keep the verified portable installer for future lifecycle commands.
Start with a project, not an AI charge
Follow your first project on a practice copy: open, make a harmless manual comment, save, close and reopen. Local editing is separate from connected AI access. For entitled access, follow account activation through the actual native account/access dialog. Never paste a provider key into chat or a website form.
Update without losing work
Save, close and back up the entire project including local libraries. Verify the new release's exact installer/signatures and read its notes before installing. For the Linux portable lifecycle, use that release's update command with its own archive, signature and source identity—not the identity above. Do not replace an engine under an open editor.
Open a representative copy after updating. Confirm symbols and footprints load, save a harmless change and reopen it. Retain the predecessor and original project backup: format conversion may not be reversible in an older editor.
Uninstall or recover
Windows: Settings → Apps → Installed apps → TraceForge → Uninstall. Keep projects outside the app folder. Do not delete unrelated KiCad installations, libraries, credentials or project folders.
Linux portable installation:
python3 -B "$BOOTSTRAP" --prefix "$PREFIX" inspect
python3 -B "$BOOTSTRAP" --prefix "$PREFIX" rollback --trusted-public-key "$KEY"
# Save and close editors first. Removes this managed payload, not project folders.
python3 -B "$BOOTSTRAP" --prefix "$PREFIX" uninstall
Rollback requires a retained, compatible signed predecessor; a fresh install has none. Do not use --purge as routine cleanup. If recovery reports a conflict, preserve both versions rather than overwrite newer work. Uninstalling does not cancel a subscription; use billing management.
Keep the error, version and exact step for support, without secrets or private project bytes. See troubleshooting before deleting anything.
Prepared 0.1.6 instructions — not the current download
These describe a separate prepared release, not an upgrade or download announcement.
Choose the correct installer
The prepared 0.1.6 release has three installers: Windows 11 x64, Ubuntu AMD64 (x86-64) and Ubuntu ARM64 (AArch64). The Linux packages target Ubuntu 24.04 and 26.04. This guide describes that release candidate; it does not announce publication. Use only the version and exact signed files actually listed on the download page. Do not use the former 0.1.5 portable-installer commands for a 0.1.6 .deb.
Check your computer's CPU architecture first. Windows ARM64, Windows 10 and other Linux distributions are not part of this release target. Keep project backups outside the application directory and evaluate a project copy first. The application interface and bundled getting-started/recovery guides offer English, Spanish, French and German. Provider diagnostics and the owner's approved policy originals may remain English.
Verify before running
Download the installer, its detached signature and the release public key together. Follow the verification guide and match the whole SHA-256, version, architecture and source revision. For example:
Get-FileHash "$HOME\Downloads\TraceForge_0.1.6_windows-x64.exe" -Algorithm SHA256
sha256sum TraceForge_0.1.6_amd64.deb
# On an ARM64 computer, use TraceForge_0.1.6_arm64.deb instead.
A checksum alone is not an authenticated signature. Stop on a mismatch. A detached release signature is also not a claim of Microsoft-trusted publisher reputation; do not bypass unexpected Windows security warnings.
Windows: install and first launch
Save and close TraceForge, run the verified Windows x64 installer and confirm its destination. The installer explains Microsoft WebView2 and the isolated local engineering engine's Windows/WSL prerequisites. It checks existing prerequisites and offers the supported prerequisite path; no separate Python, Node, Linux distribution setup or private developer account is required. A prerequisite may require Windows administrator consent or a restart: do not treat an unapproved, cancelled or restart-pending installation as ready. Do not disable security controls to force it to launch.
Launch the installed TraceForge shortcut as an ordinary user. Open a disposable .kicad_pro project and its schematic/PCB. The first useful screen is the project workspace, not a payment form. Local editing is distinct from signed-in, entitled AI access; use account activation for the latter. If the UI reports a missing WebView2 runtime, use the installer's repair/prerequisite path or the official Microsoft runtime, not DLLs from an unknown website.
Ubuntu: install and first launch
Choose the .deb matching your CPU and install it through Software Install, or run:
# AMD64 / x86-64:
sudo apt install ./TraceForge_0.1.6_amd64.deb
# ARM64 / AArch64, instead:
# sudo apt install ./TraceForge_0.1.6_arm64.deb
Ubuntu may request administrator consent and download the package's declared desktop/system dependencies. Review that prompt; a successful download is not a successful installation. No compiler, Node, separate Python environment or private Codex account is required. Launch TraceForge from the desktop application menu, or run traceforge-client as your ordinary user. Do not run the editor with sudo.
Open a project copy, confirm symbols and footprints load, save a harmless change, close and reopen it. Keep projects outside /opt/TraceForge. See your first project and troubleshooting if the expected workspace does not open.
Update, rollback and recovery
Save work and close editors before applying an update. TraceForge authenticates the application and any required engineering-engine update as a compatible pair. Downloading or reviewing an update does not approve project changes. An engine still used by an editor must not be switched or removed underneath it. Read the update's restart/error state rather than repeatedly starting another request.
A failed verified startup retains or restores the previous trusted selection. Rollback needs a retained compatible predecessor; a fresh installation has none. File-format conversion may not be reversible in an older release: keep the original project backup rather than overwriting newer work. For installer repair, run the matching verified Windows installer again, or reinstall the matching .deb through Ubuntu's package manager. Keep the exact error and version if recovery refuses corrupt or stale files; do not delete the profile as the default fix.
Uninstall without deleting work
On Windows, use Settings → Apps → Installed apps → TraceForge → Uninstall. On Ubuntu use Software Install, or:
sudo apt remove traceforge-client
Save and close work first. Uninstall removes application-owned files, not customer projects, conversations, drafts, settings or private-engine data. Shared prerequisites and unrelated KiCad installations are not silently removed. Keep retained data when reinstalling a verified version; do not manually delete profile or isolated-engine directories as routine cleanup. Uninstalling does not cancel a subscription: use billing management.
The installed customer-documentation directory includes the four language guides and exact approved Privacy, Terms, Refunds and Support originals. The release's notices and corresponding-source download must match its native revision. For help use support, including your version, architecture and redacted error—not passwords, tokens or private project files.