Environment Variables

Every environment variable the Desktop app and its engine read

Environment variables move the data directory, isolate secrets, and keep the engine’s output readable on non-English locales.

import os
from praisonaiagents import Agent

os.environ["PRAISONAI_DESKTOP_HOME"] = "/tmp/praison-profile"
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# The app reads the same variable to pick its data directory.
agent.start("Where does my data live?")

An empty value is treated as unset — PRAISONAI_DESKTOP_HOME="" no longer picks a different directory for the Rust shell than for the Python engine.

Quick Start

1. Override the data directory

   Set PRAISONAI_DESKTOP_HOME to a folder before launching to keep a separate profile.

2. Isolate secrets

   Set PRAISONAI_KEYCHAIN_SERVICE to keep test keys out of your real keychain entry.

3. Leave the encoding vars alone

   PYTHONUTF8 and PYTHONIOENCODING are set by the shell for the engine. You do not need to set them yourself.

How the engine gets its environment

The Desktop shell rebuilds the engine’s environment from the resolved venv before spawning it — it does not hand the engine your shell untouched.

Most variables pass through unchanged — provider keys (OPENAI_API_KEY, TAVILY_API_KEY), Desktop vars (PRAISONAI_DESKTOP_HOME, PRAISONAI_KEYCHAIN_SERVICE, PRAISONAI_AGENTS_SOURCE, PRAISONAI_TRAIN_CMD, PRAISONAI_MODEL), and platform vars (HOME, APPDATA, XDG_DATA_HOME).

Three variables are stripped by the shell before the engine spawns: PYTHONHOME, PYTHONPATH, PYTHONSTARTUP. Setting them in your shell does nothing for the engine — they would otherwise redirect the engine’s stdlib or site-packages away from the venv the shell just resolved.

Two variables are always set by the shell: VIRTUAL_ENV (points at the resolved venv root) and PATH (the venv’s bin/Scripts prepended to whatever PATH you exported).

Reference

_API_BASE | Engine | Set from the base_url setting for a slashed model id; the provider is named by the id's prefix. | |

_API_KEY | Engine | Set from the api_key setting for a slashed model id, following the same naming rule. | | TAVILY_API_KEY | User | Enables the built-in web_search` tool. |

Per-provider variables the engine writes

The app does not send your credential fields to OpenAI only. It writes them to the variables named for the selected provider — the base_url field is exported as `

_API_BASE, and api_key as

_API_KEY. The provider is taken from the model id's slashed prefix; a bare id is treated as OpenAI. The specific overrides encoded in PROVIDER_ENV_OVERRIDES in the engine's server.py`:

_API_BASE (uppercased) |

_API_KEY (uppercased) | | bare id (gpt-4o-mini, …) | OPENAI_API_BASE | OPENAI_API_KEY` |

The OpenAI pair is always kept in step, so switching back to a bare id after using a slashed one does not leave a stale endpoint behind.

Video-tab unlocks

Each video model in the Video tab becomes selectable only when one of its keys is present. A model with no configured key shows (key needed) and stays disabled.

Data Directory Precedence

The data directory follows one order per platform, and both the Rust shell and the Python engine derive it the same way.

Encoding on Non-English Locales

The shell exports PYTHONUTF8=1 and PYTHONIOENCODING=utf-8 to the engine so its output decodes cleanly on CP932 (Japanese) or CP1252 (Western European) systems.

Setting these yourself is redundant — the shell already does it.

Best Practices

Related