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.
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.
ashplug --version
ashplug config init
03
Initial configuration
config init writes a default TOML file. Inspect the effective configuration or its resolved path with:
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.
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.
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.
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:
cargo uninstall ashplug
PATH, source the generated script again, and check that Bash or Zsh is being used.