# Environment Variables Used by Ponytail to Detect the Host Platform

> Discover how Ponytail detects the host platform using os.name and specific environment variables like APPDATA for configuration path resolution.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: api-reference
- Published: 2026-08-30

---

**Ponytail does not rely on environment variables to detect the host platform; instead, it uses Python's built-in `os.name` property to identify Windows versus POSIX systems, then applies platform-specific environment variables such as `APPDATA` or `XDG_CONFIG_HOME` solely for configuration path resolution after the OS has been determined.**

Ponytail is an open-source project by DietrichGebert designed to manage cross-platform configuration directories and runtime modes. While many applications query environment variables to determine whether they are running on Windows, macOS, or Linux, Ponytail takes a different architectural approach by leveraging the standard library for OS detection before consulting environment variables for path configuration.


## How Ponytail Detects the Host Platform Without Environment Variables

According to the source code in [`ponytail/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/__init__.py), Ponytail determines the operating system through Python’s `os.name` rather than environment variables. This property returns `"nt"` for Windows and `"posix"` for Unix-like systems.

In lines 45-49 of [`ponytail/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/__init__.py), the codebase checks `os.name` to decide which default configuration directory to use. This logic executes before any environment variable is read, ensuring the platform is identified via the standard library’s reliable mechanism rather than external configuration.

```python
import os
from pathlib import Path

# Platform detection as implemented in Ponytail

if os.name == "nt":
    # Windows-specific logic

    config_dir = Path(os.getenv("APPDATA", Path.home() / "AppData" / "Roaming")) / "ponytail"
else:
    # POSIX-compatible logic (Linux/macOS)

    config_dir = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config")) / "ponytail"

```


## Platform-Specific Environment Variables for Configuration Paths

Once `os.name` identifies the platform, Ponytail uses environment variables only to override default configuration directories. These variables do not influence the detection logic itself, but rather the final path construction.

### XDG_CONFIG_HOME for Linux and macOS

On non-Windows systems, Ponytail respects the **XDG Base Directory Specification**. If `XDG_CONFIG_HOME` is set, Ponytail uses it as the parent directory for its configuration folder. If unset, it defaults to `~/.config/ponytail`.

```bash

# Override the default config location on Linux or macOS

export XDG_CONFIG_HOME="/custom/config/path"

# Result: Ponytail will use /custom/config/path/ponytail

```

### APPDATA for Windows

On Windows (when `os.name == "nt"`), Ponytail looks for the `APPDATA` environment variable to locate the roaming AppData directory. If this variable is unavailable, it falls back to constructing the path from the user's home directory.

```cmd

# Override the AppData location on Windows

set APPDATA=C:\Users\Me\CustomAppData

# Result: Ponytail will use C:\Users\Me\CustomAppData\ponytail

```


## Runtime and Benchmark Environment Variables

Beyond platform path configuration, Ponytail recognizes several other environment variables that control behavior across all operating systems.

### PONYTAIL_DEFAULT_MODE

Line 53 of [`ponytail/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/__init__.py) reads the `PONYTAIL_DEFAULT_MODE` variable to set the initial runtime mode. Valid options include `lite`, `full`, `ultra`, `off`, and `review`. This setting is platform-agnostic and affects how Ponytail behaves regardless of the host OS.

```bash

# Set the default mode before running Ponytail

export PONYTAIL_DEFAULT_MODE=ultra

```

### PONYTAIL_PLUGIN_DIR and PONYTAIL_TMPL for Benchmarks

The benchmark scripts in `benchmarks/agentic/` use additional environment variables for temporary overrides. Lines 28-30 of [`benchmarks/agentic/tasks.py`](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/agentic/tasks.py) reference `PONYTAIL_TMPL` to specify a template repository for benchmark tasks. Similarly, lines 210-215 of [`benchmarks/agentic/run.py`](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/agentic/run.py) use `PONYTAIL_PLUGIN_DIR` to override the plugin directory location during test runs.

```bash

# Used for benchmark execution to point to local resources

export PONYTAIL_TMPL=my-local-template
export PONYTAIL_PLUGIN_DIR=/tmp/ponytail-plugins

```

These benchmark-specific variables are primarily used in development and testing workflows rather than standard production deployments.


## Source Code Implementation Details

The actual implementation of platform detection and environment variable handling is concentrated in specific source files:

- **[`ponytail/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/__init__.py)** (lines 45-49): Contains the `os.name` check and the conditional logic for selecting between `APPDATA` and `XDG_CONFIG_HOME`.
- **[`ponytail/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/__init__.py)** (line 53): Reads `PONYTAIL_DEFAULT_MODE` from the environment.
- **[`benchmarks/agentic/tasks.py`](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/agentic/tasks.py)** (lines 28-30): Demonstrates usage of `PONYTAIL_TMPL` for benchmark task templates.
- **[`benchmarks/agentic/run.py`](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/agentic/run.py)** (lines 210-215): Shows temporary override of `PONYTAIL_PLUGIN_DIR` during benchmark execution.


## Summary

- **Platform detection** in Ponytail relies on `os.name` (returning `"nt"` for Windows or `"posix"` for Linux/macOS), not environment variables.
- **`XDG_CONFIG_HOME`** overrides configuration directories on Linux and macOS systems.
- **`APPDATA`** provides the roaming profile directory path on Windows systems only.
- **`PONYTAIL_DEFAULT_MODE`** sets the runtime mode across all platforms.
- **`PONYTAIL_PLUGIN_DIR`** and **`PONYTAIL_TMPL`** are reserved for benchmark and testing scenarios.


## Frequently Asked Questions

### Does Ponytail use environment variables to detect Windows or Linux?

No. According to the source code in [`ponytail/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/__init__.py), Ponytail uses Python's standard `os.name` property to detect the host platform. Environment variables like `APPDATA` or `XDG_CONFIG_HOME` are only consulted after the platform has been identified to determine where to store configuration files.

### What is the difference between XDG_CONFIG_HOME and APPDATA in Ponytail?

`XDG_CONFIG_HOME` is used on POSIX-compliant systems (Linux and macOS) to override the default `~/.config` directory, following the XDG Base Directory Specification. `APPDATA` is used exclusively on Windows (when `os.name == "nt"`) to locate the roaming application data folder. Both serve the same purpose of customizing the configuration path, but each applies to a different operating system.

### How do I change Ponytail's default runtime mode?

Set the `PONYTAIL_DEFAULT_MODE` environment variable to one of the supported values: `lite`, `full`, `ultra`, `off`, or `review`. This variable is read at initialization (line 53 of [`ponytail/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/__init__.py)) and applies across all platforms, affecting how Ponytail processes and executes tasks.

### What are PONYTAIL_PLUGIN_DIR and PONYTAIL_TMPL used for?

These variables are specific to Ponytail's benchmark suite. `PONYTAIL_TMPL`, referenced in [`benchmarks/agentic/tasks.py`](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/agentic/tasks.py), points to a template repository for benchmark tasks. `PONYTAIL_PLUGIN_DIR`, used in [`benchmarks/agentic/run.py`](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/agentic/run.py), allows tests to temporarily override the plugin search path. Neither variable affects standard platform detection or production runtime behavior.