POLICY REFERENCE

Policy reference

Every field accepted by Voidleap's managed-policy file (policy.json), grouped by enforcement tier. The generator writes these same paths.

Building one? Use the policy generator.

Enforced today

The 43 fields the current client acts on. Every other field in this reference parses and is stored, but changes no behaviour yet. Enforcement is per field, not per section — some of these live in sections listed below under Parsed.

Implementation status

Enforced
Wired and enforced in the current Voidleap build. These are the fields that actually do something today.
Parsed
Loaded by the schema and surfaced via GET /policy/status; enforcement is landing incrementally. You can ship these in a policy file today without breaking older clients.
Deferred
Parsed but enforcement is not on the immediate roadmap. Safe to include in a policy file; do not rely on the behaviour yet.

148 of 148 fields shown.

Enforced Enforced today

Guardrails guardrails Enforced

Locks for the per-machine security.json — outside-workspace policy, blocked/sensitive command lists, and path permissions.

guardrails.lock Lock all security.json fields
Lock every security.json key at every scope, so project, workspace, and global toggles stop having any effect and the merged config reports lockedFields covering all keys. Writes to a locked field return 409 PolicyLocked, as does reset-to-defaults while any guardrail is locked.
guardrails.lockedFields Locked fields Parsed
Lock a specific subset of security.json keys instead of the whole file. Use this for fine-grained control when guardrails.lock is too coarse.
guardrails.forceOutsideWorkspace Force outsideWorkspace
Open in generator "blocked" | "ask"
Pin the outsideWorkspace policy at every scope, so a project security.json cannot loosen it. "blocked" refuses every read or write outside the workspace; "ask" prompts for each access.
guardrails.mandatorySensitivePatterns Mandatory sensitive patterns
Glob patterns unioned into the merged sensitivePatterns list. Users cannot remove these entries at any scope.
guardrails.mandatoryBlockedCommands Mandatory blocked commands
Shell command glob patterns unioned into the merged blockedCommands list. Users cannot remove these entries at any scope.
guardrails.mandatoryAskCommands Mandatory ask commands Parsed
Shell command glob patterns the agent must ask before running. Unioned with the merged askCommands list; users cannot remove these.
guardrails.disableUserAllowedCommands Disable user allowedCommands Parsed
Prevent users from extending allowedCommands at any scope. The effective allowed list comes from policy and built-ins only.
guardrails.mandatoryPathPermissions Mandatory path permissions Parsed
Open in generator structured value — see description
Admin overlay on pathPermissions, which wins over user settings. Each key is an absolute path; each value is { read?, write?, bash? } with values "allowed" | "ask" | "blocked".

Marketplaces marketplaces Enforced

Controls which plugin marketplaces appear in the catalog, whether users can add or remove them, and which are pushed by policy.

IDs of marketplaces allowed to appear in the catalog. When set, GET /plugins/marketplaces filters down to this list.
IDs of marketplaces explicitly hidden from the catalog, even when they would otherwise be available.
Only show marketplaces that the curated directory has flagged as verified.
marketplaces.lockBuiltinDirectory Lock built-in directory
Refuse DELETE on the curated voidleap-directory marketplace. Users cannot remove the built-in catalog.
marketplaces.allowAddingMarketplaces Allow adding marketplaces
Allow users to POST new marketplaces. Set false to lock the catalog to whatever policy or built-ins deliver.
marketplaces.mandatory Mandatory marketplaces Parsed
Open in generator structured value — see description
Marketplaces pushed to every machine. Each entry needs id, name, and source ({ type: 'git'|'http', url, ref? }), and may set verified. Users cannot remove them.
marketplaces.allowedSourceTypes Allowed source types Parsed
Open in generator Array<"git" | "http">
Restrict which marketplace source types are accepted. Typically ["git"] to forbid raw HTTP sources.

Approval approval Enforced

Pins the permission mode and the timeout the permission broker applies to an unanswered prompt.

approval.disableModeAuto Disable auto approval
Refuse auto approval everywhere: the per-thread Auto toggle, the server default in Settings, and any custom mode whose approval is auto. Enabling the toggle (PATCH /thread/:id) or the default (POST /config/auto-approval) returns 409 PolicyLocked, the resolver never yields auto, a running loop ignores a mid-run request to turn it on, /chat degrades a custom auto mode to default, the Auto toggle renders disabled, and posture reports approvals.autoModeAllowed: false.
approval.decisionTimeoutMinutes Decision timeout (minutes)
Open in generator { value: integer ≥ 1, locked?: true }
How long an unanswered permission prompt waits before the broker denies it. A lock freezes the Security settings row and makes the write return 409 PolicyLocked.
approval.forceMode Force mode Parsed
Open in generator "ask" | "auto" | "inherit"
Pin the permission mode. "ask" prompts on every tool call, "auto" runs without prompting (subject to other guardrails), "inherit" uses the parent agent's mode.
approval.askTimeoutMinutes Ask timeout (minutes) Parsed
Open in generator { value: integer ≥ 1, locked?: true }
Cap how long an ask-mode prompt waits before auto-rejecting. Wrap with locked: true to prevent users from extending it.

Sandbox sandbox Enforced

Requires that tool execution happen inside the OS-level sandbox, and pins its restriction level and network confinement.

sandbox.required Sandbox required
Open in generator must be true
Enable the sandbox for every thread; the schema only accepts true. The enable toggle is frozen and attempts to disable it return 409 PolicyLocked.
Open in generator { value: "strict", locked?: true }
Pin the sandbox restriction level. "strict" blocks reads and writes outside the workspace; standard mode blocks writes only.
Open in generator { value: "allow" | "deny" | "allowlist" | "ask", locked?: true }
Pin network confinement for sandboxed tools: "allow" is unrestricted, "deny" blocks all network access, "allowlist" permits only the domains listed below, and "ask" prompts per domain. When auto approval is in effect (the Auto toggle, its default, or a custom auto mode), "ask" degrades to "allowlist", because auto approval never prompts and dropping to unrestricted allow would remove the confinement.
sandbox.allowedDomains Allowed domains
Domains reachable from the sandbox under allowlist or ask mode. This list replaces every user-configured allowlist rather than unioning with it, and user writes are refused — a domain list the user can extend would make a mandated allowlist trivial to defeat.

Security security Enforced

Secret masking for agent output; the exfiltration block and the guard rules are always on and cannot be set from policy. The current client's status endpoint reports this section as an unknown key even though the schema accepts it — the setting still applies.

Open in generator { value: boolean, locked?: true }
Controls the "Mask secrets everywhere" setting. A lock freezes the Settings › Agent toggle and makes POST /config/secret-redaction return 409 PolicyLocked; it never disables the exfiltration block or the guard rules.

Plugins plugins Enforced

Constrains which plugins can be installed, from which sources, and at which pinned revisions. Source checks run before anything is fetched; the fetched tree is then reviewed before installed files or hooks are published. Findings are scoped to the components you selected, conservatively — shared, unknown, ambiguous and file-less findings stay in scope. The gate runs static review; deep AI review stays optional, and static heuristics are not proof that a plugin is safe. Without a stronger policy, a suspicious or malicious verdict needs an acknowledgement of that exact verdict: a suspicious acknowledgement cannot approve malicious content, and a policy block cannot be acknowledged away. Updates run the same gate, and batch updates never acknowledge risk automatically.

plugins.requirePinnedSha Require pinned SHA
Refuse plugin installs whose effective remote ref is not a 40-character hexadecimal commit. Branch names and tags are refused. Local sources are exempt — use Allowed source types to restrict those.
plugins.allowedSourceTypes Allowed source types
Open in generator Array<"github" | "url" | "git-subdir" | "local">
Accept plugin sources only of the listed kinds: github, url, git-subdir, or local. Absence imposes no restriction, but an explicitly empty list permits no matching source. Dropping "local" blocks unaudited dev installs.
Accept remote plugin installs only from the listed repositories, matched exactly against a GitHub owner/repo string or a remote git URL. Absence imposes no restriction, but an explicitly empty list permits no matching remote source. Local sources are not matched here — use Allowed source types to control them.
plugins.requireSecurityReviewClean Require security review clean
Refuse any plugin install or update whose security verdict is not safe. A safe verdict does not mean zero findings. This is the stricter of the two verdict gates; Block malicious installs refuses only the malicious verdict.
plugins.blockMaliciousInstalls Block malicious installs
Refuse plugin installs and updates whose security verdict is malicious, even when the user acknowledges the risk. Off when absent. Require security review clean is stricter: it permits only a safe verdict.
plugins.disableInstall Disable install
Refuse every new plugin install. Pre-installed plugins continue to work. This is also one of the two extra restrictions the strict fallback applies to a broken policy file.
plugins.mandatoryInstalled Mandatory installed Parsed
Open in generator structured value — see description
Plugins that must be installed on every machine. Each entry is { marketplace, pluginName, pinnedSha? }. Missing plugins are installed on next launch.

MCP mcp Enforced

Controls which Model Context Protocol servers can be connected and how their credentials flow. Allow and deny entries match either the effective server name, including any plugin prefix, or the server's URL.

mcp.allowedServers Allowed servers
Open in generator structured value — see description
Restrict MCP connections to the listed servers, matched by effective name or url. The list is exclusive only when non-empty: an empty or absent list imposes no allow-list restriction. Denied servers still win.
mcp.deniedServers Denied servers
Open in generator structured value — see description
Refuse every MCP server matching one of these entries, by effective name or url. Deny wins over the allowed list, and an already-connected server is dropped on the next policy reload.
mcp.allowManagedOnly Allow managed only Parsed
Only MCP servers delivered by policy are usable. User-scoped servers are ignored.
mcp.disableUserScope Disable user scope
Ignore MCP server definitions from user scope, which is the global scope outside any project.
mcp.disableProjectScope Disable project scope
Ignore MCP server definitions from the per-project config.
mcp.disableOauth Disable OAuth Parsed
Refuse MCP servers that require OAuth authentication.
mcp.allowedTransports Allowed transports
Open in generator Array<"http">
Refuse MCP servers whose transport is not listed. Absence imposes no restriction, but an explicitly empty list permits none. Only "http" is defined — there is no stdio or SSE transport to allow.

Hooks hooks Enforced

Controls user-defined hooks (pre/post-tool, lifecycle) — disable entirely, restrict commands, or push mandatory entries. Hook policy applies at execution time, not at definition time.

Stop every hook from running. This is also one of the two extra restrictions the strict fallback applies to a broken policy file.
hooks.allowManagedOnly Allow managed only Parsed
Only hooks delivered by policy are executed; user-defined hooks are ignored.
hooks.disableUserScope Disable user scope
Stop hooks defined in user scope, which is the global scope outside any project.
hooks.allowedCommands Allowed commands
Restrict hooks to handlers whose every parsed command executable appears here, compound commands included. The list is exclusive only when non-empty. This is not an argument sandbox: allowing bash, sh, or any other interpreter still permits whatever code is passed to it.
hooks.maxTimeout Max timeout
Open in generator integer ≥ 1
Cap every hook handler's timeout at this many seconds. Must be a positive integer. This is a ceiling, not a value: the client takes the smaller of the handler's own timeout and this cap, a handler asking for more is clamped rather than refused, and handlers with no explicit timeout keep their 30-second default.
hooks.disableAsync Disable async
Run async hook handlers synchronously, blocking the triggering action until they complete.
hooks.mandatory Mandatory hooks Parsed
Open in generator structured value — see description
Hooks that must run on every triggering event. Each entry is a free-form record matching the hook definition shape.

Shell shell Enforced

Controls which shell binary Voidleap invokes and how much of the user's shell environment reaches agent commands.

shell.lockShell Lock shell Parsed
Open in generator { value: string, locked?: true }
Pin the shell binary used for shell-based tool execution. Wrap with locked: true to prevent overrides.
shell.disableRcLoading Disable rc loading
Forces "Load shell configuration" off: agent commands never run as a login shell, and the interactive-shell snapshot is disabled too because it is another way to load rc files. The settings row is frozen and writes return 409 PolicyLocked.
shell.disableEnvExtraction Disable env extraction
Never extract the login-shell environment for sandboxed agent commands; the server's own scrubbed process environment is used instead. The settings row is frozen and writes return 409 PolicyLocked.
shell.disableShellSnapshot Disable shell snapshot
Never take the interactive-shell snapshot: agent commands run without the functions and aliases from ~/.zshrc or ~/.bashrc (nvm, pyenv shims, user aliases). Implied by disableRcLoading. The settings row is frozen and writes return 409 PolicyLocked.
shell.envDenylist Environment denylist
Additional environment variable names removed from every agent-spawned child process, on top of the built-in denylist (SSH agent socket, AWS session credentials, askpass helpers, dynamic-loader hooks). Additive only: a policy cannot remove a built-in entry.

Parsed Parsed, enforcement landing

Skills skills Parsed Some fields enforced

Controls skill discovery, the script-execution surface, and which skill sources are usable.

skills.disableScriptExecution Disable script execution Enforced
Strip script-execution guidance from skill prompts and deny shell calls from skill-forked agents at the executor.
skills.disableUserScope Disable user scope
Prevent skills from being discovered in the user-scope skill directory.
skills.disableProjectScope Disable project scope
Prevent skills from being discovered in the per-project skill directory.
skills.disableWorkspaceScope Disable workspace scope
Prevent skills from being discovered in the per-workspace skill directory.
Only skills whose IDs appear in this list are usable.
Skills whose IDs appear here are hidden and refused at invocation.
skills.enforceAllowedTools Enforce allowed tools
Reject skills whose declared tool surface exceeds the calling agent's allowed tools.
Prevent the fork operation that copies a skill across scopes.
skills.requireApprovedSource Require approved source
Only allow skills whose source has been marked approved.

Precedence precedence Parsed

Disables lower-precedence config scopes outright. policyOverridesAll is always on and is not configurable here.

precedence.disableProjectScope Disable project scope
Ignore .voidleap/security.json (and the rest of the project scope) when merging config.
precedence.disableWorkspaceScope Disable workspace scope
Ignore workspace-scope config when merging.
precedence.disablePerCallOverrides Disable per-call overrides
Reject per-call overrides supplied in tool calls or agent frontmatter; the merged scope-stack value wins.

Agents agents Parsed Some fields enforced

Limits which agents are discoverable and pins their permissions, model, and token cap. Filtering runs before source precedence is merged. Built-in agents are exempt from the scope switches, but not from the name lists.

agents.allowList Allow list Enforced
Restrict agents to the listed IDs. The list is exclusive only when non-empty: an empty or absent list imposes no allow-list restriction. The deny list still wins over it.
agents.denyList Deny list Enforced
Refuse every agent whose ID appears here, hiding it from discovery and refusing it at invocation. Deny wins over the allow list.
agents.disableUserScope Disable user scope Enforced
Ignore agents defined in user scope, which is the global scope outside any project. Built-in agents are exempt.
agents.disableProjectScope Disable project scope Enforced
Ignore agents defined in the per-project agents directory. Built-in agents are exempt.
agents.mandatoryPermissions Mandatory permissions
Open in generator structured value — see description
Admin-enforced permission floor applied to every agent: { tools?: { allow?, deny? }, paths?: { allow?, deny? }, readPaths?: { allow?, deny? } }. Allow lists intersect; deny lists union.
Pin every agent to this model ID, overriding their frontmatter. Useful for routing all traffic through an approved deployment.
agents.maxTokensCap Max tokens cap
Open in generator integer ≥ 1
Hard cap on max-output tokens for any agent.
agents.disableThinking Disable thinking
Strip extended-thinking budgets from agent runs. Agents that requested thinking will run without it.

Tools tools Parsed Some fields enforced

Per-tool clamps: which tools are usable, plus settings for Bash, WebFetch, WebSearch, Read, Edit, and Task. The usable-tool lists match registered tool names and apply to primary agents, subagents, custom-tool registration and direct execution; a thread override cannot bypass them.

tools.disabled Disabled Enforced
Refuse every tool whose registered name appears here, for every agent. Deny wins over the allowed list.
tools.allowed Allowed Enforced
Restrict tools to the listed registered names. The list is exclusive only when non-empty: an empty or absent list imposes no allow-list restriction.
tools.disableImplementationOverrides Disable implementation overrides
Refuse per-call or per-agent overrides of a tool's implementation. Built-in implementations win.
tools.bash.mandatoryBlockedCommands Bash: mandatory blocked commands
Shell command patterns the Bash tool must refuse, regardless of user or agent settings. Unioned with the user list.
tools.bash.maxTimeoutCap Bash: max timeout cap
Open in generator integer ≥ 1
Hard cap on the timeout (in seconds) a Bash invocation can request.
tools.bash.shell Bash: shell
Open in generator { value: string, locked?: true }
Force Bash to use a specific shell binary. Wrap with locked: true to prevent overrides.
tools.bash.disableEnvInjection Bash: disable env injection
Refuse per-call env-variable injection on Bash invocations.
tools.bash.disableCwdOverride Bash: disable cwd override
Refuse per-call cwd overrides on Bash invocations. Tools run in the agent's default working directory.
tools.webFetch.allowedDomains WebFetch: allowed domains
When set, WebFetch refuses any URL whose host is not on this list.
tools.webFetch.deniedDomains WebFetch: denied domains
WebFetch refuses any URL whose host matches this list.
tools.webFetch.allowPrivateIp WebFetch: deny private IPs
Open in generator must be false
Pin WebFetch's private-IP allowance off. Requests resolving to RFC1918, loopback, or link-local addresses are refused.
tools.webFetch.userAgent WebFetch: user agent
Open in generator { value: string, locked?: true }
Force WebFetch to use a specific User-Agent string. Wrap with locked: true to prevent overrides.
tools.webFetch.provider WebFetch: provider
Open in generator { value: "jina" | "direct", locked?: true }
Pin the WebFetch backend. "direct" fetches in-process; "jina" routes through the Jina reader.
tools.webSearch.provider WebSearch: provider
Open in generator { value: string, locked?: true }
Pin the WebSearch backend by ID. Wrap with locked: true to prevent overrides.
tools.webSearch.disable WebSearch: disable
Disable the WebSearch tool entirely.
tools.read.maxFileSize Read: max file size
Open in generator integer ≥ 1
Hard cap (in bytes) on a single Read tool invocation.
tools.edit.createBackup Edit: create backup
Open in generator { value: boolean, locked?: true }
Force Edit to write (or skip) a sibling backup before modifying a file. Wrap with locked: true to prevent overrides.
tools.task.maxConcurrent Task: max concurrent
Open in generator integer ≥ 1
Cap on the number of subagents that can run in parallel.
tools.task.defaultTimeout Task: default timeout
Open in generator integer ≥ 1
Default per-subagent timeout in seconds.

Automations automations Parsed

Controls background automations (cron, timers) — disable, throttle, cap retention, or strip the user shell from prompts.

Disable the automations subsystem entirely.
automations.disableTriggerTypes Disable trigger types
Open in generator Array<"cron" | "timer">
Subset of automation trigger types to refuse.
Open in generator integer ≥ 1
Cap on the number of automation runs that can be in flight at once.
automations.maxRetentionDays Max retention (days)
Open in generator integer ≥ 1
Cap on how long automation run history is kept, in days.
Open in generator { value: integer ≥ 0, locked?: true }
Cap on hook-chain recursion depth in automation runs. 0 disables hook chaining. Wrap with locked: true to prevent overrides.
automations.disableUserShellInPrompts Disable user shell in prompts
Strip the user-shell rendering from automation prompts so prompts do not include local shell output.

Providers providers Parsed

Allow- or block-list LLM providers; disable Ollama specifically.

Only providers whose IDs appear here are usable.
Providers whose IDs appear here are hidden.
Specifically refuse the Ollama (local model) provider.

Models models Parsed

Allow- or block-list specific model IDs across all enabled providers.

Only models whose IDs appear here can be selected.
Models whose IDs appear here are hidden.

Model tiers modelTiers Parsed

Cross-model caps: lock the tier preset, cap output tokens, or strip extended thinking.

Lock the active model-tier preset so users cannot switch tiers (e.g. between standard and high-tier).
modelTiers.maxOutputTokensCap Max output tokens cap
Open in generator integer ≥ 1
Hard cap on max-output tokens across every tier.
Strip extended-thinking budgets across every tier.

Auth auth Parsed

Controls how users sign in, where API keys come from, and which email domains a license can bind to.

auth.allowedLoginMethods Allowed login methods
Open in generator Array<"anthropic-oauth" | "anthropic-api-key" | "openai-oauth" | "openai-api-key" | "gemini" | "openrouter" | "azure" | "bedrock" | "github-copilot" | "antigravity">
Restrict the set of sign-in methods offered. Methods outside this list are hidden from the auth UI.
auth.disableLocalApiKeys Disable local API keys
Refuse API keys entered through the UI. Combine with envOnlyApiKeys to require environment-supplied credentials.
auth.requireLicenseEmailDomain Require license email domain
Only accept Voidleap licenses whose owner email is on one of these domains. Useful for restricting installs to corporate accounts.
auth.envOnlyApiKeys Env-only API keys
Only read provider API keys from environment variables. UI-stored or config-stored keys are ignored.
auth.disableCustomServerUrl Disable custom server URL
Refuse user-supplied custom server URLs at auth time. Users must connect to the default Voidleap auth endpoint.

Network network Parsed

HTTP egress controls: proxy, allowed domains, custom CAs, mTLS, and which hosts the local server binds.

Refuse outbound requests that do not flow through the configured proxy.
Force outbound HTTP through this proxy URL.
network.allowedDomains Allowed domains
Allow-list of hosts for any outbound network call from Voidleap.
network.extraCaCertPath Extra CA cert path
Filesystem path to an extra CA bundle to trust for HTTPS.
network.mTlsCertPath mTLS cert path
Filesystem path to the client certificate used for mutual-TLS connections.
network.mTlsKeyPath mTLS key path
Filesystem path to the private key paired with the mTLS client certificate.
network.disableLicenseTlsPin Disable license TLS pin
Skip the built-in certificate pin used when talking to the licensing service. Required in MITM-proxy environments.
network.allowedServerBindHosts Allowed server bind hosts
Allow-list of hosts the local Voidleap server is permitted to bind. Bind requests outside this list are refused.

Browser browser Parsed

Controls the built-in browser subagent — disable it, restrict origins, or strip captured data.

Disable the built-in browser subagent entirely.
browser.disablePersistentPartition Disable persistent partition
Always launch the browser in a fresh, non-persistent partition. Cookies and storage do not survive between sessions.
browser.allowedOrigins Allowed origins
Allow-list of origins the browser is permitted to navigate.
browser.disableConsoleLogCapture Disable console log capture
Refuse to capture browser console output back to the agent context. Useful when consoles can leak sensitive data.

Telemetry telemetry Parsed

Disable telemetry or point OpenTelemetry traces at a custom endpoint.

Disable Voidleap's telemetry emission entirely.
OTLP endpoint to send OpenTelemetry traces and metrics to.

Logging logging Parsed

Retention cap for local log files and where error logs are uploaded.

logging.maxRetentionDays Max retention (days)
Open in generator integer ≥ 1
Cap on how long log files are kept before rotation, in days.
logging.errorLogUploadEndpoint Error log upload endpoint
URL to receive crash and error logs from this machine.

App / Updates app Parsed

Pins the minimum acceptable app version, the update channel, and whether auto-update runs.

app.minimumVersion Minimum version
Refuse to run on app versions older than this (semver). Useful for enforcing a security patch baseline.
app.updateMode Update mode
Open in generator "auto" | "manual" | "disabled"
How updates are applied. "auto" installs in the background, "manual" requires user action, "disabled" turns updates off.
app.updateChannel Update channel
Open in generator "stable" | "beta"
Pin the release channel — "stable" or "beta".
app.disableUpdateChecks Disable update checks
Disable the background poll that checks for new versions. Combine with updateMode: 'disabled' for fully offline machines.

Context context Parsed

Controls the AGENTS.md / context payload — push a mandatory file, suppress the user's, cap import depth.

context.mandatoryAgentsMd Mandatory AGENTS.md
Content (or filesystem path, by convention) of an AGENTS.md prepended to every agent's context.
context.disableUserAgentsMd Disable user AGENTS.md
Ignore the AGENTS.md found in the user's home directory.
context.maxImportDepth Max import depth
Open in generator { value: integer ≥ 0, locked?: true }
Cap on @import chain depth inside markdown context files. 0 disables imports. Wrap with locked: true to prevent overrides.
context.disableMarkdownImports Disable markdown imports
Refuse all @import directives in markdown context files.

Library library Parsed

Forces specific library entries (agents, skills, automations, etc.) to be disabled or hidden in the UI.

library.mandatoryDisabled Mandatory disabled
Library entry IDs (agents, skills, automations) that must be disabled. Users cannot re-enable them.
library.mandatoryHidden Mandatory hidden
Library entry IDs that are hidden from the UI entirely. Implies mandatoryDisabled.

Deferred Parsed, deferred

Modes modes Deferred

Allow- or block-list permission/mode presets and ignore user-scope modes.

Only modes whose IDs appear here are usable.
Modes whose IDs appear here are hidden.
modes.disableUserScope Disable user scope
Ignore modes defined in the user-scope config.

Code index codeIndex Deferred

Disables or throttles the background code-index that powers symbol search.

Disable the code index entirely. Symbol search falls back to grep.
Disable automatic re-indexing on file changes. Index is only rebuilt when explicitly requested.
Open in generator integer ≥ 1
Cap on the size (in bytes) of a file the indexer will parse. Larger files are skipped.
codeIndex.maxFilesAutoSeed Max files auto-seed
Open in generator integer ≥ 1
Cap on how many files the indexer will seed automatically when first attaching to a workspace.

Validation validation Deferred

Pins the severity of validation findings and forces specific codes to be suppressed.

Open in generator { value: "error" | "warning" | "off", locked?: true }
Pin the global validation severity — "error" fails, "warning" reports, "off" disables. Wrap with locked: true to prevent overrides.
validation.mandatorySuppressedCodes Mandatory suppressed codes
Open in generator structured value — see description
Validation rule codes that are forcibly suppressed. Users cannot un-suppress them.

REPL repl Deferred

Controls the interactive REPL — which providers it can use and whether it summarises long sessions.

repl.allowedProviders Allowed providers
Only providers whose IDs appear here are usable from the REPL.
repl.disableSummarization Disable summarization
Disable the REPL's automatic context summarisation. Long sessions hit the context cap instead.

UI ui Deferred

Strips client-side affordances: TTS, custom server URL, the guided tour.

ui.disableTtsApiKey Disable TTS API key
Hide the text-to-speech API-key input from the UI.
ui.disableCustomServerUrl Disable custom server URL
Hide the custom-server URL input from the UI. Users must connect to the default endpoint.
ui.disableGuidedTour Disable guided tour
Suppress the first-run guided tour overlay.

Deploying the file

A policy in the wrong place is never loaded. A policy in the right place that the loader rejects is not ignored — by default it locks the machine down instead.

Where it goes
The loader checks exactly one path and stops: VOIDLEAP_POLICY_PATH when set (testing only, and logged loudly), otherwise the first of these that matches the host.
  • Linux /etc/voidleap/policy.json
  • macOS /Library/Application Support/Voidleap/policy.json
  • Windows C:\ProgramData\Voidleap\policy.json
Ownership
On Linux and macOS the file must be owned by root (uid 0). On Windows it must stay under C:\ProgramData\Voidleap\. A file that fails this check is not ignored: it counts as a rejected file and takes the fallback below. The reason is logged and reported by GET /policy/status.
Missing versus broken: the strict fallback
A missing file still means no managed policy at all. A file that is present but unreadable, wrongly owned, malformed, or schema-invalid fails closed by default: the loader applies a restrictive fallback policy instead of yours. That fallback keeps its own baseline restrictions and additionally sets:
  • plugins.disableInstall: true
  • hooks.disable: true

Setting VOIDLEAP_POLICY_STRICT_FALLBACK=0 or VOIDLEAP_POLICY_STRICT_FALLBACK=false restores the old permissive behaviour. Unset, or any other value, leaves strict fallback on. It is a server environment setting, not a field in policy.json, so it cannot be set from this generator. Repair the file and reload instead of leaning on the fallback: it is a safety net, not a configuration.

Precedence
policy > project > workspace > global > defaults > per-call > agent-frontmatter. A locked policy field short-circuits every scope below it, so a project .voidleap/security.json cannot loosen a policy-locked guardrail.
Managed defaults versus mandates
A field shaped { value } is a managed default: it applies when the user has not chosen a value, and an explicit user setting still wins. A field shaped { value, locked: true } is a mandate: it short-circuits settings and per-thread overrides, and the matching write returns 409 PolicyLocked. The generator's three-state control writes exactly this — Not set deletes the field, Default writes the first shape, Locked writes the second.
Status, reload, and the audit log
GET /policy/status reports whether a policy was applied, its source and path, when it was loaded, every locked dotted path, unknown keys, validation errors, and whether the strict fallback is in effect. The result is cached for the lifetime of the process: restart, or call GET /policy/status?reload=true. A reload does more than re-read the file — it also refreshes the already-loaded runtime configurations and the agent, custom-tool, and MCP server registrations, so a repaired file takes effect without a full restart. Policy edits are appended to ~/.voidleap/logs/policy.jsonl.