Configuration

This page summarises the environment variables that control Pygent. They can be exported in your shell or set via a .env file before running the CLI.

Variable	Description	Default
OPENAI_API_KEY	API key for OpenAI or any compatible service.	–
OPENAI_BASE_URL	Base URL for the API endpoint.	https://api.openai.com/v1
PYGENT_MODEL	Model name used for requests.	gpt-4.1-mini
PYGENT_IMAGE	Docker image used for sandboxed execution.	python:3.12-slim
PYGENT_USE_DOCKER	Set to 0 to run commands locally. Otherwise the runtime will try to use Docker if available.	auto
PYGENT_MAX_TASKS	Maximum number of delegated tasks that can run concurrently.	3
PYGENT_HISTORY_FILE	Path to a JSON file where the conversation history is saved.	–
PYGENT_WORKSPACE	Directory used to persist the workspace between sessions.	–
PYGENT_SNAPSHOT	Load environment and history from the given directory on startup.	–
PYGENT_STEP_TIMEOUT	Default time limit in seconds for each step when running delegated tasks.	–
PYGENT_TASK_TIMEOUT	Default overall time limit in seconds for delegated tasks.	–
PYGENT_PERSONA_NAME	Name of the main agent persona.	Pygent
PYGENT_PERSONA	Description of the main agent persona.	"a sandboxed coding assistant."
PYGENT_TASK_PERSONAS	List of personas for delegated agents separated by os.pathsep.	–
PYGENT_TASK_PERSONAS_JSON	JSON array of persona objects with name and description for delegated agents. Overrides PYGENT_TASK_PERSONAS if set.	–
PYGENT_INIT_FILES	List of files or directories copied into the workspace at startup, separated by os.pathsep.	–
PYGENT_BANNED_COMMANDS	Commands that cannot be executed by the bash tool, separated by os.pathsep.	–
PYGENT_BANNED_APPS	Applications that cannot appear in any command, separated by os.pathsep.	–
PYGENT_LOG_FILE	Path to the CLI log file.	workspace/cli.log
PYGENT_CONFIRM_BASH	Require confirmation before running bash commands (set to 0 to disable). When enabled, the command is displayed before prompting.	1

Instead of setting environment variables you can create a pygent.toml file in the current directory or in your home folder. Values defined there are loaded at startup if the corresponding variables are unset. Example:

persona_name = "FriendlyBot"
persona = "a friendly bot"

[[task_personas]]
name = "tester"
description = "runs tests"

[[task_personas]]
name = "developer"
description = "implements features"

initial_files = ["bootstrap.py"]

The keys map to the environment variables of the same name.

You can also specify a configuration file explicitly when launching the CLI:

pygent --config path/to/pygent.toml

Environment variables can also be provided on the command line using the -e option:

pygent -e OPENAI_API_KEY=sk-... -e PYGENT_MODEL=gpt-4

If you need additional setup logic execute a Python file with --pyconfig config.py. To resume from a saved snapshot pass --load DIR or set PYGENT_SNAPSHOT.

A practical example is included in examples/sample_config.toml together with the script config_file_example.py, which delegates a testing task:

python examples/config_file_example.py

See Getting Started for installation instructions and the API Reference for details about the available classes.