config.example.toml

# chrome-cdp persistent defaults.
#
# Copy this to $XDG_CONFIG_HOME/chrome-cdp/config.toml
# (usually ~/.config/chrome-cdp/config.toml) and uncomment what you want.
#
# Precedence, highest first:
#   command-line flags  >  CHROME_CDP_* env vars  >  this file  >  built-in defaults
#
# Every key is optional; omit any you don't want to override.

# Output + connection defaults
# target = "url:github" # default tab when neither --target nor `use` is set
# json = false          # emit the machine-readable JSON envelope by default
# timeout = "30s"       # max time to wait per command (Go duration string)
# consent_timeout = "120s" # how long to hold the connection open waiting for Chrome's
#                       # browser-modal "Allow remote debugging?" prompt to be answered.
#                       # Only an OPEN port whose upgrade is hanging waits this long; a
#                       # refused endpoint still fails in milliseconds. Shorten it if you
#                       # only ever launch Chrome with --remote-debugging-port (which
#                       # never prompts); lengthen it if the dialog tends to hide behind
#                       # the window and you want more time to find it.
#                       # Clamped to 1s-10m. "0s" (or a negative value) means the 120s
#                       # default, not "do not wait" — a zero wait abandons the prompt
#                       # the instant it is raised, which is the failure this setting
#                       # exists to prevent. The ceiling is there because this is also
#                       # how long a second command can be held up behind the first.
# no_launch = false     # never auto-launch a managed fallback Chrome
# no_daemon = false     # connect directly instead of via the shared daemon
# no_color = false      # plain, symbol-free human output
# port = 0              # explicit Chrome debug port (0 = auto-discover)
# endpoint = ""         # explicit debug endpoint: ws://host:port/devtools/browser/<id>
#                       # or http://host:port (no wss:// or https:// — TLS endpoints are
#                       # not supported). Wins over port and the DevToolsActivePort file —
#                       # use it to reach a Chrome this tool cannot discover on its own (a
#                       # container, an SSH-forwarded port, another machine).
# session = ""          # namespace the sticky current tab (env CHROME_CDP_SESSION), so
#                       # several agents can share one Chrome without stealing each
#                       # other's current tab. Must match ^[A-Za-z0-9._-]{1,64}$; a
#                       # malformed value here is dropped, like a malformed endpoint.
#                       # Does NOT namespace the daemon connection or its console/net
#                       # event buffers — those are shared across sessions by design.
# profile_dir = ""      # managed-launch Chrome profile directory
# browser_bin = ""      # binary the managed-launch fallback execs instead of Chrome
#                       # (env CHROME_CDP_BROWSER_BIN). No --browser-bin flag; Chrome,
#                       # Chromium, Brave, Edge, Vivaldi, and (macOS) Arc are found
#                       # automatically if already debug-enabled — this only matters
#                       # when none is and a managed Chrome would otherwise be launched.

# Selector defaults
# by = "css"            # selector syntax: css | id | search | jspath | css-all
# wait = "visible"      # wait condition: visible | ready | enabled

# Domain policy — bounds which origins chrome-cdp may act on.
#
# Off unless this table exists; with no [policy] table nothing changes. It
# bounds a COOPERATIVE caller (a confused agent, an unread recipe) and is not a
# sandbox: anything that can run chrome-cdp can also edit this file.
#
# Unlike every other key here, a [policy] table the CLI cannot parse is FATAL —
# it refuses to act rather than act unbounded. Run `chrome-cdp policy init` to
# generate a starting point from the tab you are on.
#
# Patterns are [scheme://]host[:port], matched on the parsed URL's host:
#   example.com     exactly that host, any scheme or port
#   *.example.com   any subdomain — but NOT example.com itself, EXCEPT in `deny`,
#                   where the wildcard covers the apex too (over-blocking is the
#                   safe direction in a list of what may never be touched)
#   localhost:*     that host on any port
#   https://x.test  only over https
#
# `eval` and `raw` can navigate the tab themselves, so an allow-list bounds where
# the CLI can go only while those two are denied. Deny them unless you need them.
#
# [policy]
# enabled = true
# allow = ["*.workday.com", "localhost:*"]  # empty = everything except `deny`
# deny = ["*.bank.example"]                 # always refused, bank.example included; beats `allow`
# read_only = ["*.wikipedia.org"]           # reads permitted, actions refused
# verbs_denied = ["eval", "raw"]            # refused on every origin
# upload_roots = ["~/Documents/receipts"]   # directories files may be uploaded from
# audit_log = "~/.local/state/chrome-cdp/audit.log"  # NDJSON; never records values
# audit_all = false                         # also log permitted actions
# on_violation = "error"                    # error | prompt (prompt refuses when there is no TTY)
# Event-capture bounds (read by the connection holder, so they take effect on
# the next `daemon start`; there is no per-command flag for them)
# console_buffer = 1000    # console messages retained per tab (`console` reports evictions as `dropped`)
# console_max_entry = 8192 # per-message text cap, in bytes
# net_buffer = 500         # network records retained per tab (`net` reports evictions as `dropped`)
# net_max_body = 65536     # per-body cap in bytes, for `net --body`
# record_buffer = 600          # frames retained per tab by `record` (evictions are reported as dropped_frames)
# record_max_bytes = 100663296 # retained frame bytes per tab; a frame count alone does not bound memory on a large viewport