A clear path to
your first prompt.

Before you begin

1. A supported system and shell: macOS or Linux on amd64/x86_64 or arm64/aarch64, or FreeBSD on amd64. Use Bash, zsh, or Fish. Arch packages are x86_64 only. There is no native Windows/PowerShell installer.
2. Download access: a working internet connection and trusted HTTPS access to GitHub, the selected package repository, and your model provider. Local inference still needs an initial model download.
3. Permissions: a writable home directory for per-user assets. Linux system packages and macOS .pkg need administrator access; run Homebrew and ash install as your normal user.
4. A model: either a local inference server with a downloaded model or a cloud account/API key. Choose a model that supports tool calling, not an image/audio-only model. Local RAM, disk, and GPU needs depend on that model.

Prebuilt ash packages do not require Go, Rust, Node.js, or Xcode build tools. A package manager may have its own prerequisites; follow its official setup instructions first.

macOS

Recommended: Homebrew

Prerequisites: Homebrew, its supported macOS environment, and a working brew command. The tap selects the Intel or Apple Silicon archive automatically. Homebrew 6 does not implicitly trust this third-party tap. If Homebrew refuses to load the formula as untrusted, review the publisher and formula, then trust only this formula (not the entire tap):

brew trust --formula jonconradt/ash/ash
brew install Jonconradt/ash/ash
ash version

Homebrew remembers this local trust decision. The tap cannot enable trust on your behalf; trusting the whole tap with brew trust jonconradt/ash is broader and permits loading its other formulae too. To trust Beta or Nightly instead, use the corresponding formula name, jonconradt/ash/ash-beta or jonconradt/ash/ash-nightly. Homebrew owns the binaries, bundled native plugins, man pages, and license notices in its prefix (normally /opt/homebrew on Apple Silicon or /usr/local on Intel). It checks the archive against the formula's SHA-256 checksum. It does not configure your provider or edit your shell startup file: continue to per-user initialization. Use brew upgrade ash for updates and brew uninstall ash to remove Release; see channel formulas for Beta/Nightly.

Alternative: native .pkg

Download the darwin-arm64.pkg asset for Apple Silicon or darwin-amd64.pkg for Intel from a published release. Verify its signed checksum manifest before opening the installer. Administrator access is required.

The package writes ash and ash-broker to /usr/local/bin, plugins to /usr/local/lib/ash/plugins, man pages to /usr/local/share/man, and notices to /usr/local/share/licenses/ash. The receipt is dev.ash.cli. It does not run per-user initialization or subscribe to updates: initialize after installation, replace it with a verified newer .pkg to update, and use the manual removal procedure to uninstall. Do not install it over a Homebrew-owned copy.

Linux

Use your distribution's package manager where possible. These packages own /usr/bin/ash, /usr/bin/ash-broker, /usr/lib/ash/plugins, man pages under /usr/share/man, and license notices. They leave provider settings and shell hooks to per-user initialization.

Debian and Ubuntu: APT

Prerequisites: amd64 or arm64, administrator access, APT, curl, gpg, and CA certificates. Install missing download/key tools using your distribution before adding the repository. Release is named stable:

sudo apt update
sudo apt install ca-certificates curl gnupg
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://www.versionx.ai/apt/gpg.key -o versionx-apt.asc
gpg --show-keys --with-fingerprint versionx-apt.asc
sudo gpg --dearmor --batch --yes -o /etc/apt/keyrings/versionx-keyring.gpg versionx-apt.asc
sudo chmod 0644 /etc/apt/keyrings/versionx-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/versionx-keyring.gpg] https://www.versionx.ai/apt stable main" |
  sudo tee /etc/apt/sources.list.d/versionx.list
sudo apt update
sudo apt install ash
rm versionx-apt.asc

Before importing any repository key, verify its fingerprint against a trusted publisher source. The VersionX key fingerprint is 32C6 C11D 2F86 BFE4 6EB7 7FFC 5257 FEA6 1368 919F. APT checks signed repository metadata and the package digests it contains; the key is scoped with signed-by. Update with sudo apt update && sudo apt upgrade ash; remove with sudo apt remove ash.

Fedora and RHEL-compatible systems: DNF

Prerequisites: x86_64 or aarch64, administrator access, DNF/RPM, curl, gpg, and CA certificates. Install missing tools from your distribution. Inspect the key and compare the fingerprint above before importing it:

curl -fsSL https://www.versionx.ai/rpm/gpg.key -o versionx-rpm.asc
gpg --show-keys --with-fingerprint versionx-rpm.asc
sudo rpm --import versionx-rpm.asc
sudo tee /etc/yum.repos.d/versionx.repo >/dev/null <<'EOF'
[versionx]
name=VersionX ash repository
baseurl=https://www.versionx.ai/rpm/
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://www.versionx.ai/rpm/gpg.key
EOF
sudo dnf install ash
rm versionx-rpm.asc

RPM files are not individually signed. repo_gpgcheck=1 verifies repository metadata covering their checksums; gpgcheck=0 reflects the absent per-package signatures, not disabled repository verification. If your policy requires signed RPM payloads, this repository does not meet it. Update with sudo dnf upgrade ash; remove with sudo dnf remove ash.

Arch Linux: Pacman

Prerequisites: x86_64, administrator access, Pacman with its keyring initialized, curl, and gpg. Verify the displayed key fingerprint matches the one above before trusting it. Add the repository once, not on every update:

curl -fsSL https://www.versionx.ai/pacman/gpg.key -o versionx-pacman.asc
gpg --show-keys --with-fingerprint versionx-pacman.asc
sudo pacman-key --add versionx-pacman.asc
sudo pacman-key --lsign-key 32C6C11D2F86BFE46EB77FFC5257FEA61368919F
sudo tee -a /etc/pacman.conf >/dev/null <<'EOF'
[versionx]
Server = https://www.versionx.ai/pacman/$arch
SigLevel = Required DatabaseRequired
EOF
sudo pacman -Syu ash
rm versionx-pacman.asc

Pacman verifies both package and database signatures. Keep Arch synchronized with sudo pacman -Syu, not a partial upgrade; remove ash with sudo pacman -R ash.

Other Linux installation methods

Already using Homebrew on Linux? The same tap instructions support amd64 and arm64; Brew owns these files, not APT/DNF. Otherwise, use a verified script/archive installation or a matching .deb/.rpm download. Install a verified .deb with sudo apt install ./PACKAGE.deb, or a .rpm with sudo dnf install ./PACKAGE.rpm (replace the filenames). A direct package remains package-manager-owned, but does not add a repository or automatically subscribe to future releases. The current RPM payload is unsigned; follow your distribution's policy rather than disabling signature checks.

FreeBSD

Prerequisites: amd64, Bash (even when your interactive shell is zsh or Fish), download/verification tools, and a writable installation directory. Install Bash using FreeBSD's native manager:

sudo pkg install bash

FreeBSD's pkg manages prerequisites, not ash: there is currently no ash .pkg repository and no arm64 release archive. Use the verified script, or verify a FreeBSD amd64 tarball, extract it into a temporary directory, and install its versioned ash binary as ~/.local/bin/ash alongside ash-broker. Copy its native plugins to $XDG_DATA_HOME/ash/plugins (default ~/.local/share/ash/plugins), then initialize. You own these files; pkg delete will not remove them. Use Release self-updates in the default location or manually replace verified artifacts.

Initialize and verify

After installing binaries, run setup interactively as your normal user. If you do not want shell integration, you can install only Ash. This is probably not what you want. The real value of ash is the shell integration below. Assets-only setup leaves your startup files unchanged:

ash install

The install you likely want to use involves shell integration. This will change your .bashrc (or the equivalent for your shell) to include Ash. To enable command-not-found integration, choose exactly one command for the shell you use:

Bash

ash install --shell bash --shell-integration

zsh

ash install --shell zsh --shell-integration

Fish

ash install --shell fish --shell-integration

Bash uses ~/.bashrc, zsh uses ~/.zshrc, and Fish uses $XDG_CONFIG_HOME/fish/config.fish (default ~/.config/fish/config.fish). Open a new shell afterward; existing shells retain their running broker. Integration prepends ~/.local/bin to PATH: remove an old user-local copy before expecting a system package to be selected.

If provider settings are missing, setup detects existing provider keys or a running local server; otherwise it offers a provider menu and prompts for credentials. Pick an available tool-capable model. Existing valid settings are preserved, so rerunning setup is not a provider-switch command.

Settings are stored in $XDG_CONFIG_HOME/ash/.ash_env (default ~/.config/ash/.ash_env, private file permissions). Managed integration loads them. Without integration, Bash/zsh users can source that file in their normal startup configuration; Fish users should set the corresponding ASH_AI_* variables using Fish syntax, not source the Bash-format file. Protect any file containing tokens and never commit it.

For a user-local install without integration, add its actual directory to PATH. Bash/zsh: export PATH="$HOME/.local/bin:$PATH". Fish: fish_add_path "$HOME/.local/bin". Persist this using your shell's startup configuration; substitute your custom installation directory when applicable.

command -v ash
command -v ash-broker
ash version
ash "Say hello in one sentence"

The first commands should resolve to the installation you chose. The prompt needs a running server or valid cloud credentials; installing ash does not install a model.

Local Ollama: no cloud account required

You do not need to have a local AI to use ash. However, if you want to run models locally without relying on a cloud provider, you can set up a local Ollama server.

Ollama also offers a cloud service for running models remotely, but that is not required for local usage with ash. The cloud server includes a free tier and Google's Gemma 4 31b cloud model (gemma4-31b:cloud) works very well with ash. This is the model used by the project to generate release notes and perform devops tasks.

Install Ollama using its official OS instructions. Start the Ollama app/service, or run ollama serve in a separate terminal if a server is not already running. On FreeBSD, ash's support does not imply a native Ollama installer: use a reachable server on another supported host if needed.

Download a tool-capable model that fits your hardware; llama3.1:8b is an example, not a minimum requirement. Check the current tools catalog for alternatives:

ollama pull llama3.1:8b
ollama list
curl -fsS http://localhost:11434/api/tags
ash install

With no cloud keys already set, setup can detect the local server and offer the downloaded model. If another provider is already configured, manually change the endpoint/model instead. Bash/zsh example:

export ASH_AI_ENDPOINT="http://localhost:11434"
export ASH_AI_MODEL="llama3.1:8b"
unset ASH_AI_AUTH_TOKEN
ash "Say hello in one sentence"

Fish equivalent:

set -gx ASH_AI_ENDPOINT http://localhost:11434
set -gx ASH_AI_MODEL llama3.1:8b
set -e ASH_AI_AUTH_TOKEN
ash "Say hello in one sentence"

These changes affect the current shell only. Persist them in your protected ash environment file or appropriate shell configuration, replacing any old provider overrides. Local Ollama does not need a token. Keep the server on loopback unless you deliberately secure access; a remote server receives your prompts and tool output.

Optional: set OLLAMA_KEEP_ALIVE=30m in the Ollama server's environment and restart the server to keep models warm. -1 keeps them loaded indefinitely but consumes memory between requests. Setting this only in the ash client terminal does not reconfigure an already running server.

Local inference has no provider API bill, but uses your hardware/storage/electricity. Ollama cloud is a separate service with authentication and plan limits; it is not the same as this local setup.

Free cloud tiers

Create a provider key using the links below, then run ash install interactively and choose that provider. Setup prompts for the token and lists models where supported. Choose a currently available free-tier text model with tool calling; listing a model does not guarantee it is free for your account.

Already exporting a recognized provider key? Setup detects it; if several keys exist, it asks you to choose. Do not paste real keys into command history, recordings, or source code. The configuration file contains a secret, not an encrypted vault.

Manual configuration or switching providers

Replace the endpoint below with the table's value and MODEL_ID with a model verified in your provider account. If your key is already exported as GROQ_API_KEY, this Bash/zsh example reuses it without typing the secret:

export ASH_AI_ENDPOINT="https://api.groq.com/openai/v1"
export ASH_AI_MODEL="MODEL_ID"
export ASH_AI_AUTH_TOKEN="$GROQ_API_KEY"

Fish equivalent:

set -gx ASH_AI_ENDPOINT https://api.groq.com/openai/v1
set -gx ASH_AI_MODEL MODEL_ID
set -gx ASH_AI_AUTH_TOKEN "$GROQ_API_KEY"

For Gemini or OpenRouter, use their endpoint and recognized key variable instead. Save the chosen settings securely for future shells. Cloud endpoints require HTTPS and a token; local HTTP is not a shortcut for a cloud service. See the environment reference and other supported providers for paid services and advanced overrides.

Script installation: an alternative, not the first choice

Prefer Homebrew, APT, DNF, or Pacman: they track owned files, verify downloads using their trust configuration, and provide familiar updates/removal. They still require trusting publishers and package install actions.

Prerequisites: a supported OS/architecture, $SHELL identifying Bash/zsh/Fish, Sigstore cosign, tar, uname, install, standard shell utilities, a SHA-256 command (sha256sum, shasum, or sha256), and a downloader (curl, wget, or Python). The example uses curl. FreeBSD also needs Bash. Your home/installation directory must be writable.

Download to a local file, inspect it with an editor, and execute only if you trust its source and behavior. Inspection is not a guarantee of safety; do not run these steps blindly:

curl -fsSL https://jonconradt.github.io/ash/install.sh -o ash-install.sh
less ash-install.sh

After inspection, run the saved copy as your normal user:

sh ./ash-install.sh
rm ./ash-install.sh

install.sh downloads the latest Release, verifies its Sigstore-signed checksum manifest and archive digest, and installs ash/ash-broker in ~/.local/bin. Native plugins go under $XDG_DATA_HOME/ash/plugins. It runs per-user setup and asks before enabling shell integration. Without an interactive terminal, provider/integration prompts may be skipped: run ash install interactively afterward.

You can set ASH_INSTALL_DIR before running the script to choose another destination. Add that destination to PATH yourself. Self-update is supported only under ~/.local/bin; custom destinations require manual replacement. The script has no Beta/Nightly selector.

Verify a direct package or archive

Prerequisites: cosign and a SHA-256 utility. From the same published release, download your package/archive, SHA256SUMS, and SHA256SUMS.sigstore.json. Work in a new directory. Replace vX.Y.Z with the exact tag, including a prerelease suffix if applicable:

cosign verify-blob SHA256SUMS \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/Jonconradt/ash/.github/workflows/release.yml@refs/tags/vX.Y.Z" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Only after that succeeds, compute your file's digest with shasum -a 256 PACKAGE on macOS, sha256sum PACKAGE on Linux, or sha256 -q PACKAGE on FreeBSD. Replace PACKAGE with the downloaded filename and compare it exactly with that filename's entry in the verified manifest. Stop on a missing entry or any mismatch. An unsigned checksum downloaded beside a file is not equivalent to verified publisher metadata.

Updates and the three channels

• Release (recommended): stable published versions such as vX.Y.Z; repository configuration calls this stable.
• Beta: prerelease testing, tagged vX.Y.Z-beta.N; expect changes and regressions.
• Nightly: recent default-branch changes, tagged vX.Y.Z-nightly.YYYYMMDD.N; the highest regression risk. Builds are scheduled but may be skipped when nothing changes or publishing fails.

A published release updates the corresponding Homebrew formula or signed Linux repository. You receive it when you run the owning manager's upgrade command (or your own OS update policy does). Publication, repository updates, and website deployment can lag one another; check availability before changing channels. ash does not silently install background binary updates.

Homebrew: install or switch formulas

For a fresh Beta/Nightly installation, use the corresponding full formula name above in brew install. When switching, first uninstall the currently installed formula: all three provide the same binaries. Example, Release to Beta:

brew uninstall ash
brew install Jonconradt/ash/ash-beta
brew update
brew upgrade ash-beta

Use ash-nightly for Nightly or ash for Release in the install/upgrade commands. Uninstall the old channel's actual formula, not always ash. User settings are retained; open a new shell after switching.

Linux: select one repository channel

APT: use the APT setup with exactly one distribution from the table. To switch an existing install, edit /etc/apt/sources.list.d/versionx.list, replacing stable with beta or nightly (or back to stable), then:

sudo apt update
sudo apt install --allow-downgrades ash

DNF: use the DNF setup with the selected baseurl. For an existing install, replace baseurl in /etc/yum.repos.d/versionx.repo, keeping its signature settings, then:

sudo dnf --refresh distro-sync ash

Pacman: use the Pacman setup with the selected Server URL. Keep the section name [versionx]: every channel publishes a database named versionx.db. Change the Server in that one section rather than adding a differently named database. To switch, including a downgrade:

sudo pacman -Syuu ash

Review the proposed transaction: returning to Release may downgrade ash, and Pacman's double u can downgrade other packages too. Back up configuration before switching. Afterwards use normal APT/DNF/Pacman upgrade commands from the OS sections; do not leave several ash channel sources enabled.

User-local Release updates

ash update

This verifies and installs a stable release only when the active ash executable is under ~/.local/bin. It also updates bundled assets/plugins, with choices for customized files. ash update --version vX.Y.Z selects a stable tag, not a channel; it is not a downgrade command. There is no --channel option. Package-manager installs, macOS .pkg installs, and custom script destinations must use their owning manager/installer instead. FreeBSD Beta/Nightly use manual verified archives, not a self-updater subscription. Open a new shell after updating.

Uninstall without removing unrelated files

1. Disable shell integration first

Before removing binaries, run the command for each shell where you enabled integration:

Bash

ash install --shell bash --disable-shell-integration

zsh

ash install --shell zsh --disable-shell-integration

Fish

ash install --shell fish --disable-shell-integration

If ash is already missing, edit the relevant startup file from initialization and remove only the block between # >>> ash install >>> and # <<< ash install <<<. Remove any ash-specific PATH/environment lines you added manually, not unrelated shell configuration. Close ash-enabled shells afterward so their shell-owned brokers exit.

2. Let the owning package manager remove its files

Homebrew (Release)

brew uninstall ash

APT

sudo apt remove ash

DNF

sudo dnf remove ash

Pacman

sudo pacman -R ash

Choose only your installation method; for Homebrew Beta/Nightly use ash-beta/ash-nightly. APT/DNF/Pacman remove package-owned binaries, plugins, and man pages, not your home-directory configuration/history. Do not manually delete package-owned files.

Optional repository cleanup: remove the ash source file /etc/apt/sources.list.d/versionx.list and its dedicated /etc/apt/keyrings/versionx-keyring.gpg, or the ash repository file /etc/yum.repos.d/versionx.repo, or the ash [versionx] section from /etc/pacman.conf. First check that no other packages use them. Remove an imported RPM/Pacman trust key only after confirming its fingerprint and that nothing else relies on it; never delete a distribution's shared keyring.

3a. Manual macOS .pkg removal

macOS Installer records a receipt but has no ash uninstaller. Confirm this is a .pkg installation, not Homebrew, and inspect its exact payload:

pkgutil --pkg-info dev.ash.cli
pkgutil --files dev.ash.cli

Using that receipt as the inventory, remove only its ash-owned files: /usr/local/bin/ash, /usr/local/bin/ash-broker, the files in /usr/local/lib/ash/plugins, /usr/local/share/man/man1/ash.1, the listed localized ash.1 pages, and notices in /usr/local/share/licenses/ash. Administrator privileges are needed. Check ownership if another installer has subsequently replaced these files; do not remove its copy. Remove empty ash-only directories, not shared /usr/local, bin, or man directories.

After removing the payload, optionally remove the receipt:

sudo pkgutil --forget dev.ash.cli

Forgetting a receipt does not remove any installed files. Preserve it until you have finished checking the payload.

3b. Manual user-local / Linux / FreeBSD archive removal

Locate the active copy with command -v ash and command -v ash-broker. For the default script installation, after disabling hooks, remove those two specific files:

rm "$HOME/.local/bin/ash" "$HOME/.local/bin/ash-broker"

For ASH_INSTALL_DIR or a manually extracted archive, remove only the actual installed ash/broker paths. Remove archive plugins/man pages/notices you installed using your original file inventory; script plugins are in the ash user-data directory. If files are under /usr/bin, check ownership first with dpkg -S /usr/bin/ash, rpm -qf /usr/bin/ash, or pacman -Qo /usr/bin/ash as appropriate. A package-owned copy must be removed through that manager, even if installed from a standalone download.

4. Optional: erase local settings, tools, and history

• Configuration: $XDG_CONFIG_HOME/ash, default ~/.config/ash.
• Data, plugins, and Python environment: $XDG_DATA_HOME/ash, default ~/.local/share/ash.
• History and state: $XDG_STATE_HOME/ash, default ~/.local/state/ash.
• Cache: $XDG_CACHE_HOME/ash, default ~/.cache/ash.
• Broker runtime: $XDG_RUNTIME_DIR/ash, or $XDG_STATE_HOME/ash/runtime when no runtime root is available.

Inspect your actual absolute XDG overrides before deleting only these ash subdirectories; never delete an XDG root or your home directory. After all ash-enabled shells have closed, remove leftover ash runtime files if needed. MCP OAuth credentials may also remain in the OS credential manager: remove ash-specific entries there and revoke access at the MCP provider. Revoke unused AI keys in their provider accounts; deleting a local file does not revoke a key. Do not uninstall Ollama/models, Python, or shared dependencies as part of ash removal.

Quick troubleshooting

Command not found or wrong version

Check PATH and command -v ash/command -v ash-broker. An old ~/.local/bin copy can shadow a package. Use one owner/channel at a time and open a new shell.

Provider menu did not appear

Run ash install from an interactive terminal. Existing valid settings are preserved; use manual configuration to switch providers. Without integration, ensure settings are exported into the CLI's environment.

No model or connection refused

For Ollama, confirm its server is running and ollama list includes your chosen model. For cloud services, check endpoint, model eligibility, HTTPS, token, and account quota; never share token-bearing logs.

Repository or channel unavailable

Check architecture and the published release/repository. Publication can lag; do not disable signature verification to work around an unavailable repository.

Python tool setup failed

Install Python with venv/ensurepip and allow dependency downloads, then rerun ash install. Basic ash remains usable without these tools.

Need more detail? See the command reference, FAQ, or report an issue without credentials.