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.
- guardrails.lock
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.
- guardrails.forceOutsideWorkspace
Pin the outsideWorkspace policy at every scope, so a project security.json cannot loosen it.
- guardrails.mandatorySensitivePatterns
Glob patterns unioned into the merged sensitivePatterns list.
- guardrails.mandatoryBlockedCommands
Shell command glob patterns unioned into the merged blockedCommands list.
- marketplaces.allowList
IDs of marketplaces allowed to appear in the catalog.
- marketplaces.blockList
IDs of marketplaces explicitly hidden from the catalog, even when they would otherwise be available.
- marketplaces.requireVerified
Only show marketplaces that the curated directory has flagged as verified.
- marketplaces.lockBuiltinDirectory
Refuse DELETE on the curated voidleap-directory marketplace.
- marketplaces.allowAddingMarketplaces
Allow users to POST new marketplaces.
- approval.disableModeAuto
Refuse auto approval everywhere: the per-thread Auto toggle, the server default in Settings, and any custom mode whose approval is auto.
- approval.decisionTimeoutMinutes
How long an unanswered permission prompt waits before the broker denies it.
- sandbox.required
Enable the sandbox for every thread; the schema only accepts true.
- sandbox.mode
Pin the sandbox restriction level.
- sandbox.networkMode
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.
- sandbox.allowedDomains
Domains reachable from the sandbox under allowlist or ask mode.
- security.secretRedaction
Controls the "Mask secrets everywhere" setting.
- skills.disableScriptExecution
Strip script-execution guidance from skill prompts and deny shell calls from skill-forked agents at the executor.
- plugins.requirePinnedSha
Refuse plugin installs whose effective remote ref is not a 40-character hexadecimal commit.
- plugins.allowedSourceTypes
Accept plugin sources only of the listed kinds: github, url, git-subdir, or local.
- plugins.allowedRepos
Accept remote plugin installs only from the listed repositories, matched exactly against a GitHub owner/repo string or a remote git URL.
- plugins.requireSecurityReviewClean
Refuse any plugin install or update whose security verdict is not safe.
- plugins.blockMaliciousInstalls
Refuse plugin installs and updates whose security verdict is malicious, even when the user acknowledges the risk.
- plugins.disableInstall
Refuse every new plugin install.
- agents.allowList
Restrict agents to the listed IDs.
- agents.denyList
Refuse every agent whose ID appears here, hiding it from discovery and refusing it at invocation.
- agents.disableUserScope
Ignore agents defined in user scope, which is the global scope outside any project.
- agents.disableProjectScope
Ignore agents defined in the per-project agents directory.
- tools.disabled
Refuse every tool whose registered name appears here, for every agent.
- tools.allowed
Restrict tools to the listed registered names.
- mcp.allowedServers
Restrict MCP connections to the listed servers, matched by effective name or url.
- mcp.deniedServers
Refuse every MCP server matching one of these entries, by effective name or url.
- mcp.disableUserScope
Ignore MCP server definitions from user scope, which is the global scope outside any project.
- mcp.disableProjectScope
Ignore MCP server definitions from the per-project config.
- mcp.allowedTransports
Refuse MCP servers whose transport is not listed.
- hooks.disable
Stop every hook from running.
- hooks.disableUserScope
Stop hooks defined in user scope, which is the global scope outside any project.
- hooks.allowedCommands
Restrict hooks to handlers whose every parsed command executable appears here, compound commands included.
- hooks.maxTimeout
Cap every hook handler's timeout at this many seconds.
- hooks.disableAsync
Run async hook handlers synchronously, blocking the triggering action until they complete.
- shell.disableRcLoading
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.
- shell.disableEnvExtraction
Never extract the login-shell environment for sandboxed agent commands; the server's own scrubbed process environment is used instead.
- shell.disableShellSnapshot
Never take the interactive-shell snapshot: agent commands run without the functions and aliases from ~/.zshrc or ~/.bashrc (nvm, pyenv shims, user aliases).
- shell.envDenylist
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).
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 fieldsOpen in generator
boolean - 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.
- Open in generator
string[] - 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 outsideWorkspaceOpen 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 patternsOpen in generator
string[] - Glob patterns unioned into the merged sensitivePatterns list. Users cannot remove these entries at any scope.
- guardrails.mandatoryBlockedCommands Mandatory blocked commandsOpen in generator
string[] - Shell command glob patterns unioned into the merged blockedCommands list. Users cannot remove these entries at any scope.
- Open in generator
string[] - Shell command glob patterns the agent must ask before running. Unioned with the merged askCommands list; users cannot remove these.
- Open in generator
boolean - Prevent users from extending allowedCommands at any scope. The effective allowed list comes from policy and built-ins only.
- 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.
- marketplaces.allowList Allow listOpen in generator
string[] - IDs of marketplaces allowed to appear in the catalog. When set, GET /plugins/marketplaces filters down to this list.
- marketplaces.blockList Block listOpen in generator
string[] - IDs of marketplaces explicitly hidden from the catalog, even when they would otherwise be available.
- marketplaces.requireVerified Require verifiedOpen in generator
boolean - Only show marketplaces that the curated directory has flagged as verified.
- marketplaces.lockBuiltinDirectory Lock built-in directoryOpen in generator
boolean - Refuse DELETE on the curated voidleap-directory marketplace. Users cannot remove the built-in catalog.
- marketplaces.allowAddingMarketplaces Allow adding marketplacesOpen in generator
boolean - Allow users to POST new marketplaces. Set false to lock the catalog to whatever policy or built-ins deliver.
- 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.
- 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 approvalOpen in generator
boolean - 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.
- 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.
- 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 requiredOpen 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.
- sandbox.mode ModeOpen in generator
{ value: "strict", locked?: true } - Pin the sandbox restriction level. "strict" blocks reads and writes outside the workspace; standard mode blocks writes only.
- sandbox.networkMode Network modeOpen 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 domainsOpen in generator
string[] - 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.
- security.secretRedaction Secret redactionOpen 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 SHAOpen in generator
boolean - 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 typesOpen 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.
- plugins.allowedRepos Allowed reposOpen in generator
string[] - 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 cleanOpen in generator
boolean - 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 installsOpen in generator
boolean - 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 installOpen in generator
boolean - 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.
- 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 serversOpen 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 serversOpen 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.
- Open in generator
boolean - Only MCP servers delivered by policy are usable. User-scoped servers are ignored.
- mcp.disableUserScope Disable user scopeOpen in generator
boolean - Ignore MCP server definitions from user scope, which is the global scope outside any project.
- mcp.disableProjectScope Disable project scopeOpen in generator
boolean - Ignore MCP server definitions from the per-project config.
- Open in generator
boolean - Refuse MCP servers that require OAuth authentication.
- mcp.allowedTransports Allowed transportsOpen 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.
- hooks.disable DisableOpen in generator
boolean - Stop every hook from running. This is also one of the two extra restrictions the strict fallback applies to a broken policy file.
- Open in generator
boolean - Only hooks delivered by policy are executed; user-defined hooks are ignored.
- hooks.disableUserScope Disable user scopeOpen in generator
boolean - Stop hooks defined in user scope, which is the global scope outside any project.
- hooks.allowedCommands Allowed commandsOpen in generator
string[] - 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 timeoutOpen 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 asyncOpen in generator
boolean - Run async hook handlers synchronously, blocking the triggering action until they complete.
- 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.
- 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 loadingOpen in generator
boolean - 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 extractionOpen in generator
boolean - 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 snapshotOpen in generator
boolean - 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 denylistOpen in generator
string[] - 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.
- Open in generator
boolean - Strip script-execution guidance from skill prompts and deny shell calls from skill-forked agents at the executor.
- skills.disableUserScope Disable user scopeOpen in generator
boolean - Prevent skills from being discovered in the user-scope skill directory.
- skills.disableProjectScope Disable project scopeOpen in generator
boolean - Prevent skills from being discovered in the per-project skill directory.
- skills.disableWorkspaceScope Disable workspace scopeOpen in generator
boolean - Prevent skills from being discovered in the per-workspace skill directory.
- skills.allowList Allow listOpen in generator
string[] - Only skills whose IDs appear in this list are usable.
- skills.denyList Deny listOpen in generator
string[] - Skills whose IDs appear here are hidden and refused at invocation.
- skills.enforceAllowedTools Enforce allowed toolsOpen in generator
boolean - Reject skills whose declared tool surface exceeds the calling agent's allowed tools.
- skills.disableFork Disable forkOpen in generator
boolean - Prevent the fork operation that copies a skill across scopes.
- skills.requireApprovedSource Require approved sourceOpen in generator
boolean - 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 scopeOpen in generator
boolean - Ignore .voidleap/security.json (and the rest of the project scope) when merging config.
- precedence.disableWorkspaceScope Disable workspace scopeOpen in generator
boolean - Ignore workspace-scope config when merging.
- precedence.disablePerCallOverrides Disable per-call overridesOpen in generator
boolean - 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.
- Open in generator
string[] - 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.
- Open in generator
string[] - Refuse every agent whose ID appears here, hiding it from discovery and refusing it at invocation. Deny wins over the allow list.
- Open in generator
boolean - Ignore agents defined in user scope, which is the global scope outside any project. Built-in agents are exempt.
- Open in generator
boolean - Ignore agents defined in the per-project agents directory. Built-in agents are exempt.
- agents.mandatoryPermissions Mandatory permissionsOpen 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.
- agents.forceModel Force modelOpen in generator
string - Pin every agent to this model ID, overriding their frontmatter. Useful for routing all traffic through an approved deployment.
- agents.maxTokensCap Max tokens capOpen in generator
integer ≥ 1 - Hard cap on max-output tokens for any agent.
- agents.disableThinking Disable thinkingOpen in generator
boolean - 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.
- Open in generator
string[] - Refuse every tool whose registered name appears here, for every agent. Deny wins over the allowed list.
- Open in generator
string[] - 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 overridesOpen in generator
boolean - Refuse per-call or per-agent overrides of a tool's implementation. Built-in implementations win.
- tools.bash.mandatoryBlockedCommands Bash: mandatory blocked commandsOpen in generator
string[] - 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 capOpen in generator
integer ≥ 1 - Hard cap on the timeout (in seconds) a Bash invocation can request.
- tools.bash.shell Bash: shellOpen 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 injectionOpen in generator
boolean - Refuse per-call env-variable injection on Bash invocations.
- tools.bash.disableCwdOverride Bash: disable cwd overrideOpen in generator
boolean - Refuse per-call cwd overrides on Bash invocations. Tools run in the agent's default working directory.
- tools.webFetch.allowedDomains WebFetch: allowed domainsOpen in generator
string[] - When set, WebFetch refuses any URL whose host is not on this list.
- tools.webFetch.deniedDomains WebFetch: denied domainsOpen in generator
string[] - WebFetch refuses any URL whose host matches this list.
- tools.webFetch.allowPrivateIp WebFetch: deny private IPsOpen 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 agentOpen 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: providerOpen 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: providerOpen in generator
{ value: string, locked?: true } - Pin the WebSearch backend by ID. Wrap with locked: true to prevent overrides.
- tools.webSearch.disable WebSearch: disableOpen in generator
boolean - Disable the WebSearch tool entirely.
- tools.read.maxFileSize Read: max file sizeOpen in generator
integer ≥ 1 - Hard cap (in bytes) on a single Read tool invocation.
- tools.edit.createBackup Edit: create backupOpen 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 concurrentOpen in generator
integer ≥ 1 - Cap on the number of subagents that can run in parallel.
- tools.task.defaultTimeout Task: default timeoutOpen 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.
- automations.disable DisableOpen in generator
boolean - Disable the automations subsystem entirely.
- automations.disableTriggerTypes Disable trigger typesOpen in generator
Array<"cron" | "timer"> - Subset of automation trigger types to refuse.
- automations.maxConcurrency Max concurrencyOpen 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.
- automations.hookMaxDepth Hook max depthOpen 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 promptsOpen in generator
boolean - 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.
- providers.allowList Allow listOpen in generator
string[] - Only providers whose IDs appear here are usable.
- providers.blockList Block listOpen in generator
string[] - Providers whose IDs appear here are hidden.
- providers.disableOllama Disable OllamaOpen in generator
boolean - Specifically refuse the Ollama (local model) provider.
Models models Parsed
Allow- or block-list specific model IDs across all enabled providers.
- models.allowList Allow listOpen in generator
string[] - Only models whose IDs appear here can be selected.
- models.blockList Block listOpen in generator
string[] - 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.
- modelTiers.locked LockedOpen in generator
boolean - Lock the active model-tier preset so users cannot switch tiers (e.g. between standard and high-tier).
- modelTiers.maxOutputTokensCap Max output tokens capOpen in generator
integer ≥ 1 - Hard cap on max-output tokens across every tier.
- modelTiers.disableThinking Disable thinkingOpen in generator
boolean - 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 methodsOpen 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 keysOpen in generator
boolean - Refuse API keys entered through the UI. Combine with envOnlyApiKeys to require environment-supplied credentials.
- auth.requireLicenseEmailDomain Require license email domainOpen in generator
string[] - 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 keysOpen in generator
boolean - Only read provider API keys from environment variables. UI-stored or config-stored keys are ignored.
- auth.disableCustomServerUrl Disable custom server URLOpen in generator
boolean - 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.
- network.requireProxy Require proxyOpen in generator
boolean - Refuse outbound requests that do not flow through the configured proxy.
- network.proxyUrl Proxy URLOpen in generator
string - Force outbound HTTP through this proxy URL.
- network.allowedDomains Allowed domainsOpen in generator
string[] - Allow-list of hosts for any outbound network call from Voidleap.
- network.extraCaCertPath Extra CA cert pathOpen in generator
string - Filesystem path to an extra CA bundle to trust for HTTPS.
- network.mTlsCertPath mTLS cert pathOpen in generator
string - Filesystem path to the client certificate used for mutual-TLS connections.
- network.mTlsKeyPath mTLS key pathOpen in generator
string - Filesystem path to the private key paired with the mTLS client certificate.
- network.disableLicenseTlsPin Disable license TLS pinOpen in generator
boolean - Skip the built-in certificate pin used when talking to the licensing service. Required in MITM-proxy environments.
- network.allowedServerBindHosts Allowed server bind hostsOpen in generator
string[] - 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.
- browser.disable DisableOpen in generator
boolean - Disable the built-in browser subagent entirely.
- browser.disablePersistentPartition Disable persistent partitionOpen in generator
boolean - Always launch the browser in a fresh, non-persistent partition. Cookies and storage do not survive between sessions.
- browser.allowedOrigins Allowed originsOpen in generator
string[] - Allow-list of origins the browser is permitted to navigate.
- browser.disableConsoleLogCapture Disable console log captureOpen in generator
boolean - 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.
- telemetry.disabled DisabledOpen in generator
boolean - Disable Voidleap's telemetry emission entirely.
- telemetry.otelEndpoint OTel endpointOpen in generator
string - 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 endpointOpen in generator
string - 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 versionOpen in generator
string - Refuse to run on app versions older than this (semver). Useful for enforcing a security patch baseline.
- app.updateMode Update modeOpen 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 channelOpen in generator
"stable" | "beta" - Pin the release channel — "stable" or "beta".
- app.disableUpdateChecks Disable update checksOpen in generator
boolean - 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.mdOpen in generator
string - Content (or filesystem path, by convention) of an AGENTS.md prepended to every agent's context.
- context.disableUserAgentsMd Disable user AGENTS.mdOpen in generator
boolean - Ignore the AGENTS.md found in the user's home directory.
- context.maxImportDepth Max import depthOpen 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 importsOpen in generator
boolean - 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 disabledOpen in generator
string[] - Library entry IDs (agents, skills, automations) that must be disabled. Users cannot re-enable them.
- library.mandatoryHidden Mandatory hiddenOpen in generator
string[] - 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.
- modes.allowList Allow listOpen in generator
string[] - Only modes whose IDs appear here are usable.
- modes.denyList Deny listOpen in generator
string[] - Modes whose IDs appear here are hidden.
- modes.disableUserScope Disable user scopeOpen in generator
boolean - Ignore modes defined in the user-scope config.
Code index codeIndex Deferred
Disables or throttles the background code-index that powers symbol search.
- codeIndex.disable DisableOpen in generator
boolean - Disable the code index entirely. Symbol search falls back to grep.
- codeIndex.manualOnly Manual onlyOpen in generator
boolean - Disable automatic re-indexing on file changes. Index is only rebuilt when explicitly requested.
- codeIndex.maxFileBytes Max file bytesOpen 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-seedOpen 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.
- validation.severity SeverityOpen 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 codesOpen 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 providersOpen in generator
string[] - Only providers whose IDs appear here are usable from the REPL.
- repl.disableSummarization Disable summarizationOpen in generator
boolean - 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 keyOpen in generator
boolean - Hide the text-to-speech API-key input from the UI.
- ui.disableCustomServerUrl Disable custom server URLOpen in generator
boolean - Hide the custom-server URL input from the UI. Users must connect to the default endpoint.
- ui.disableGuidedTour Disable guided tourOpen in generator
boolean - 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_PATHwhen 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
- Linux
- 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 byGET /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=0orVOIDLEAP_POLICY_STRICT_FALLBACK=falserestores the old permissive behaviour. Unset, or any other value, leaves strict fallback on. It is a server environment setting, not a field inpolicy.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.jsoncannot 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/statusreports 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 callGET /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.