Configuration Reference¶

Complete reference for the agentwatch configuration file.

Overview¶

agentwatch uses a YAML configuration file, typically located at ~/.config/agentwatch/config.yaml.

Generating Configuration¶

# Generate default config
agentwatch --generate-config > ~/.config/agentwatch/config.yaml

# View current config
agentwatch config show

The update channel is not in this file. The self-update channel (stable/unstable) is a gateway-only setting in the gateway config (gateway.yaml), not this per-user config.yaml. Per-user daemons follow the gateway's channel and have no channel of their own. See Architecture & Installation.

Full Configuration¶

# =============================================================================
# Logging
# =============================================================================
logging:
  # Log level: DEBUG, INFO, WARNING, ERROR
  log_level: INFO

  # Log file path (null = stderr only)
  log_file: ~/.cache/agentwatch/daemon.log

  # Max log file size before rotation (MB)
  log_rotate_max_mb: 10

  # Number of rotated log files to keep
  log_rotate_backup_count: 9

# =============================================================================
# Service Settings
# =============================================================================
service:
  # How often to scan for new/removed tmux sessions (seconds)
  session_discovery_interval: 5

  # How often to capture each session's terminal (seconds)
  capture_interval: 1

  # tmux socket path (null = default socket)
  tmux_socket: null

  # Path to tmux binary
  tmux_bin: tmux

  # Debug settings
  debug:
    # Enable debug mode
    enabled: false

    # Directory for capture files (null = disabled)
    capture_dir: null

    # Auto-cleanup captures older than this (hours)
    retention_hours: 4.0

    # Log each capture
    log_captures: false

    # Log detection results
    log_detections: false

    # Log state changes (recommended for debugging)
    log_state_changes: true

    # Log hook executions
    log_hooks: true

    # Dry run mode - log hooks without executing
    dry_run_hooks: false

# =============================================================================
# Web Viewer (HTTPS Server)
# =============================================================================
web_viewer:
  # Enable/disable web viewer
  enabled: true

  # Host to bind (127.0.0.1 = localhost only)
  host: 127.0.0.1

  # Port to listen on
  port: 8081

  # Terminal streaming frame rate
  fps: 2.0

  # Max keyboard input messages per second
  max_input_rate: 20

  # Custom SSL certificate (optional)
  ssl_cert: null
  ssl_key: null

# =============================================================================
# Tunnel (agentwatch.sh)
# =============================================================================
tunnel:
  # Enable auto-provisioned tunnel
  # Requires device token in ~/.config/agentwatch/tokens/device
  enabled: false

# =============================================================================
# Cloudflare Tunnel (Manual)
# =============================================================================
cloudflare:
  # Enable manual Cloudflare tunnel
  enabled: false

  # Path to cloudflared config file
  config_file: ~/.cloudflared/config-agentwatch.yml

  # Path to cloudflared binary
  cloudflared_bin: cloudflared

# =============================================================================
# Coding Sessions
# =============================================================================
sessions:
  # Enable coding session management
  enabled: true

  # Prefix for auto-generated session names
  session_prefix: coding-

  # Maximum concurrent coding sessions
  max_sessions: 3

  # Default lines to capture for session capture
  capture_lines: 50

  # Allowed working directories for coding sessions
  # Sessions can only be created under these paths
  allowed_workdirs:
    - "~"         # Home directory
    - "/tmp"      # Temporary files
    - "/var/tmp"  # Persistent temp

# =============================================================================
# Hooks
# =============================================================================
hooks:
  # Webhook example
  - name: my-webhook
    type: webhook
    trigger: state_change
    programs: ["Claude Code"]
    to_states: [Error, Blocked]
    url: "https://example.com/webhook"
    include: status
    timeout_seconds: 10
    retry_count: 0
    retry_delay_seconds: 1.0

  # Shell example
  - name: my-shell
    type: shell
    trigger: state_change
    to_states: [Idle]
    command: 'echo "$SESSION_NAME finished" >> ~/agentwatch.log'
    include: status

Section Reference¶

logging¶

Key	Type	Default	Description
`log_level`	string	`INFO`	Log level: DEBUG, INFO, WARNING, ERROR
`log_file`	string	`~/.cache/agentwatch/daemon.log`	Log file path (null = stderr only)
`log_rotate_max_mb`	number	`10`	Max log file size (MB)
`log_rotate_backup_count`	number	`9`	Rotated files to keep

service¶

Key	Type	Default	Description
`session_discovery_interval`	number	`5`	Session scan interval (seconds)
`capture_interval`	number	`1`	Capture interval per session (seconds)
`tmux_socket`	string	`null`	tmux socket path
`tmux_bin`	string	`tmux`	Path to tmux binary

service.debug¶

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable debug mode
`capture_dir`	string	`null`	Directory for capture files
`retention_hours`	number	`4.0`	Capture cleanup age (hours)
`log_captures`	boolean	`false`	Log each capture
`log_detections`	boolean	`false`	Log detection results
`log_state_changes`	boolean	`true`	Log state changes
`log_hooks`	boolean	`true`	Log hook executions
`dry_run_hooks`	boolean	`false`	Log hooks without executing

web_viewer¶

Key	Type	Default	Description
`enabled`	boolean	`true`	Enable web viewer
`host`	string	`127.0.0.1`	Bind address
`port`	number	`8081`	Port number
`fps`	number	`2.0`	Streaming frame rate
`max_input_rate`	number	`20`	Max input messages/sec
`ssl_cert`	string	`null`	Custom SSL certificate path
`ssl_key`	string	`null`	Custom SSL key path

tunnel¶

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable auto-provisioned tunnel

The device token is stored at ~/.config/agentwatch/tokens/device.

cloudflare¶

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable manual Cloudflare tunnel
`config_file`	string	`~/.cloudflared/config-agentwatch.yml`	Cloudflared config path
`cloudflared_bin`	string	`cloudflared`	Path to cloudflared

sessions¶

Key	Type	Default	Description
`enabled`	boolean	`true`	Enable coding session management
`session_prefix`	string	`coding-`	Auto-generated session name prefix
`max_sessions`	number	`3`	Max concurrent sessions
`capture_lines`	number	`50`	Default capture lines
`allowed_workdirs`	list	`["~", "/tmp", "/var/tmp"]`	Allowed working directories

hooks¶

List of hook definitions. Each hook has:

Key	Type	Required	Description
`name`	string	Yes	Unique identifier
`type`	string	Yes	`webhook` or `shell`
`trigger`	string	Yes	`state_change`, `program_change`, `any_change`
`programs`	list	No	Filter: current program must match
`states`	list	No	Filter: current state must match
`from_states`	list	No	Filter: previous state must match
`to_states`	list	No	Filter: target state must match
`from_programs`	list	No	Filter: previous program must match
`to_programs`	list	No	Filter: target program must match
`include`	string	No	Data format: `status`, `json`, `text`, `png`

Webhook-specific:

Key	Type	Default	Description
`url`	string	Required	Webhook URL
`timeout_seconds`	number	`10`	Request timeout
`retry_count`	number	`0`	Retry attempts
`retry_delay_seconds`	number	`1.0`	Delay between retries

Shell-specific:

Key	Type	Default	Description
`command`	string	Required	Shell command

Environment Variables¶

These override configuration values:

Variable	Overrides
`AGENT_WATCH_SOCKET`	`service.tmux_socket`
`AGENT_WATCH_TARGET`	Target pane
`AGENT_WATCH_COLS`	One-shot capture/render width
`AGENT_WATCH_ROWS`	One-shot capture/render height
`AGENT_WATCH_FORMAT`	Output format
`AGENT_WATCH_SESSION_SECRET`	Session signing key
`AGENTWATCH_TOKEN`	Device token

SSL Certificates¶

Certificates are used in this priority:

Tunnel certificate - Auto-provisioned for *.agentwatch.sh
Custom certificate - From ssl_cert/ssl_key config
Auto-generated - Self-signed localhost certificate

Auto-generated Certificates¶

On first start, if no certificates are configured, a self-signed localhost certificate is generated automatically.

Custom Certificates¶

web_viewer:
  ssl_cert: /path/to/cert.pem
  ssl_key: /path/to/key.pem

Tunnel Certificates¶

When using the auto-provisioned tunnel, Cloudflare origin certificates are fetched automatically and stored at ~/.config/agentwatch/certs/.

Hook Shell Environment¶

Shell hooks receive these environment variables:

Variable	Description
`SESSION_NAME`	tmux session name
`SESSION_ID`	tmux session ID
`PROGRAM`	Current program
`PROGRAM_VERSION`	Version (if detected)
`STATE`	Current state
`DETAIL`	State detail
`PREVIOUS_PROGRAM`	Previous program
`PREVIOUS_STATE`	Previous state
`PREVIOUS_DETAIL`	Previous detail
`TIMESTAMP`	ISO timestamp
`DURATION_SECONDS`	Time in previous state
`CAPTURE_FILE`	Capture file path (if `include: text/png`)
`AGENTWATCH_TRIGGER`	Trigger type

Example Configurations¶

Minimal¶

web_viewer:
  enabled: true

sessions:
  enabled: true

With Desktop Notifications¶

hooks:
  - name: desktop-notify
    type: shell
    trigger: state_change
    to_states: [Blocked, Error, Idle]
    command: 'notify-send "agentwatch" "$SESSION_NAME: $STATE"'

With Remote Access¶

tunnel:
  enabled: true

hooks:
  - name: slack-notify
    type: webhook
    trigger: state_change
    to_states: [Error]
    url: "https://hooks.slack.com/services/..."

Debug Mode¶

logging:
  log_level: DEBUG

service:
  debug:
    enabled: true
    capture_dir: ~/.cache/agentwatch/captures
    log_state_changes: true
    log_hooks: true