Extra Settings Reference¶

This page is a single, consolidated reference for the extra settings (user/group variables) that PrimeThink features read at runtime — primarily the secrets and configuration values that capabilities and tool plugins resolve through ${SETTING_NAME} placeholders.

Each setting is also documented in its own topic page, in context. This page collects them all in one place so you can see, at a glance, every setting the platform's documented features expect and where each one is used.

What Counts as an "Extra Setting"¶

PrimeThink has three distinct kinds of configuration. This page covers the first:

Extra settings are the values you store under App Settings → Variables Management. Two consumers read them:

• Capabilities (MCP, API, Sandbox, Computer Use) — via ${SETTING_NAME} placeholders in their options.
• Tool plugins — programmatically, via the injected context.get_user_setting_value(name, user_id, group_id). See Tool Plugins → Plugin Context.

How Placeholder Resolution Works¶

Any string value in a capability's options can contain ${SETTING_NAME} placeholders. They are resolved when the agent's tools are built:

1. The system scans the options for ${...} tokens.
2. For each token it resolves the setting against the current user's settings, then the group's. (Capability options are built without a chat context, so the chat and workspace levels described in the settings hierarchy do not apply here.)
3. The returned value replaces the placeholder.
4. If a setting can't be resolved (missing or empty), an UnresolvedPlaceholderError is raised and that capability/tool is skipped with a logged error — the rest of the agent still loads.

Rules:

• Setting names must be word characters only — letters, digits, and underscore. ${HA_REMOTE_TOKEN} is valid; ${ha-token} is not.
• Names are case-sensitive: ${MY_KEY} looks for a setting named exactly MY_KEY.
• Resolution scope by capability type:
  • MCP — server_label, server_url, require_approval, headers, and any extra string/dict values.
  • API — url and headers.
  • Sandbox — env values passed into the sandbox.
  • Computer Use — prompt and actions text.

Configuring a Setting¶

Variables have their own Variables page in the administration area, listing every variable by name and value with a New variable button above it. Pick the level you want — your own or the group's — and add a name and a value:

Setting name:  WEATHER_API_KEY
Setting value: sk-abc123...

Each variable also carries two switches:

• Private value — masks the value everywhere, in the interface and in the API. Turn it on for anything secret; a masked value can still be read by the agent that needs it, but nobody can read it back out. If you save a variable whose name looks like a secret — it contains secret, password, key or token — with this switch off, PrimeThink asks first and offers to turn it on for you. That check is a courtesy, not a rule: name a credential something else and nothing will warn you. A private variable can still be edited: its edit dialog opens with an empty value box labelled New value, and saving needs a new value to be typed in, because the stored one is never shown again.
• Inject into sandbox — makes the value available as an environment variable when the agent runs commands in a sandbox. Off by default. On a shared level PrimeThink warns before enabling it, because everyone who can run the agent there can then read the value. Setting this needs the edit permission for that level's variables, so a reader sees the switch explaining what it would require rather than a switch that silently does nothing.

The value is then available as ${WEATHER_API_KEY} in any capability's options for that user/group. Settings can also be managed via the admin API.

Where a Value Comes From: the Settings Hierarchy¶

A setting name can be stored at four levels. When a value is resolved, the most specific level that holds the name wins, and the rest are ignored:

chat  >  workspace  >  user  >  group

If none of the four holds the name, resolution falls back to the platform's own configuration, and finally to an empty value. A level is skipped entirely when there is no context for it — a background job with no chat has no chat or workspace level to consult, and resolves exactly as it always did.

A setting's flags (whether its value is private, whether it may be injected into a sandbox) always come from the same row that supplied the winning value, never from a less specific level.

Where each level is edited¶

All four levels use the same editor, so a variable is described the same way wherever it lives — only the reach differs.

The tab appears only where you may read that level's variables, so a level your role does not grant you shows no Variables tab at all rather than an empty one. Two more rules follow from the table further down: a workspace you can read but not write shows its variables without the means to change them, and a View Only workspace shows no tab to anyone but its owner. A direct message has no chat variables — the tab is not offered there.

Because the levels override one another, the same name at a narrower level silently wins. When a value is not the one you expect, check the narrower levels before changing the one you set: a leftover chat variable is invisible from the group's Variables page.

Where the chat and workspace levels take effect¶

The two new levels are consulted wherever a value is resolved with a chat in hand:

• ${SETTING} expansion in the text of a user's message
• ${SETTING} expansion in an agent's system prompt
• Retrieval tuning — the number of results and the similarity threshold used for document search
• The agent job timeout
• Sandbox provider configuration and the environment variables injected into a sandbox

Capability option placeholders are the exception. The ${SETTING_NAME} tokens in a capability's options are resolved when the agent's tools are built, which happens without a chat context, so they continue to resolve over the user and group levels only. Do not expect a chat- or workspace-level variable to override a credential referenced from a capability's options.

Managing the new levels over the API¶

Workspace and chat variables have the same endpoints as group variables — list, read by name, create, update, and delete — under the workspace and the chat respectively, split the same way into managed and not managed settings.

Access is gated twice. The caller needs the matching Workspace Variables or Chat Variables permission, and must pass the ordinary access check for the container:

For chat variables, reading requires membership of the chat, and writing follows the same rule as renaming a chat or editing its goal. A chat or workspace you are not in is reported as not found rather than forbidden, so its existence is not disclosed.

Reading a setting by name at any level returns only stored values. It never falls through to the platform's own configuration or environment, so a caller cannot use it to read server secrets by guessing names.

Settings Catalog¶

The settings below are referenced throughout the documentation. Each links to the page where it is used in full context.

API Capabilities¶

Web Search¶

Web Page Fetching¶

Used by the Read Content of URL tool when a site blocks a direct fetch or serves a page with no readable content.

MCP Capabilities¶

Sandbox Capabilities¶

Computer Use Capabilities¶

Tool Plugins¶

Plugins read settings programmatically rather than through ${...} placeholders, using context.get_user_setting_value(...) (often wrapped in a settings-provider class). The example management plugin reads:

Security Notes¶

• Never hard-code secrets in capability options, prompts, scripts, or plugin code. Always store them as settings and reference them with ${...} (or read them via get_user_setting_value).
• Scope tokens to the minimum access your agent needs — a compromised token grants whatever access it carries.
• Prefer Group Variables for shared service credentials so they're managed in one place; use User Variables for per-person tokens.
• Use a Workspace Variable when a value belongs to a project rather than a person — every member then resolves the same value, and it survives members joining and leaving. Remember it is readable by the workspace's members, so it is the wrong place for a personal credential.
• A Chat Variable is narrower still, and is the right level for a one-off override that must not leak into the rest of your work. It disappears with the chat.
• Settings values are write-focused in the UI — treat them like passwords.

Related Topics¶

• App Settings — where User and Group Variables are configured
• UI Settings — the separate interface feature-toggle system
• Capabilities — overview of agent capabilities
• API Capabilities · MCP Capabilities · Sandbox Capabilities · Computer Use Capabilities
• Tool Plugins — reading settings from plugin code