Getting started

Morphz ships as a prebuilt native binary with the Dashboard embedded. The first-run path covers installation, model configuration, and a live response check.

Prerequisites

• macOS 11 or newer on Apple Silicon or Intel, ARM64 or x86_64 Linux with glibc 2.35 or newer, or x86_64 Windows;
• Access to at least one model service;
• Read and write access to the working directory.

Local command execution on Linux also requires Bubblewrap and working unprivileged user namespaces. The installer checks this boundary and prints a remediation when the host is not ready. Installing the operating-system package may require administrator access; the Morphz binary itself does not.

Install with one command

macOS and Linux:

curl -fsSL https://morphz.ai/install.sh | sh -s -- setup

Windows PowerShell:

irm https://morphz.ai/install.ps1 | iex

The installer shows its detection, download, verification, installation, and PATH configuration stages. It downloads the matching archive from GitHub Releases, verifies its SHA-256 checksum, and installs into the user directory without requiring root access. The setup argument starts Setup directly from the installer; new terminals can invoke morphz directly.

Updates are explicit and reuse the same verified GitHub Release assets:

morphz update status
morphz update

A successful update retains the previous main binary; use morphz update rollback when needed.

Complete Setup

Setup opens the Dashboard wizard by default. On an interactive SSH or headless Linux session it selects the terminal wizard automatically:

morphz setup

Use the full-screen terminal wizard on SSH hosts or systems without a browser:

morphz setup --tui

To print the Dashboard URL without opening a browser:

morphz setup --no-open

A successful Setup persists a complete model service, auth account, and model route. An OAuth account becomes selectable after its login flow completes successfully.

Verify the model path

Run the structural diagnostics first:

morphz doctor

Then open Model Services in the Dashboard and test the account. Authentication confirms that credentials are stored; the account test also verifies the selected account, physical model, and live request path, and reports elapsed time or errors.

Start the first conversation

Launch the interactive interface:

morphz

Or provide a prompt directly:

morphz inspect this project and explain what you can access

When the Dashboard displays a model response, the model path is verified and Morphz is ready for work. If the page shows only user messages, keep the current Session and trace its model request path with Operations and troubleshooting.

Build from source

From the repository root, use the Rust toolchain pinned by rust-toolchain.toml:

cargo build --release

The resulting binary is target/release/morphz. Source builds support development, review, and independent reproduction; ordinary users can use the one-command installer above.

Next steps

• Read Core concepts to distinguish Contexts from Sessions;
• Read Sessions and concurrent work to understand independent workstreams over shared cognition;
• Read Cognitive Applications, Harnesses, and Yao to bind domain practice to an Objective;
• Read Model services, accounts, and routes to understand the model selector;
• Read Remote OAuth before deploying on a remote host.