Configuration layers#
| Layer | Controls | Persistence |
|---|---|---|
| Application settings | Providers, workers, phase bindings, global instructions, AI toggles, MCP, window behavior | %APPDATA%\Enactive\settings.json |
| Workspace preferences | Selected role, autonomy, staging, recent workspace information | %APPDATA%\Enactive\workspaces.json |
| Workspace approvals | Standing desktop tool approvals keyed by workspace identity | %APPDATA%\Enactive\permissions.json |
| Templates | Reusable goals, parameters, ceilings, checks, limits | Global or Workspace template files |
| Resolved run specification | One template resolved with concrete answers and permissions | Stored with a run |
| Environment | Storage backend, logging, console model/endpoint, initial desktop defaults | Process environment |
There is no independent Workspace Providers/Phases file in the current desktop implementation. Global instructions and phase bindings are application-wide. “Workspace versus Global” in the template editor selects a template's storage scope, not a separate full application-settings profile.
Saving and cancelling#
Most settings are edited on a copy and take effect through the outer Save action. Cancel discards those unsaved edits. Provider/worker/MCP sub-editors update that draft; finish by saving the main Settings window.
Template files are the exception: their editor saves immediately, and deletion is immediate after its confirmation. Outer Cancel cannot undo those file operations.
If saving fails, inspect the reported error before closing the editor. Secret-protection failures must not be treated as successful saves.
General, Account, and About#
General includes startup behavior and what happens when the main window closes. Close to tray is enabled by default. With no system tray available, closing exits because the window has nowhere to hide. Quitting with work in flight requires attention because background work lives in the same process.
Account is currently a placeholder. Enactive has no desktop account system of its own; provider credentials live under AI → Providers.
About shows application/build/runtime information and component versions, useful when diagnosing mixed or stale application files.
AI → Providers#
A provider is a named endpoint with a transport adapter, authentication, and a catalog of model IDs.
| Field | Guidance |
|---|---|
| ID | Stable unique key used in model references; changing it affects references |
| Display name | Human-readable provider label |
| Kind | OllamaNative, Anthropic, or OpenAiCompatible |
| Base URL | API base for the selected adapter |
| API key | Credential entered in the editor and protected when saved |
| Headers | Provider-specific HTTP headers; use only where needed |
| Models | Exact endpoint model names, discovered or entered manually |
| Max output tokens | Optional per-provider response cap where the adapter supports it |
Adapter behavior#
| Kind | Request interface | Practical configuration |
|---|---|---|
| OllamaNative | Native /api/chat |
Local URL such as http://localhost:11434; native context/thinking controls |
| Anthropic | Messages API | Base such as https://api.anthropic.com; API credentials and exact model ID |
| OpenAiCompatible | <BaseUrl>/chat/completions |
API prefix such as https://api.openai.com/v1, or a compatible local/remote service |
Model discovery populates a catalog. It does not install local models or prove compatibility with streaming, tool calls, or every request field Enactive sends. Validate a candidate with a small real run before using it across phases.
OpenAI-compatible does not mean support for the Responses API. The current adapter sends Chat Completions fields, including temperature when requested and max_tokens when configured. An endpoint/model that rejects those fields needs compatibility work; a model ID alone cannot solve it.
Output caps#
- OpenAI-compatible: request-level
MaxTokens, otherwise the provider setting, is sent asmax_tokens. - Anthropic: uses a default output budget of 32,000 when no override applies, and can retry after learning a lower supported cap from an API error. It also retries a rejected temperature parameter without that field.
- Native Ollama: the current adapter does not map the provider Max output tokens field to
num_predict.
Do not confuse response output caps with NumCtx (context capacity) or template MaxTokens (cumulative run budget).
Secret storage#
Provider API keys are saved as DPAPI-protected values; the plaintext API key property is excluded from serialization. General provider Headers are ordinary settings data, unlike the encrypted MCP header/environment dictionaries. Do not place secrets in general custom headers expecting the API-key protection to cover them.
Windows DPAPI protection is tied to the user context. Copying settings to another machine/account may require re-entering credentials. Keep keys out of templates and Global instructions.
AI → Team#
Workers combine instructions, tools, permission level, a preferred model, and an optional fallback. Models are referenced as:
providerId/model-nameFor example, ollama/qwen3-coder:30b identifies a model under the configured provider with ID ollama. The provider ID is an Enactive setting, not part of the upstream model name.
| Built-in worker | Default tools | Default level |
|---|---|---|
| Developer | File inspection/editing, directories/moves, shell, Git, Docker | Execute |
| Reviewer | Read, search, list | Observe |
| Ops | Read/search/list, shell, Git, Docker | Execute |
| Writer | Read/search/list, write/edit, directories/moves | Execute |
The worker's tool allowlist is authoritative: an empty list permits no tools; * permits all registered tools. MCP additionally supports mcp__*, a server prefix such as mcp__example__*, or an exact discovered tool name.
Worker instructions are augmented at runtime with shared honesty rules, optional read-back guidance, and Global instructions. Put role-specific behavior in the worker and project/task-specific requirements in a template or request.
Fallback addresses supported execution-provider failures. It does not automatically replace a weak model because a review failed and does not configure Plan/Review failover.
AI → Phases#
| Setting | When selected | When blank |
|---|---|---|
| Plan model | Uses that model for request classification/planning | Uses the worker's base model |
| Review model | Enables model review of execution/content | Skips model review |
| Execute light | Uses that model for trivial DAG steps | Uses the worker model for those steps |
| Execute heavy | Uses that model for complex DAG steps | Uses the worker model for those steps |
Normal execution is configured in Team → worker model, not in a separate normal-phase dropdown. Light/heavy routing does not alter role permissions. See Models and Phases for selection guidance.
ReviewRequired in a template is currently metadata only. The Review binding is the actual on/off switch in both quick-action and planned desktop execution.
AI → General#
| Setting | Default | Effect and recommended use |
|---|---|---|
Context length (NumCtx) |
Blank/null | Requests native Ollama execution context size. Increase only when necessary and supported by available memory |
| Global instructions | Empty | Added to every worker's instructions; use for stable cross-project conventions |
| Disable local reasoning | On | Native Ollama execution requests use think:false; useful when thinking consumes turns without useful output |
| Verify writes | On | Adds instructions to read written real data back; useful for unreliable writers, costs extra work |
| Review content | On | Reviews written text for writing-only steps when Review is bound |
| Revert rejected steps | On | Attempts to restore tracked writes after final rejection, preserving newer conflicting edits |
| Review retries | 1 | One extra attempt after rejection; allowed range 0–5 |
| Allow implicit tool calls | Off | Can execute tool calls inferred from assistant text; leave off for normal structured-tool models |
| Parallel steps | 1 | Number of independent plan steps that may overlap |
Verify writes is an instruction to the worker, not an unconditional host read-back after every write. Review content requires a bound Review model; enabling the toggle alone does not create an evaluator.
NumCtx and Disable local reasoning are passed through the execution loop. Separate Plan/Review requests do not expose equivalent per-phase context/thinking configuration in the current UI. These settings do not configure OpenAI reasoning effort or Anthropic extended/adaptive thinking.
Parallelism helps when branches are independent and provider capacity permits overlap. Multiple steps on one constrained local endpoint may queue or compete for memory. Keep 1 until you have a representative task that benefits.
AI → MCP#
Configure external tool servers here, then grant the intended worker MCP access under Team. Enabled servers connect for each new desktop run. An unavailable enabled server can prevent the run from starting.
MCP tools require Execute-level access and normally ask on every call. Their external effects are not covered by built-in staging/revert. See MCP operations for the full workflow.
Environment defaults and migration#
The desktop seeds its initial model/endpoint from ENACTIVE_MODEL and ENACTIVE_OLLAMA_URL when a usable saved settings file is absent. Existing Providers/Workers/Bindings are authoritative after migration; editing environment variables is not a reliable way to override saved desktop bindings.
ENACTIVE_WORKSPACE supplies a desktop workspace startup value. Storage/logging variables apply to the components that read them; the console-specific interpretation is documented in Console.
Current settings schema version is 3. Migrations preserve older tool-access behavior explicitly and add edit_file to workers that already had write_file. Startup repair can retain a settings.before-repair-*.json copy when repairing problematic settings.
Old legacy fields such as MultiAgent, ReasonerModel, and the single BaseUrl/Model are migration inputs. Configure the current Providers/Workers/Bindings schema rather than trying to control a migrated installation through those fields.