Configuration reference

Cmdveil reads one JSON object containing server and actions. Unknown JSON fields are rejected so configuration typos cannot silently weaken a policy. Every executable action and every placeholder is validated before the server starts.

Server fields

Field	Type	Default	Meaning
bind	string	127.0.0.1	IPv4 address to listen on
port	integer	7777	TCP port, 1–65535
token_env	string	CMDVEIL_TOKEN	Environment variable containing the bearer token
max_request_bytes	integer	65536	Maximum JSON body size
max_header_bytes	integer	16384	Maximum request-header size
global_concurrency	integer	8	Maximum simultaneous actions
max_connections	integer	128	Maximum simultaneous client connections
rate_limit_per_minute	integer	120	Requests per remote IP per fixed minute window
audit_log	string/null	./cmdveil-audit.jsonl	JSONL audit destination; use null to disable

The token must contain at least 16 characters. Generate one with cmdveil token.

Action fields

Field	Type	Default	Meaning
description	string	omitted	Human-readable description returned by /v1/actions
executable	string	required	Absolute executable path
arguments	string array	[]	Fixed arguments and complete placeholders
parameters	object	{}	Declared request parameters
timeout_seconds	number	30	Wall-clock timeout, maximum 86400
max_output_bytes	integer	262144	Maximum bytes retained independently for stdout and stderr
concurrency	integer	1	Maximum simultaneous executions of this action
working_directory	string	omitted	Existing directory used as process working directory
environment	object	{}	Explicit environment variables
inherit_environment	string array	[]	Names copied from Cmdveil’s own environment

Environment inheritance is denied by default. This prevents credentials and unrelated daemon state from leaking into child processes.

Parameter fields

Field	Applies to	Meaning
type	all	string, integer, boolean, or enum
required	all	Parameter must be present
default	all	Used when parameter is omitted; cannot coexist with required: true
sensitive	all	Replaces the value with [redacted] in audit records
min, max	integer	Inclusive numeric limits
min_length, max_length	string/enum	Character-count limits
pattern	string/enum	Regular expression that must match the entire string
values	enum	Non-empty allowlist of accepted strings

Integer and boolean values may be sent as native JSON values. The strings "true", "false", and integer strings are also accepted for convenient clients.

Placeholder rules

{{parameter}} is replaced with one process argument. The placeholder must occupy the whole JSON string.

Valid:

["--user", "{{user}}", "--count", "{{count}}"]

Invalid:

["--user={{user}}"]

A fixed argument containing braces is left unchanged unless it begins with {{ and ends with }}; malformed placeholder-like values are rejected during configuration validation.

Source