Skip to content

Secure Tool Access

Tool access is governed at two levels:

  1. Startup registration (TOOLS_ALLOWLIST and TOOLS_DENYLIST): Controls which tool classes are loaded into the registry when the server starts.
  2. Per-chat activation: Core tools are available in every chat (subject to user access tiers), while optional tool groups stay disabled until enabled for a chat via the composer menu, the pre-turn activation card, or request_tool_activation.

TOOLS_DENYLIST always wins over TOOLS_ALLOWLIST. Tools also run their own is_available() check so integrations with missing credentials or sidecars stay hidden cleanly.

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

Startup allowlist and denylist

The default TOOLS_ALLOWLIST includes all core tools and packaged optional groups:

TOOLS_ALLOWLIST="web_search,fetch_web_page,weather_fetch,code_interpreter,codemode,remember_fact,forget_fact,recall_memory,past_chats,view,create_file,generate_image,read_skill,numi_docs,grocery_search_stores,grocery_profile,grocery_get_offers,chefkoch_search,chefkoch_recipe,kleinanzeigen_search,kleinanzeigen_listing,academic_search,wiki_lookup,ebay_search,ebay_listing,mydealz_search,mydealz_deal"
TOOLS_DENYLIST=""

To restrict an instance to a minimal set of tools, set an explicit TOOLS_ALLOWLIST (an empty string disables all allowlist-gated tools):

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

Or keep the default allowlist and block specific tools with TOOLS_DENYLIST:

TOOLS_DENYLIST="generate_image,code_interpreter,codemode"

Restart the server after changing either variable.

Optional tool groups

Optional tools are organized into eight per-chat groups:

Group UI Label Tools
Scientific Research Scientific Research academic_search, wiki_lookup
Grocery Grocery grocery_search_stores, grocery_profile, grocery_get_offers
Recipes Chefkoch chefkoch_search, chefkoch_recipe
Shopping Kleinanzeigen kleinanzeigen_search, kleinanzeigen_listing
eBay eBay ebay_search, ebay_listing
MyDealz MyDealz mydealz_search, mydealz_deal
Price Search Geizhals geizhals_search, geizhals_product
Weather Weather weather_fetch

When the pre-turn tool router offers an optional group card and the user clicks No, Numi records that group in the chat's declined list (declined_tool_groups_json) and stops offering it in that chat. Enabling the group manually in the composer's tools menu clears the decline.

Skills

Access to read_skill (and mounting /mnt/skills/<name> helpers inside code_interpreter) requires read_skill in TOOLS_ALLOWLIST, SKILLS_ENABLED=true, the Skills capability on the user's access tier, and the skill switched on in Admin. See Manage Skills.

Code interpreter sandbox

code_interpreter executes eligible dependency-free scripts with Monty and runs package-backed scripts inside a fresh Deno + Pyodide WebAssembly sandbox. Networking is disabled by default (TOOLS_CODE_INTERPRETER_ALLOW_NETWORKING=false), and only allowlisted standard-library modules and third-party packages can be imported. Uploaded files and reusable generated artifacts from the active chat are copied into the sandbox within size limits. See Tools reference for details.

Default sandbox settings:

TOOLS_CODE_INTERPRETER_DEPS_ALLOWLIST="numpy,pandas,matplotlib,scipy,seaborn,sympy,scikit-learn,openpyxl,xlsxwriter,python-docx,python-pptx,reportlab,pypdf,pdfminer.six,mpmath,pint,statsmodels,networkx,tzdata,pillow"
TOOLS_CODE_INTERPRETER_IMPORT_ALLOWLIST="math,statistics,random,itertools,functools,collections,datetime,re,json,typing,os,sys,pathlib,io,csv,textwrap,decimal,fractions,zoneinfo,heapq,bisect,operator,string,struct,hashlib,base64,copy,pprint,enum,dataclasses,abc,contextlib,warnings,html,xml,wave,zipfile,gzip,zlib,binascii,calendar,colorsys,difflib,uuid,time,unicodedata,array,numbers,codecs"
TOOLS_CODE_INTERPRETER_IMPORT_DENYLIST="requests,httpx,urllib,urllib3,socket,ssl,ftplib,xmlrpc,pyodide,micropip,subprocess,shutil,signal,ctypes,multiprocessing,threading,webbrowser,smtplib,telnetlib"
TOOLS_CODE_INTERPRETER_TIMEOUT=90
TOOLS_CODE_INTERPRETER_ALLOW_NETWORKING=false
TOOLS_CODE_INTERPRETER_MAX_MEMORY_MB=1024
TOOLS_CODE_INTERPRETER_MAX_CONCURRENT=2
TOOLS_CODE_INTERPRETER_UNSANDBOXED=false

[!CAUTION] Keep TOOLS_CODE_INTERPRETER_UNSANDBOXED=false. Setting it to true disables sandboxing completely and runs model-generated Python with the server user's full filesystem, environment, process, and network access.

External credential requirements

Several tools also require API keys or helper binaries before they register as available:

  • web_search: Requires at least one of KEENABLE_API_KEY, OCTEN_API_KEY, PARALLEL_API_KEY, EXA_API_KEY, YOU_API_KEY, or DEEPSEEK_API_KEY.
  • fetch_web_page: Uses the configured WEB_FETCH_PROVIDERS (defaulting to WEB_SEARCH_PROVIDERS), or direct HTTP fetching when DIRECT_WEB_FETCH_ENABLED=true.
  • generate_image: Requires OPENROUTER_API_KEY.
  • ebay_search / ebay_listing: Require EBAY_CLIENT_ID and EBAY_CLIENT_SECRET.
  • kleinanzeigen_*: Require KLEINANZEIGEN_APP_BASIC when invoked.
  • geizhals_*: Require the Geizhals sidecar service and explicit inclusion in TOOLS_ALLOWLIST.
  • Deno: Required for the Pyodide execution path in code_interpreter (set DENO_PATH if deno is not on PATH).

Verify registered tools

Query /api/v1/tools with an authenticated session to inspect the tools registered on your instance:

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