The policy file

The policy says which secrets exist and how agents may use them. It lives at ~/.config/keymitt/policy.toml (%APPDATA%\keymitt\policy.toml on Windows) and contains no secret values, so it is safe to keep in your dotfiles.

version = 1

[approval]
method = "auto"
ttl_secs = 0
timeout_secs = 120
allow_weak = true

[secrets.github]
description = "GitHub fine-grained token"
channels = ["http"]
hosts = ["api.github.com"]

[secrets.pg-staging]
description = "staging DB password"
channels = ["env", "stdin"]
commands = ["/opt/homebrew/bin/psql"]
env = ["PGPASSWORD"]

[files]
read_roots = ["~/projects/infra"]

You can edit it by hand or with keymitt add, keymitt allow and keymitt disallow. Unknown keys are rejected, so a typo cannot silently weaken a rule. The MCP server reads the policy when it starts — restart it after a change.

Channels

A channel is how a secret may reach its destination.

Channel	The value is…
stdin	written to the program's standard input
env	set as an environment variable of the program
file	written to an owner-only temporary file, overwritten and deleted after the run
http	sent by keymitt itself in an HTTP request (http_request)

There is no channel for command-line arguments: other processes on the machine can read them.

When you run keymitt add without --channel, keymitt picks channels from the rules you gave: --command enables stdin, env and file; --host enables http.

Programs

commands lists the programs that may receive the secret through stdin, env or file:

Entry	Matches
/opt/homebrew/bin/psql	exactly that file
psql	any program named psql in an absolute PATH directory — avoid; see below
*	any program — avoid this

keymitt add --command psql and keymitt allow --command psql resolve the name immediately and store the full path, so prefer those over writing bare names by hand; keymitt doctor points out bare names. When a request arrives, the program is looked up only in the absolute directories of keymitt's own PATH — relative or empty entries, which would resolve against a directory the agent may control, are ignored — and relative paths such as ./tool are refused.

Don't allowlist shells or interpreters

sh, bash, python or node can do anything with a secret they receive. Allow the specific tool instead.

Environment variable names

A secret passed through env goes into one variable, and the variable's value must be exactly the placeholder. Names that change how a program loads code or configuration — PATH, HOME, LD_*, DYLD_*, BASH_FUNC_*, GIT_*, NODE_*, PYTHON*, CARGO_*, proxy and CA variables, pagers and editors, and others — are always refused (registry tokens such as NODE_AUTH_TOKEN and CARGO_REGISTRY_TOKEN are allowed). To pin the names a secret may use, list them:

env = ["PGPASSWORD"]

Hosts

hosts lists where http_request may send the secret:

Entry	Matches
api.github.com	HTTPS on port 443 to exactly that host
*.example.com	HTTPS on port 443 to any subdomain of example.com (not example.com itself)
http://127.0.0.1:8080	exactly that scheme, host and port — for local plain-HTTP services
*	any HTTPS host — avoid this

Files the agent may read

read_file_redacted reads only below the MCP server's working directory — your project, when your client starts the server there — and the directories in [files] read_roots. A working directory that is your home directory or a filesystem root is not used. Credential stores (~/.ssh, ~/.aws, ~/.cloudflared, ~/.netrc, keychains, …) and key files (id_*, *.pem, *.key, …) are refused even inside those directories.

[files]
read_roots = ["~/projects/infra", "/etc/myapp"]

Approval settings

Key	Default	Meaning
method	auto	auto: strongest available, falling back if allowed. native: strong methods only. cli: approve from a terminal
ttl_secs	0	Remember an approval for a byte-identical request for this many seconds. 0 asks every time
timeout_secs	120	Deny if nobody answers in time
allow_weak	true	Allow non-authenticating methods when no strong one is available

See Approvals for what each method does.