Build from source
Source-backed Linux and native Windows development recipes, carrier installation, gates, and explicit platform limits.
Canonical source — docs/public/getting-started/build-from-source.md
Build from source
These recipes follow the checkout’s Makefile, installers and CI jobs. Each numbered step names its executable source. Run commands from the repository root unless a step changes directory. For a cold machine and the first session, use the Entry book (Polski); for daily operation, use the Runbook.
Read the boundary first
- Full Linux baseline: Ubuntu 24.04, glibc ≥ 2.39. The owned Linux pack is
built on Ubuntu 22.04 for an older ABI, but the public Loctree and PRView
binaries do not start on glibc 2.35/2.36 (Ubuntu 22.04/jammy, Debian
12/bookworm). A successful npm install followed by
missing or brokenis an ABI failure. Today the choices are a newer system or the explicitREQUIRE_FOUNDATIONS=0waiver and the absence of those tools. - Python ≥ 3.11 supplies
tomllib. Linux CI uses 3.11; Windows CI uses 3.12 and the Windows pack embeds 3.12.10. Node 22 is the container baseline;ensure_nodedownloads 22.16.0 when Node/npm are absent. - Rust is stable on Windows. The Linux assembler and its CI build pin the stable release 1.97.0, including both WASM targets on that toolchain.
make installbuilds and installs a Runtime Pack from the committed checkout.make install-sourceis the retained alias. The macOS source lane builds Frame and Terminal at the full SHAs inconfig/source-components.json, using detached worktrees so dirty donor checkouts stay intact. A suppliedRUNTIME_PACKinstalls that existing carrier without compiling.- Foundations are external products: npm
@loctree/loctree, npm@loctree/aicx, GitHub releasesvetcoders/prview-rs, PyPIscreenscribe. They are never vendored into the pack.REQUIRE_FOUNDATIONSdefaults to 1: a missing/broken requested foundation fails POSIX installation.=0is an explicit waiver, not a repair. Doctor warnings do not undo that install gate. Nativeinstall.ps1does not run the POSIX foundation script.
Sources: Makefile → install, install-source,
runtime-pack; Linux workflow
→ linux-runtime-pack, ubuntu-native, debian-bookworm-container;
Windows workflow →
windows-runtime-pack; foundation installer
→ ensure_node, foundation_channel_fail;
Dockerfile → FROM, build arguments;
Windows builder → embedded Python.
Linux development — Ubuntu 24.04
L1. Install the system prerequisites
sudo apt-get update
sudo apt-get install -y \
build-essential cmake libclang-dev libprotobuf-dev protobuf-compiler rsync \
libgtk-3-dev libxdo-dev libayatana-appindicator3-dev \
bash ca-certificates curl file git make python3 python3-venv \
shellcheck tar zsh openssl
Expected: apt completes with exit 0; protoc and the GTK/pkg-config development
files exist. libgtk-3-dev, libxdo-dev and appindicator cover the Linux
voc/tray dependency graph. Missing protoc fails prost-build; missing
glib-2.0/GTK means the development packages above are absent.
Source: Linux workflow → “Install Runtime Pack build prerequisites”, Ubuntu “Install make + python3”, Debian “Install prerequisites”; Dockerfile → apt list; Linux builder → tool preflight. This list is the union of those recipes; it is not the shorter runtime-only list.
L2. Clone and record the revision
git clone https://github.com/vetcoders/vibecrafted.git
cd vibecrafted
git branch --show-current
git rev-parse HEAD
git status --short
Expected: a full source SHA and no dirty tracked files before carrier assembly.
For the development handoff on this branch, select
port/windows-setup-wizard-fix explicitly with
git switch port/windows-setup-wizard-fix while that branch exists. The builders
bind provenance to HEAD; do not mix a pack from one revision with another source
archive. Commit your changes before a maintainer pack build.
Source: Quick Start → “1. Install”;
Linux builder → clean-tree preflight;
distribution writer → resolve_source_provenance.
L3. Provision Python tooling and Node 22
curl -LsSf https://astral.sh/uv/install.sh -o uv-install.sh
sh uv-install.sh
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
bash scripts/install-foundations.sh loctree aicx prview screenscribe
export PATH="$HOME/.vibecrafted/tools/node/bin:$HOME/.local/bin:$PATH"
python3 --version
node --version
uv --version
Expected: Python 3.11+, Node v22.x and executable foundations. The foundation
script bootstraps Node 22.16.0 if Node/npm are absent; it accepts an existing
Node, so replace an older host Node before continuing. It installs ScreenScribe
through uv tool install (pipx fallback), not into the system Python. If npm
reports EACCES, use a user-writable global npm installation rather than running
the entire build as root. On glibc 2.35/2.36, see “Older Linux” below.
Source: Linux workflow → Debian
“Install uv”; foundation installer →
ensure_node, install_loctree, install_aicx, install_prview, install_screenscribe.
L4. Pin Rust and install both WASM targets
If rustup is absent, use the workflow’s bootstrap first:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o rustup-init.sh
sh rustup-init.sh -y --default-toolchain stable --profile minimal
export PATH="$HOME/.cargo/bin:$PATH"
export RUSTUP_TOOLCHAIN=1.97.0
rustup toolchain install "$RUSTUP_TOOLCHAIN" --profile minimal
rustup target add --toolchain "$RUSTUP_TOOLCHAIN" \
wasm32-unknown-unknown wasm32-wasip1
rustup target list --installed --toolchain "$RUSTUP_TOOLCHAIN"
Expected: the installed-target list contains both names above. A target installed
on an ambient default toolchain does not satisfy a build selected by
RUSTUP_TOOLCHAIN. Add it to 1.97.0, not to a different default.
Source: Linux workflow → “Install Rust toolchain”, “Install Runtime Pack build prerequisites”; assembler → toolchain provisioning.
L5. Install cargo-leptos and the lock-matched wasm-bindgen CLI
curl -L --proto '=https' --tlsv1.2 -sSf \
-o /tmp/install-binstall.sh \
https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh
bash /tmp/install-binstall.sh
cargo binstall -y cargo-leptos
lock_version="$(cargo tree --locked --manifest-path vibecrafted-server/Cargo.toml -p wasm-bindgen --depth 0 --prefix none | awk 'NR == 1 { sub(/^v/, "", $2); print $2 }')"
cargo binstall -y "wasm-bindgen-cli@${lock_version}"
Expected: both tools install; lock_version comes from the checked-in dependency
lock, not from the latest wasm-bindgen release. A wasm-bindgen version mismatch
is fixed by rerunning the lock query and installing that exact CLI version.
Source: Linux workflow → “Install Runtime Pack build prerequisites”.
L6. Build, sign and install one exact carrier
Maintainers with the product release key in ~/.keys/vibecrafted-signing.key:
make install
Expected: the build writes build/runtime-pack-selection.json for the signed
pack and the installer publishes that exact carrier. Missing product credentials
stop this lane before compilation. An interrupted build leaves selection pending
and installation refuses it.
For an independent developer, use the assembler lane and your own trust anchor. Do not request or copy the product’s private key:
export VIBECRAFTED_SOURCE_OWNER_REPO=vetcoders/vibecrafted
export VIBECRAFTED_SOURCE_REVISION="$(git rev-parse HEAD)"
pack="$PWD/build/Vibecrafted_RuntimePack_linux-x64.tar.gz"
bash scripts/build-linux-runtime-pack.sh "$pack"
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out build/dev-signing.key
openssl pkey -in build/dev-signing.key -pubout -out build/dev-signing.pub
openssl dgst -sha256 -sign build/dev-signing.key -out "$pack.sig" "$pack"
openssl dgst -sha256 -verify build/dev-signing.pub -signature "$pack.sig" "$pack"
VIBECRAFTED_RUNTIME_PACK_PUBLIC_KEY="$PWD/build/dev-signing.pub" \
make install RUNTIME_PACK="$pack"
Expected: Verified OK, then a successful install. This x64 example requires
an x86_64 Linux host; use linux-arm64 in the filename on an arm64 host (the
assembler chooses the host architecture). Keep the development private key
local and untracked. This is a development signature, not a product release.
The assembler produces the sibling .sha256; the commands add .sig.
Source: Makefile → runtime-pack, install, install-source;
Linux builder → two lanes / missing-key
instructions; Linux workflow →
“Build and sign the exact-source CI carrier”.
L7. Verify the installed runtime outside the checkout
export PATH="$HOME/.vibecrafted/bin:$HOME/.cargo/bin:$HOME/.local/bin:$HOME/.local/share/vibecrafted/bin:$PATH"
cd /tmp
vibecrafted doctor
vibecrafted version
Expected: doctor exits 0 with no failures; version carries the installed source stamp. A checkout cwd can shadow the installed Python tree and produce an unstamped-launcher finding. Use a neutral cwd as CI does. A foundation warning is still a missing capability; it is not evidence that a waived install is full.
Source: Linux workflow → “Run vibecrafted doctor”.
L8. Run development gates and build the portable source artifact
Return to the checkout:
make check
make test
make portable
Expected: Check complete., a pytest summary, then a provenance-verified portable
source archive under dist/. make test runs the TUI tree plus its prerequisite
keychain check; it is not every test in the monorepo. make test-core is separate.
Never combine tests/tui and vibecrafted-core/tests in one pytest process.
make portable packages source; it does not replace the binary Runtime Pack.
Use a clean committed tree for provenance-bound artifacts.
Source: Makefile → check, test, test-core, portable;
portable builder → provenance validation.
Older Linux and Debian 12 container reference
The exact Debian apt recipe is in install-linux.yml
→ debian-bookworm-container / “Install prerequisites”. It adds file, shellcheck,
sudo, tar, python3-venv and the same build/GTK libraries; rsync is in
the separate pack-build job. The container is debian:bookworm-slim.
Dockerfile uses node:22-bookworm-slim and defaults
INSTALL_FOUNDATIONS=false, INSTALL_RUST=false, INSTALL_AGENT_CLIS=false.
It is a reference Linux base, not proof of full external-tool support.
Jammy/bookworm have glibc 2.35/2.36. CI explicitly waives foundations there; Ubuntu 24.04 retains the hard gate. To accept that same reduced capability:
REQUIRE_FOUNDATIONS=0 bash scripts/install-foundations.sh loctree aicx prview screenscribe
REQUIRE_FOUNDATIONS=0 make install RUNTIME_PACK=/absolute/path/to/your-pack.tar.gz
Loctree/PRView remain unavailable. Reinstalling the same npm package does not
repair the libc ABI. Upgrade to Ubuntu 24.04/glibc ≥ 2.39 for the full spine.
Source: workflow REQUIRE_FOUNDATIONS matrix and Debian environment;
foundation installer → foundation_channel_fail.
Native Windows development — win32-x64, without WSL
W1. Prepare the builder host and clone
Use an x64 Windows host with PowerShell 5.1+, Git for Windows, the MSVC x64 C++
build tools/Windows SDK, Rust stable, Python 3.12 on PATH and OpenSSL.
The workflow uses windows-latest with its preinstalled MSVC toolchain;
the repository does not contain a clean-host MSVC installer. Install those
build tools before invoking Cargo. Node 22 is for external npm products;
uv/Git Bash are builder tools, not customer-install prerequisites.
git clone https://github.com/vetcoders/vibecrafted.git
cd vibecrafted
rustup toolchain install stable --profile minimal
rustup default stable
python --version
cargo --version
Expected: Python 3.12 and a stable Rust toolchain. ARM64 is refused by this
x64 builder. link.exe missing means the MSVC build environment is absent.
Source: Windows workflow →
“Install Rust toolchain”, “Setup Python”;
Windows builder → host guards,
Install-CargoBin, x86_64-pc-windows-msvc;
Quick Start → “1. Install” clone recipe.
W2. Provision OpenSSL for vc-frame
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\ci-install-openssl-win64.ps1
Run this builder prerequisite from an elevated PowerShell when OpenSSL is
absent: the helper installs to Program Files and adjusts system PATH. Reopen
the builder shell after installation so openssl is visible for signing.
Expected: the helper installs the pinned FireDaemon OpenSSL x64 distribution.
The pack builder discovers OPENSSL_DIR in Program Files, or accepts an explicit
installation directory with headers, import libraries and the two shared DLLs.
Missing headers/DLLs are fatal; do not remove vc-frame from the payload to pass.
The builder fetches protoc 29.3 when a working PROTOC/protoc is absent.
Source: Windows workflow → “Install OpenSSL (vc-frame)”; builder → protoc/OpenSSL preflight.
W3. Build the native carrier
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-windows-x64-runtime-pack.ps1
$pack = Get-ChildItem -LiteralPath build -Filter "Vibecrafted_RuntimePack_*-win32-x64.tar.gz" |
Sort-Object LastWriteTime -Descending | Select-Object -First 1
if (-not $pack) { throw "Windows Runtime Pack missing under build" }
Continue only after the builder exits 0; do not select a historical pack after
a failed build. Expected: a version/date/SHA-named pack, sibling .sha256 and .sig.
The builder includes Python, vc-server, vc-terminal and vc-frame; foundations
come from their own channels. It fetches donors pinned by revision and archive
hash. If cargo-leptos is present it builds the web assets; otherwise the builder
uses the native SSR Cargo fallback.
Source: Windows workflow → “Build Windows Runtime Pack”; builder → server build, donors, embedded Python, signing.
W4. Select the development trust anchor, then install
A local build without the product key creates a rehearsal signature and
$pack.FullName.rehearsal.pub. Select that anchor only for your local build:
$env:VIBECRAFTED_RUNTIME_PACK_PUBLIC_KEY = "$($pack.FullName).rehearsal.pub"
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Pack $pack.FullName
Expected: a human install summary and the per-user launcher directory
%LOCALAPPDATA%\Vibecrafted\bin. Published product packs use the committed
vibecrafted-signing-v1.pub instead; leave the override unset for those.
Missing .sha256, .sig or trusted key fails before extraction.
Never treat a rehearsal key next to a downloaded artifact as release trust.
Source: Windows workflow → “Cold install into disposable LOCALAPPDATA” (CI trust override); builder → rehearsal signing; install.ps1 → preflight and User PATH.
W5. Verify from the installed launcher
$bin = Join-Path $env:LOCALAPPDATA "Vibecrafted\bin"
$env:Path = "$bin;$env:Path"
& (Join-Path $bin "vibecrafted.cmd") doctor
Expected: exit 0 and explicit not supported on Windows declarations.
Native dashboard, start, init and other POSIX deck commands return exit 2
with a WSL2 next step. voc, vc-o, vc-admin, vc-procs, vc-start,
rescue/flock and PTY/zsh shells are not a native managed-workspace path.
A doctor pass does not establish those capabilities. For a first native agent
session or WSL2 workspace, follow the Entry book.
Source: Windows workflow → “Cold install into disposable LOCALAPPDATA”, “vibecrafted doctor from installed launcher”; core CLI → win32 lifecycle refusal.
W6. Build and exercise the unsigned MSI/EXE carriers
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-windows-installers.ps1
Expected: carriers under packaging\windows\out with adjacent checksums.
MSI/EXE are unsigned Authenticode; SmartScreen warns. Trust is .sha256
plus the pack’s .sig and trusted key. The wrapper checksums alone do not
authenticate a publisher; the workflow only lists .sha256 for MSI/EXE, not
standalone wrapper .sig files. Their embedded Runtime Pack is signature-checked.
For disposable per-user install testing, substitute the exact paths emitted
above and run one installer at a time. The install command is the default
EXE action; do not add /install.
$msi = (Resolve-Path "packaging\windows\out\<exact-name>.msi").Path
$proc = Start-Process msiexec.exe -ArgumentList "/i `"$msi`" /qn /l*v `"$PWD\msi-install.log`" VC_SKIP_TERMINAL_LAUNCH=1" -Wait -PassThru
$proc.ExitCode
vibecrafted doctor
$stable = (& python scripts/windows_product_code.py).Trim()
$proc = Start-Process msiexec.exe -ArgumentList "/x `"{$stable}`" /qn /l*v `"$PWD\msi-uninstall.log`"" -Wait -PassThru
$proc.ExitCode
$exe = (Resolve-Path "packaging\windows\out\<exact-name>.exe").Path
$proc = Start-Process $exe -ArgumentList "/quiet /norestart /log `"$PWD\exe-install.log`" VC_SKIP_TERMINAL_LAUNCH=1" -Wait -PassThru
$proc.ExitCode
vibecrafted doctor
$proc = Start-Process $exe -ArgumentList "/uninstall /quiet /norestart /log `"$PWD\exe-uninstall.log`"" -Wait -PassThru
$proc.ExitCode
Expected: each process exits 0; doctor has no failures; uninstall removes the
product-owned per-user PATH entry and installed payload. Use logs to diagnose a
nonzero exit. MSI install logs contain Skipping action: LaunchVcTerminal (condition is false); quiet EXE also skips terminal launch. The workflow runs
MSI and EXE round trips on separate runners to avoid their shared ProductCode.
These commands uninstall the test installation; do not run them over an active
workspace. For script-installed packs, use install.ps1 -Uninstall instead.
Source: Windows workflow →
windows-installers, windows-msi-install, windows-exe-install / silent
install, doctor and silent uninstall steps;
installer builder.
W7. Choose the Windows gate surface
python -m pytest tests/tui/test_windows_installers.py -q
Expected: a nonempty pytest summary. Native PowerShell does not turn POSIX
make check, Bash tests or zsh entry into native equivalents. Run the POSIX
source gates in WSL2 (Linux steps L1–L8); the Windows workflow is the actual
native carrier install/doctor/uninstall gate.
Source: Windows installer tests;
Makefile → check, test;
Windows workflow.
macOS maintainers
The Linux/Windows recipes above do not build the macOS App. For the signed, notarized and stapled desktop handoff, follow INSTALL → desktop artifact and the release checklist. Signing credentials remain local; a successful local build does not establish publication.