Python Environment

Purpose

Ash ships bundled Python tools (under ash_bootstrap/tools/, installed to ~/.ash/tools/) that give the AI capabilities like fetching stock data or headlines. To run these tools without touching your system Python or any other project's environment, ash install provisions a dedicated virtualenv at ~/.ash/venv.

How it works

1. During install, ash runs python3 -m venv ~/.ash/venv and installs the bundled tools' dependencies (from requirements.txt) into it with pip.
2. When the AI invokes a bundled .py tool, ash runs it with the interpreter at ~/.ash/venv/bin/python3 (or Scripts\python.exe on Windows) instead of your system python3.
3. If the venv is missing or incomplete (for example, pip failed to install because ensurepip didn't run), ash detects this, removes the partial environment, and recreates it on the next ash install.
4. If python3 or the venv module isn't available, or dependency installation fails, ash prints a message explaining what to install and continues — a missing Python environment never blocks the rest of ash install from completing. Affected tools report a clear "missing library" error until you resolve it and rerun ash install.

Benefits

• No system Python pollution — bundled tool dependencies are installed only inside ~/.ash/venv, never into your system or user site-packages.
• No conflicts with your own projects — if you already use a different version of a package (for example requests or yfinance) elsewhere, ash's copy won't clash with or override it.
• No sudo required — as a per-user virtualenv, installing its dependencies never needs elevated privileges.
• Self-healing — a partially created environment (for example, from a failed ensurepip) is automatically detected and rebuilt rather than left broken.
• Isolation reduces blast radius — a compromised or misbehaving third-party package used by a bundled tool stays confined to ~/.ash/venv and can't shadow or override packages used by other Python programs on your machine through a shared global site-packages.
• Zero configuration — this all happens automatically during ash install; you don't need to think about Python packaging at all.

This isolation is about hygiene and avoiding cross-contamination with your system/global Python, not sandboxing — the venv doesn't restrict filesystem or network access, so it doesn't protect against a genuinely malicious package acting with your normal user permissions.

Overriding the interpreter

Set the ASH_PYTHON environment variable to point ash at a different interpreter (for example, if you maintain your own environment with additional packages):

export ASH_PYTHON=/path/to/your/python3

When set, ash uses this interpreter for bundled tools instead of ~/.ash/venv.

Troubleshooting

• "missing library" errors from a bundled tool: rerun ash install after making sure python3 and its venv module are installed, and that you have network access to install packages from PyPI.
• Environment seems stuck/broken: delete ~/.ash/venv and rerun ash install to force a clean rebuild.