documentation / getting started

Installation

Build Ashplug from source, initialize its configuration, and connect it to an AI provider. The commands below are taken from the project documentation.

01

Requirements

  • Rust stable 1.85 or newer and Cargo.
  • Bash or Zsh for shell integration.
  • An OpenAI-compatible endpoint, a local Ollama server, or the mock provider.
  • Linux is the only platform with a documented Bubblewrap sandbox backend. macOS has the normal executor; Windows support is not documented.

02

Install from source

Clone the repository, enter the checkout, and install the binary with Cargo.

terminal
git clone https://github.com/XenVen/ashplug.git
cd ashplug
cargo install --path .

Repository note: the application documentation currently uses XenVen/ashplug; the active Git remote is Ashplug/ashplug. Confirm the canonical clone URL before publishing an installation link.

verify
ashplug --version
ashplug config init

03

Initial configuration

config init writes a default TOML file. Inspect the effective configuration or its resolved path with:

configuration
ashplug config show
ashplug config path

The default provider is OpenAI-compatible. Its API key is read from the environment variable named by api_key_env; the default name is OPENAI_API_KEY.

openai-compatible provider
export OPENAI_API_KEY="…"

For a local Ollama server, set provider = "ollama", the local base URL, and a model in the TOML configuration. For offline development, use the mock provider documented below.

04

Run a first task

Use the mock provider for a deterministic, offline check. This is the same safe workflow used in the homepage demonstration.

offline check
ASHPLUG_MOCK_RESPONSE='{"summary":"Print a safe greeting","steps":[{"description":"Print a safe greeting","command":{"program":"echo","args":["ashplug demo"]}}]}' \
  ashplug --provider mock --no-history "show a safe greeting"

Use --plan when you want Ashplug to produce and evaluate a plan without executing it. Use --yes to approve every command the safety policy permits for one invocation.

05

Shell integration

Print and source the integration script. The documented setup is additive and does not overwrite existing shell configuration.

bash
ashplug init bash > /tmp/ashplug.bash
source /tmp/ashplug.bash

For Zsh, replace bash with zsh. To make the integration persistent, add the corresponding eval "$(ashplug init bash)" or Zsh line to the appropriate startup file.

06

Updating and troubleshooting

There is no release updater or uninstall workflow documented by the project. When building from a checkout, update the checkout using your normal Git workflow and rerun the documented Cargo install command. If installed with Cargo, Cargo’s standard uninstall command is:

remove Cargo installation
cargo uninstall ashplug
Provider errorCheck the configured provider, endpoint, model, and API-key environment variable. The mock provider avoids network access.
Command deniedReview the safety decision. Unknown, privileged, shell-interpreter, and invalid commands are denied by default.
Shell hook unavailableConfirm the binary is on PATH, source the generated script again, and check that Bash or Zsh is being used.