Installation
Touba provides a standalone CLI for macOS, Linux and Windows, plus a VS Code extension. Choose your platform in the Hub. Each resource lists its version, prerequisites and file SHA-256.
The macOS Apple Silicon and Intel installers are signed and notarized by Apple.
Choose your installation
| Platform | System prerequisites | Installer | Standalone archive |
|---|---|---|---|
| macOS Apple Silicon | macOS 13.5 or later, arm64 | .dmg | .tar.gz |
| macOS Intel | macOS 13.5 or later, x64 | .dmg | .tar.gz |
| Linux x64 | Ubuntu 24.04 or compatible system, glibc 2.39+ | .deb | .tar.gz |
| Windows x64 | 64-bit Windows, x64 | .exe | .tar.gz |
Archives include the compiler, Node runtime, Touba commands and both SDK archives. Using the CLI requires no separate Node, Rust, Cargo or pnpm installation. Prerequisites for JavaScript and Python host applications are listed below.
Using an installer
- macOS: open the DMG, then Install Touba.app. Installation is per user.
- Windows: run the EXE and follow the per-user setup wizard.
- Linux: open the DEB with your software manager, or run
sudo apt install ./touba-v1.0.0-linux-x64-setup.deb. This is a system installation.
Windows and SmartScreen
The current Windows installer is unsigned. SmartScreen may display “Windows protected your PC” for an application with little download history. This reputation warning alone does not mean malware has been detected. Microsoft explains these checks.
-
Download the installer from the Hub and compare its SHA-256 hash with the one shown under Details:
Get-FileHash .\touba-v1.0.0-win32-x64-setup.exe -Algorithm SHA256 -
If the source and hash match, you trust the file, and the message concerns only an unrecognized application, choose More info, then Run anyway, if Windows offers that option.
-
If a threat is detected, the hash differs, or your organization blocks execution, stop the installation and contact your administrator or the Touba team.
Keep SmartScreen and antivirus protection enabled, whichever browser you use. Windows publisher signing is planned: the team is preparing this improvement as listed in the roadmap. A signature identifies the publisher; reputation also builds over time.
Using an archive
Download your platform’s file from the Hub and extract it. For example, on macOS Apple Silicon:
tar -xzf touba-v1.0.0-darwin-arm64.tar.gz
sh touba-v1.0.0-darwin-arm64/install.sh
For Intel Mac, use darwin-x64; for Linux, use linux-x64 in the file and
directory names. The default installation prefix is $HOME/.touba.
The script offers to add its bin directory to PATH.
tar -xzf touba-v1.0.0-win32-x64.tar.gz
& .\touba-v1.0.0-win32-x64\install.ps1 -Prefix "$HOME\.touba"
On Windows, follow your organization’s execution policy.
Add $HOME\.touba\bin to your user PATH if needed.
Then open a new terminal.
Verify the download
Compare the result with the hash shown under Details in the Hub:
shasum -a 256 touba-v1.0.0-darwin-arm64.tar.gz
sha256sum touba-v1.0.0-linux-x64.tar.gz
Get-FileHash .\touba-v1.0.0-win32-x64.tar.gz -Algorithm SHA256
Use the name of your downloaded file, whether an archive or installer.
Choose your application's SDK
The CLI runs Touba programs. An SDK is a dependency of your host application, installed from its root:
| Application | Command | Prerequisites |
|---|---|---|
| JavaScript, or TypeScript consuming the JavaScript SDK | touba sdk install javascript | Node.js 24.22.1+ (24.x) and npm |
| Python | touba sdk install python | Python 3.11+ with uv, or venv and pip |
Both SDKs can coexist. Python creates or reuses .venv; nothing is installed
globally. Touba verifies the bundled archives, copies them into
vendor/touba-sdk/<hash>/, and installs offline. Commit this folder and your
dependency declarations, not node_modules or .venv.
touba sdk --help
touba sdk install python --python python3.12
touba sdk install python --manager uv
touba sdk path javascript
touba sdk path python
--python selects the interpreter when creating a venv. sdk path returns
a verified archive for your own dependency manager. Projects using pnpm/Yarn/Bun
keep their manager: sdk install javascript refuses to create a competing npm lockfile.
For handlers, choose touba init --language javascript or
touba init --language python. prepare then generates files and tests
in that language. Installing an SDK changes neither the .tb program,
its governance nor an existing project’s host-language choice.
See the JavaScript and Python guides.
After a CLI upgrade, rerun sdk install in each app you want to update, then
its business tests. Other applications remain unchanged.
Install the VS Code extension
Install Touba Language Toolkit from the Visual Studio Marketplace, or use the VS Code command:
code --install-extension touba.touba-tools
On macOS, if you get zsh: command not found: code, follow the steps to
enable the VS Code command.
You can also search for @id:touba.touba-tools in VS Code’s Extensions view
and select Install, without using the terminal.
The Marketplace selects your platform. For a VSIX file from the Hub, open Extensions → … → Install from VSIX… and choose the file for your system. VS Code 1.119.0 or later is required.
The extension provides diagnostics and editor tools. Install the CLI as well
for terminal commands. Run Current File can also use the extension’s
bundled runtime for self-contained files.
The extension checks TOUBA_CLI_PATH in the environment that launches VS Code,
then touba on PATH, then $HOME/.touba/bin/touba.
An invalid explicit path is reported. After changing it, restart VS Code
and run Touba: Check CLI.
Verify installation
touba version
touba doctor
Continue with your first program. The
CLI reference covers commands and options.
touba update --json reports the installed build and update information.
Update or uninstall
Stop Touba services before replacing the toolchain. For a macOS or Linux
archive, run the new install.sh --force; for Windows, run the new
install.ps1 -Force. Projects and their SDKs are updated separately.
To remove an archive installation, use its uninstall.sh or uninstall.ps1
with the same prefix. For the DEB, use your package manager. The next section
describes backup and recovery for projects with pending work.
Change builds without losing pending work
The product version, build fingerprint and data contracts are distinct.
Development builds may share the same version number while having incompatible
state contracts. Stop the service first. Back up the project, sources,
configuration, .touba/, effect journals, evidence and any explicitly
configured external store paths together. Copying a live SQLite file is not
a complete backup.
Run the candidate CLI against the stopped project:
/path/to/candidate/bin/touba serve --project-root . --check-state
The touba-state-preflight-v1 JSON report lists checked stores, active waits,
candidate build and known origin. It does not load providers or run handlers,
expiry timers or recovery. structurally_valid describes structural checks,
not a business migration. unrecorded provenance stays unknown. A recorded
origin from another project or build is refused. Do not edit origin metadata
to bypass this check.
Archive scripts and macOS/Windows wizards preserve the previous payload under builds/<fingerprint>/ in
the installation prefix. Its own bin/touba remains usable to finish pending
work with its original build. Do not run two builds against the same stores.
--force replaces the active build without deleting recovery archives.
The DEB package replaces the system toolchain under /opt/touba/toolchain.
Before updating it, keep a separate copy of the build needed for pending work.
If the candidate refuses the state, keep it offline or finish pending work with the original build. There is no automatic migration or old-format runtime reader. Restoring files does not undo external effects: inspect the effect journal before resuming, and do not restart the workflow from its beginning. Keep the build archive and backup while pending work or audit duties require them.