Skip to content

Secure Tool Access

Tool access is controlled at two levels:

  1. Registry startup: TOOLS_ALLOWLIST and TOOLS_DENYLIST decide which tools are loaded.
  2. Chat activation: custom tools are exposed to a chat only after the user enables their group. When an available group is still disabled, request_tool_activation lets the agent ask for that activation.

The denylist wins. Tools must be allowlisted and available in the current environment; request_tool_activation is exempt from the allowlist but still obeys the denylist. Tools with missing credentials or sidecars may be omitted by their availability check.

An optional tool passes operator policy and per-chat activation before it can be used.

Startup policy

The built-in default allowlist contains the core tools plus the configured grocery, recipe, shopping, scientific, eBay, and MyDealz tools:

TOOLS_ALLOWLIST="web_search,fetch_web_page,weather_fetch,code_interpreter,remember_fact,forget_fact,view,create_file,generate_image,grocery_search_stores,grocery_profile,grocery_get_offers,chefkoch_search,chefkoch_recipe,chefkoch_recipe_of_the_day,kleinanzeigen_search,kleinanzeigen_listing,kleinanzeigen_categories,academic_search,wiki_lookup,ebay_search,ebay_listing,mydealz_search,mydealz_deal,mydealz_discover"
TOOLS_DENYLIST=""

For a smaller deployment, replace the allowlist rather than assuming an empty value means "all tools":

TOOLS_ALLOWLIST="web_search,fetch_web_page,view,remember_fact,forget_fact"
TOOLS_DENYLIST=""

To remove a tool without changing a shared allowlist:

TOOLS_DENYLIST="generate_image,code_interpreter"

Restart the server after changing either variable.

Tool groups

Custom tools are grouped for per-chat activation:

Group Tools
Scientific Research academic_search, wiki_lookup
Grocery grocery_search_stores, grocery_profile, grocery_get_offers
Recipes chefkoch_search, chefkoch_recipe, chefkoch_recipe_of_the_day
Shopping kleinanzeigen_search, kleinanzeigen_listing, kleinanzeigen_categories
eBay ebay_search, ebay_listing
MyDealz mydealz_search, mydealz_deal, mydealz_discover
Price Search geizhals_search, geizhals_variant, geizhals_product

A group's tool names still need to be present in TOOLS_ALLOWLIST and pass their availability checks. ChatToolsUpdate can persist the enabled tool names for a chat through POST /api/v1/chats/{chat_id}/tools.

Code interpreter boundary

code_interpreter uses Monty for eligible dependency-free scripts and falls back to a fresh Deno/Pyodide sandbox for other supported code. Imports and dependencies are allowlisted, and networking is disabled by default. Current-chat uploads and reusable generated files are provisioned into the sandbox within size limits. See Tools reference for file paths and execution limits.

Relevant settings:

TOOLS_CODE_INTERPRETER_DEPS_ALLOWLIST="numpy,pandas,matplotlib,scipy,seaborn,sympy,scikit-learn,openpyxl,xlsxwriter,python-docx,reportlab,pypdf"
TOOLS_CODE_INTERPRETER_IMPORT_ALLOWLIST="math,statistics,random,itertools,functools,collections,datetime,re,json,typing,os,sys,pathlib,io,csv"
TOOLS_CODE_INTERPRETER_IMPORT_DENYLIST="requests,httpx,urllib,urllib3,socket,ssl,ftplib,xmlrpc,pyodide,micropip"
TOOLS_CODE_INTERPRETER_TIMEOUT=90
TOOLS_CODE_INTERPRETER_ALLOW_NETWORKING=false
TOOLS_CODE_INTERPRETER_UNSANDBOXED=false

TOOLS_CODE_INTERPRETER_UNSANDBOXED=true executes model-supplied Python with the server user's filesystem, environment, process, and network privileges. Do not enable it on a shared or internet-facing instance.

The timeout is not a memory or CPU quota. Use container or operating-system limits for hostile multi-user workloads.

Optional integrations

Some tools require credentials or a local service in addition to the allowlist:

  • web_search requires PARALLEL_API_KEY. General web extraction also uses Parallel; DIRECT_WEB_FETCH_ENABLED enables direct text fetching without a query. See the tools reference for native handlers and fallback behavior.
  • generate_image uses OPENROUTER_API_KEY.
  • eBay requires EBAY_CLIENT_ID and EBAY_CLIENT_SECRET.
  • Kleinanzeigen requires valid KLEINANZEIGEN_APP_BASIC access.
  • Geizhals requires its sidecar service.
  • Deno is required for the Pyodide path, including third-party packages; set DENO_PATH when it is not on PATH.

See Configuration and Tools Reference for the complete parameter and environment reference.

Verify the effective policy

After restart, query the authenticated metadata endpoint:

curl http://localhost:4567/api/v1/tools \
  -H "Authorization: Bearer YOUR_TOKEN"

The response is the effective registry. A missing tool may be denied or fail an availability check. A tool listed here can still need per-chat activation before the agent can call it; registry membership and chat activation are separate gates.