Install
Install Vibecrafted on macOS (one command, no Xcode), Linux, or native Windows (win32-x64 Runtime Pack), and verify the result with doctor.
Canonical source — docs/public/getting-started/install.md
Install
Vibecrafted runs on macOS, Linux, and native Windows (win32-x64 Runtime Pack).
Pick the section for your platform, then verify the result with
vibecrafted doctor.
The canonical download page is
vibecrafted.io/en/install
(PL). The release it serves is the one
named by https://vibecrafted.io/channel/main.json; that manifest, not this
page, is the authority for the current version.
macOS (14+, Apple Silicon) — the ordinary path
You do not need Xcode, Command Line Tools, Swift, Make, a Python of your own, or a source checkout. Open Terminal and run one command:
curl -fsSL https://vibecrafted.io/install.sh | bash
On a supported Mac this installs the signed Vibecrafted.app and the
matching runtime together, so you do not need to download the DMG first. The
installer asks for consent before it changes anything and keeps your existing
shell, Terminal and Frame configuration and any running sessions.
When it finishes, open a new terminal and check the result:
vibecrafted --version
vibecrafted doctor
To read the script before running it:
curl -fsSL https://vibecrafted.io/install.sh -o install.sh
less install.sh
bash install.sh
Prefer the app? Download the DMG
- Open vibecrafted.io/en/install and use Download macOS app. The DMG is Developer ID signed and notarized.
- Open the DMG and drag
Vibecrafted.appto Applications, then launch it. - If the app offers to install or upgrade the Vibecrafted tools on first start, accept. Otherwise publish them from the menu bar: Vibecrafted → Republish anyway… and confirm.
Dragging the app into Applications does not by itself install the
vibecrafted command or the runtime. Until step 3 has run you can have a
current app next to an older (or absent) command line. Republish anyway…
installs the runtime generation carried inside the app you just opened; it does
not download a newer app and does not need a source checkout or Xcode.
Updating on macOS
Re-running the one-command install pairs the app and the runtime again. The
in-app Check for Updates works only once a newer release is actually
published on the update feed; if none is, nothing is fetched. Republish anyway… is not an update check — it reinstalls what the app already carries.
Linux and WSL2
curl -fsSL https://vibecrafted.io/install.sh | bash
The bootstrap installs the release bound by the website channel manifest; it
does not follow a Git branch. Confirm what you received with
vibecrafted --version.
The installer detects your platform and Linux distribution family first, reports
every missing prerequisite in one pass instead of failing one tool at a time,
and stages a versioned runtime generation under
~/.local/share/vibecrafted/tools/.
The no-toolchain macOS path above is a darwin-arm64 carrier. It does not cover Intel Macs or Linux, and the signed App exists only for macOS. Those platforms keep their own requirements — a platform-matching Runtime Pack or the source toolchain described in Build from source.
Linux is a first-class runtime
The Linux install path is gated on pushes and pull requests to main,
develop and release/*. .github/workflows/install-linux.yml builds a Linux
x64 Runtime Pack on Ubuntu 22.04, then installs it with this tree’s
install.sh on Ubuntu 22.04, Ubuntu 24.04 and debian:bookworm-slim, and runs
vibecrafted doctor. The 22.04 and Debian jobs explicitly waive foundations;
24.04 keeps the hard foundation gate. CI installs from the checkout, not from
the published website channel.
The macOS-only surfaces are the desktop app, notarization, and the locterm
runtime. The command deck, control plane, dispatch, skills, and settlement
ledger all run on Linux.
Windows
The native Windows product is the win32-x64 Runtime Pack. It does not require WSL. From a checkout:
powershell -NoProfile -File .\scripts\build-windows-x64-runtime-pack.ps1
powershell -NoProfile -File .\install.ps1 -Pack .\build\Vibecrafted_RuntimePack_<version>-<YYYYMMDD>-<sha8>-win32-x64.tar.gz
Canonical MSI/EXE names look like
Vibecrafted_<version>-<YYYYMMDD>-<sha8>-windows-x64.msi (unsigned
Authenticode — SmartScreen will warn; trust is .sha256 + .sig).
Runtime home is %LOCALAPPDATA%\Vibecrafted. Launchers are *.cmd under
%LOCALAPPDATA%\Vibecrafted\bin. tools/vibecrafted-current is a directory
junction. PTY/zsh, flock/rescue, and voc are not supported on native Windows
(vibecrafted doctor declares them).
install.ps1 delegates to scripts/install-runtime-pack.ps1 when a pack is
present. Without a pack it prints the exact next command and exits non-zero.
First-run: vibecrafted doctor then vibecrafted init.
WSL2 remains a POSIX alternative: install WSL2, then use install.sh inside
the distro. That is not the native Windows product.
Advanced: App and Runtime Pack by hand
Ordinary users do not need this section. The one-command install and the DMG above already carry everything.
The separate GitHub Releases publisher lists versioned carriers and their checksums. Its latest release can differ from the website channel; choose the matching App and Runtime Pack from one release.
The signed App is one Developer ID signed and notarized artifact carrying
matching builds of vc-terminal, vc-frame, vc-start and the complete
Vibecrafted runtime; no companion repository installer is required. The App
and its Runtime Pack are paired — a fixed host needs both from the same
release, not one without the other.
To verify a downloaded DMG yourself, fetch the .dmg and its adjacent
.dmg.sha256 from the carrier named by the website channel manifest (GitHub
Releases is a separate publisher and its latest is not that carrier), then:
shasum -a 256 -c Vibecrafted_<version>-<YYYYMMDD>-<sha8>.dmg.sha256
The same release carries
Vibecrafted_RuntimePack_<version>-<YYYYMMDD>-<sha8>-darwin-<arch>.tar.gz, its
.sha256, and detached .sig. It is built from the exact Runtime Pack inside
the signed App and adds only the bundled terminal and native vc-frame helper.
From a source checkout:
make install RUNTIME_PACK=../Vibecrafted_RuntimePack_<version>-<YYYYMMDD>-<sha8>-darwin-<arch>.tar.gz
make uninstall
Both commands use the pack-owned Python and vetcoders_install.py. Installation
writes one ownership receipt; uninstall refuses modified managed files, restores
pre-existing collisions, and prunes only directories that receipt proves the
installer created.
Portable source channel — Linux, WSL2, source fallback
Apple notarization cannot reach these systems, so the same release carries a
second canonically named artifact:
Vibecrafted_<version>-<YYYYMMDD>-<sha8>-portable.tar.gz plus its adjacent
.sha256.
curl -fsSLO https://github.com/vetcoders/vibecrafted/releases/download/v<version>/Vibecrafted_<version>-<YYYYMMDD>-<sha8>-portable.tar.gz
curl -fsSLO https://github.com/vetcoders/vibecrafted/releases/download/v<version>/Vibecrafted_<version>-<YYYYMMDD>-<sha8>-portable.tar.gz.sha256
sha256sum -c Vibecrafted_<version>-<YYYYMMDD>-<sha8>-portable.tar.gz.sha256
tar -xzf Vibecrafted_<version>-<YYYYMMDD>-<sha8>-portable.tar.gz
bash vibecrafted-<version>/install.sh --runtime-pack-file /absolute/path/to/matching-pack.tar.gz install
What the tarball is, and what it is not:
- It is an allowlisted projection of one exact commit, not a
git archiveof a working tree. Development artifacts are excluded by construction, and every required runtime path must be present or the packer refuses to write. - It carries a closed
source-provenance.json: schemavibecrafted.source-provenance.v2, avibecrafted.distribution-tree.v1digest over every entry, bound to the commit the release was cut from.install.shre-validates that carrier before it stages anything. - It is not a prebuilt-binary bundle. Product launchers and native
vc-terminal/vc-framehosts stay on the Runtime Pack.--skills-onlyinstalls skill views from source; it does not claim a complete native runtime. - Linux prebuilt packs (
linux-x64,linux-arm64) are built natively byscripts/build-linux-runtime-pack.shand are not produced by macOSmake release. Vibecrafted does not ship a systemd unit; start the server and guardian withvibecrafted server start. - On Windows, use the native win32-x64 Runtime Pack. The portable Linux tarball is the POSIX alternative inside WSL2.
The checksum proves the bytes survived the wire. The provenance carrier proves
they are the distribution they claim to be, pinned to one commit — the part
curl | bash, which follows the website channel, cannot give you.
Runtime boundary
Every new or restored workspace has a durable workspace_id and enters through
the bundled vc-start. The app sources an app-owned XDG/runtime environment and
does not overwrite your terminal, shell, Zellij or vc-frame configuration.
vc-terminal and vc-frame do not have independent app, DMG, installer or
update channels.
The server endpoint is read from Vibecrafted settings and may be any host:port,
for example http://127.0.0.1:3024. It is never baked into the app.
Container
docker build -t vetcoders/vibecrafted:local .
docker run --rm -it -v "$PWD:/workspace" vetcoders/vibecrafted:local version
Verify
vibecrafted doctor
vibecrafted version
doctor distinguishes what is broken from what is merely absent. On a plain
install, externally managed foundations you have not installed are reported as
warnings rather than failures. Anything reported red is genuinely wrong.
Next
- First run — what happens on your first command, and what to do when an agent CLI is missing.
- Build from source — the checkout path, the target surface, and building your own artifact.
- Quick start — your first workflow.
- Update and rollback — runtime generations and pointer rollback.