Configuration

Everything in std-tools is configured through environment variables, each with a default. This page lists every variable the code reads. The tables are generated from one table in the code (ENV_VARS in _config.py) by scripts/gen_reference.py, which also writes the README's configuration section and .env.example, so the three always agree.

How configuration is loaded

• std-tools reads the process environment only. It never loads a .env file itself. To use one, load it in whatever starts std-tools: docker run --env-file .env, env_file: in Docker Compose, or load_dotenv() in your application before std-tools is first used. The repository's .env.example lists every variable, commented out, ready to copy.
• A stdio server sees only the environment you pass it. The MCP SDK starts a stdio server with a short allow-list of variables (PATH, HOME or USERPROFILE, TEMP and a few others), so pass the variables below in the client's env. See Using with the Toolkit.
• Values are read once per process, then cached, unless the table says otherwise. Restart the server after changing one.
• Invalid numbers are errors, not silent defaults. A numeric variable that is not a positive integer raises an error naming the variable. The composed launcher (python -m doc_processing_std_tools) checks every variable at start-up and refuses to start; other entry points fail on the first tool call that reads it.
• Relative directories (DPTTOOLS_MEMORY_DIR, DPTTOOLS_SKILLS_DIR) are resolved against the process's working directory when configuration is first read.

The variables, by area:

General

Variable	Default	Accepted values	When it is read	Description
DPTTOOLS_MAX_FILE_SIZE_MB	50	Positive integer (MB)	First use; cached	Largest file the read tools will open.
DPTTOOLS_OUTPUT_TRUNCATION_LIMIT	50000	Positive integer (characters)	First use; cached	Longest text a tool returns to the model; longer output is truncated with a notice.
DPTTOOLS_MEMORY_DIR	./agent_memory	Directory path	First use; cached	Where the memory tools keep their files. A relative path is resolved against the working directory.
DPTTOOLS_SKILLS_DIR	./.agent_skills	Directory path	First use; cached	Where the skills tools look for skills (one subdirectory with a SKILL.md per skill).

Code execution

Variable	Default	Accepted values	When it is read	Description
DPTTOOLS_SANDBOX_TIMEOUT	30	Positive integer (seconds)	First use; cached	Default and maximum timeout for execute_command, and the timeout for execute_skill_script.

Documents and OCR

Variable	Default	Accepted values	When it is read	Description
DPTTOOLS_OCR_TIMEOUT	180	Integer seconds; clamped to 30–600	First use; cached	Wall-clock deadline for one OCR job, upload and polling included. A value outside 30–600 is clamped; one that is not a positive integer is an error.
LLMWHISPERER_API_KEY	(none)	LLMWhisperer API key	Every OCR call	Required by ocr_pdf and ocr_image (install the [ocr] extra).
DPTTOOLS_CONVERT_TIMEOUT_S	120	Positive integer (seconds)	First use; cached	Timeout for one LibreOffice conversion: convert_document, and the Office-to-PDF step of render_document_page, render_document_thumbnail and read_document_pages_as_images.
DPTTOOLS_SOFFICE_BIN	(none)	Path to soffice, or a command name on PATH	First use; cached	LibreOffice executable to run. When unset, std-tools looks for libreoffice, then soffice, on PATH. A value that does not resolve to an executable is an error naming the variable.

Web

Variable	Default	Accepted values	When it is read	Description
DPTTOOLS_WEB_SEARCH_PROVIDER	(none)	tavily, serper or brave	First use; cached	Search provider for web_search. Without it, web_search returns a configuration error.
DPTTOOLS_WEB_SEARCH_API_KEY	(none)	The provider's API key	First use; cached	API key for the search provider. Tavily receives it as a Bearer token.
DPTTOOLS_WEB_FETCH_TIMEOUT	30	Positive integer (seconds)	First use; cached	Timeout for fetch_webpage, independent of DPTTOOLS_SANDBOX_TIMEOUT. The connect phase is capped at 10 seconds.
DPTTOOLS_WEB_FETCH_MAX_BYTES	2000000	Positive integer (bytes)	First use; cached	Most bytes fetch_webpage downloads from one response. A longer page is cut at this point and the result says byte_cap_reached.
DPTTOOLS_WEB_FETCH_MAX_REDIRECTS	5	Positive integer	First use; cached	Most redirects fetch_webpage follows. Every hop is checked against the private-address block.
DPTTOOLS_WEB_FETCH_ALLOW_HOSTS	(none)	Comma-separated exact hostnames	First use; cached	Hosts the fetch tools may reach even though they resolve to a private or loopback address (for example an internal wiki). Exact names only, no wildcards. Empty by default: every private address is refused.
DPTTOOLS_FETCH_IMAGE_MAX_BYTES	10000000	Positive integer (bytes)	First use; cached	Largest image fetch_image downloads. A larger image is refused (its declared size is checked before download); one within the limit is then scaled to the image limits below.

Images

Variable	Default	Accepted values	When it is read	Description
DPTTOOLS_IMAGE_MAX_EDGE_PX	1568	Positive integer (pixels)	First use; cached	Long-edge limit for every image returned to the model; larger images are scaled down. Files written to an output_path keep full resolution.
DPTTOOLS_IMAGE_MAX_MB	3	Positive integer (MB)	First use; cached	Encoded-size limit for every image returned to the model.

Browser

Variable	Default	Accepted values	When it is read	Description
DPTTOOLS_ENABLE_BROWSER	false	true or false	Launcher start-up	Adds the browser server to the composed launcher (python -m doc_processing_std_tools). In-process users pass browser_server to Agent(tools=[...]) instead.
DPTTOOLS_BROWSER_MODE	launch	launch, persistent or cdp	First use; cached	launch: std-tools starts its own Chromium with a fresh profile per session. persistent: its own Chromium on a saved profile (one session at a time). cdp: attach to a browser someone else started (the user's own browser).
DPTTOOLS_BROWSER_HEADLESS	true	true or false	First use; cached	Run Chromium without a window. Set false to watch the agent (needs a display).
DPTTOOLS_BROWSER_PROFILE_DIR	(none)	Directory path	First use; cached	Saved browser profile for persistent mode (required there), so a person can sign in once.
DPTTOOLS_BROWSER_CDP_URL	(none)	A DevTools endpoint URL	First use; cached	Browser to attach to in cdp mode (required there), for example http://127.0.0.1:9222. Chrome 136 and later need a dedicated --user-data-dir for remote debugging.
DPTTOOLS_BROWSER_CDP_SHARE_TABS	false	true or false	First use; cached	In cdp mode, let the agent see and use tabs it did not open. By default it works only in its own tabs. Required to enable run_script in cdp mode, because a script can reach every tab.
DPTTOOLS_BROWSER_TOOLS	core	core or full	Server creation	core: 18 browser_* tools. full: all 27 default members of Anthropic's browser toolset (adds right/middle/double/triple click, drag, mouse down/up/move and hold_key). Both also register fetch_webpage_rendered.
DPTTOOLS_BROWSER_ENABLE	(none)	Comma-separated: javascript_exec, file_upload, read_console, read_network, run_script	Server creation	Opt-in tools, off by default because of what they can do. A run_script script can reach the whole browser, so while it is enabled only one browser session is open at a time, and cdp mode also needs DPTTOOLS_BROWSER_CDP_SHARE_TABS=true.
DPTTOOLS_BROWSER_MAX_SESSIONS	4	Positive integer	First use; cached	Most browser sessions (one per MCP session) open at once. Always 1 while run_script is enabled.
DPTTOOLS_BROWSER_IDLE_TIMEOUT_S	600	Positive integer (seconds)	First use; cached	A session unused for this long is closed, with its tabs.
DPTTOOLS_BROWSER_VIEWPORT	1440x900	WIDTHxHEIGHT	First use; cached	Page viewport size in pixels. Screenshots are this size unless the image limits scale them.
DPTTOOLS_BROWSER_AUTO_SCREENSHOT	false	true or false	First use; cached	Attach a screenshot to the result of every action that changes the page. Off by default: reading the page as text is cheaper.
DPTTOOLS_BROWSER_DOWNLOAD_DIR	(none)	Directory path	First use; cached	Where downloads are saved, one subdirectory per session. Default: a new temporary directory per session.
DPTTOOLS_BROWSER_UPLOAD_DIR	(none)	Directory path	First use; cached	The only directory browser_file_upload may read from (required to enable it). Must differ from the download directory.
DPTTOOLS_BROWSER_ALLOWED_DOMAINS	(none)	Comma-separated domains	First use; cached	If set, the browser may only load these domains and their subdomains. Empty: any public host. Private and reserved addresses stay blocked either way.
DPTTOOLS_BROWSER_BLOCKED_DOMAINS	(none)	Comma-separated domains	First use; cached	Domains (and their subdomains) the browser may never load. Wins over the allowed list.
DPTTOOLS_BROWSER_ALLOW_HOSTS	(none)	Comma-separated exact hostnames	First use; cached	Hosts the browser may reach even though they resolve to a private or loopback address. Exact names only.
DPTTOOLS_BROWSER_CONFIRM	off	off, deny or elicit	First use; cached	Confirmation gate for consequential actions (purchases, deletions, sending, passwords, uploads). off: the client app approves actions through its own hooks. deny: refuse them. elicit: ask a human through MCP elicitation; refuse if nobody can answer.
DPTTOOLS_BROWSER_SCRIPT_TIMEOUT_S	60	Positive integer (seconds)	First use; cached	Timeout for one browser_run_script call.

Computer

Variable	Default	Accepted values	When it is read	Description
DPTTOOLS_ENABLE_COMPUTER	false	true or false	Launcher start-up	Adds the desktop computer server to the composed launcher. In-process users pass computer_server to Agent(tools=[...]) instead.
DPTTOOLS_COMPUTER_BACKEND	virtual	virtual or host	First use; cached	virtual: the agent's own Xvfb display per session (Linux containers). host: the real screen, mouse and keyboard of the machine std-tools runs on, with a kill switch; only with the user's knowledge.
DPTTOOLS_COMPUTER_DISPLAY_SIZE	1440x900	WIDTHxHEIGHT	First use; cached	Size of each virtual display (virtual only).
DPTTOOLS_COMPUTER_MAX_SESSIONS	2	Positive integer	First use; cached	Most virtual desktops open at once (virtual only; host always allows one session).
DPTTOOLS_COMPUTER_VNC_PORT	off	Port number, or off	First use; cached	Serve each virtual display over VNC on 127.0.0.1 (first session on this port, the next on port + 1) so a person can watch or take over. Needs x11vnc (virtual only).
DPTTOOLS_COMPUTER_MONITOR	primary	primary or a monitor number (1, 2, ...)	First use; cached	Which monitor the host backend uses. primary is the one the system marks primary (on Linux, the XRandR primary output). Coordinates are relative to it.
DPTTOOLS_COMPUTER_KILL_HOTKEY	ctrl+alt+shift+k	A key chord	First use; cached	In host mode, pressing this (or moving the mouse into the top-left corner) stops the agent until the server restarts.
DPTTOOLS_COMPUTER_CONFIRM	off	off, deny or elicit	First use; cached	Confirmation gate. elicit: ask before the first action of each host session and before key chords that close, quit or delete (alt+f4, ctrl+w, ctrl+q, super+w, super+q, delete, shift+delete), also with extra keys such as ctrl+shift+w and as click modifiers. deny: refuse those chords. off: the client app approves actions through its own hooks.