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.

Availability and strict mode

Ash exposes its dedicated run_python3 tool only when the selected interpreter resolves to a runnable executable. The selection order is ASH_PYTHON, the complete managed virtualenv, then system python3. A missing or invalid selected interpreter means Python authoring and execution are unavailable for that request.

ASH_STRICT=1 disables Python execution even when the interpreter is valid. In strict mode ash neither publishes run_python3 nor runs ash-managed bundled .py tools. This is defense in depth, not a sandbox; see Conditional-Python-Execution and Security-Model-and-Environment-Variables.

Tool catalog and eligibility

$TOOLS_DIR_LIST is a reserved internal Ash substitution, never an environment variable. Ash renders it in .ash_system from scripts that are both allowed by the effective policy and regular files in ~/.ash/tools/ with read and execute permission bits. The $TOOLS_DIR_LIST line in .ash_tools is the matching internal directive; replace it with literal names to restrict which managed scripts may run.

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.