Configuration

The ravix daemon reads a YAML config file at:

• macOS: ~/.ravix/config.yaml
• Linux: $XDG_CONFIG_HOME/ravix/config.yaml (fallback ~/.ravix/config.yaml)

ravix onboard writes a default one for you. This page is the full reference for editing it by hand.

The config has two top-level keys: daemon and rules.

daemon

Runtime settings for the polling loop and file output.

Key	Default	Description
poll_interval	10s	How often to poll the Ravi API for new messages.
root_dir	~/.ravix	Agent home. claude-run writes per-thread logs under <root_dir>/run_history/<to>/<thread>/<id>.log. write-to-file paths rendered by rule templates must resolve inside this directory.
state_db	~/.ravix/state.db	Path to the bbolt state database — processed-message ledger plus poll cursors.
log_level	info	One of debug, info, warn, error.

rules

A list of {name, match, action} tuples evaluated top-to-bottom. First match wins. A rule with no match fields matches everything.

match

Field	Type	Matches against
to	glob	The Ravi inbox that received the message.
from	glob or list of globs	The sender's email address.
subject_regex	RE2 regex	The message subject.
thread_id	string	Exact match on the raw Message-ID header.

All non-empty fields must match for the rule to fire.

The daemon pre-filters to direction == "incoming" before evaluating rules, so outbound messages never trigger handlers.

action

An action has a type and optional params.

claude-run

Executes claude --session-id <uuid> --dangerously-skip-permissions --print with the email piped to stdin. cwd = $HOME, no --add-dir restriction. Combined stdout+stderr is written to <root_dir>/run_history/<to>/<thread>/<id>.log.

The session id is a deterministic UUIDv5 derived from the email thread id, so a thread maps 1:1 to a Claude session. Follow-up replies resume the same conversation.

Param	Type	Default	Description
binary	string	auto-detected	Path to claude. Baked in by onboard because service-manager PATH is stripped.
prompt	string	built-in template	Override the default instructions sent to Claude.
timeout	duration	10m	Max wall-clock for the Claude invocation.

write-to-file

Renders the event into a runnable shell script on disk — a preview of what claude-run would do. Useful for debugging rules without burning tokens.

Param	Type	Description
path	Go text/template	File path to write. Must resolve inside root_dir.

Event fields available to the template:

Field	Description
{{.To}}	Recipient (your inbox).
{{.From}}	Sender.
{{.Subject}}	Subject line.
{{.Body}}	Message body.
{{.ID}}	Monotonic integer message id — preferred for filenames.
{{.MessageIDHdr}}	RFC 2822 Message-ID header. Display only; contains <>@+.
{{.ThreadID}}	Raw thread id (contains <>@+).
{{.ThreadIDSafe}}	Thread id sanitized for filesystem use.
{{.RootDir}}	The configured daemon.root_dir.
{{.ReceivedAt}}	time.Time for the message's created_dt.

Example config

daemon:
  poll_interval: 10s
  log_level: info

rules:
  # Scoped claude-run: only our own email can trigger it.
  - name: claude-run
    match:
      to: "jake-agent@raviapp.com"
      from:
        - "jake@ravi.id"
    action:
      type: claude-run

  # Preview mode for everyone else — renders the invocation without executing.
  - name: preview
    match:
      to: "jake-agent@raviapp.com"
    action:
      type: write-to-file
      params:
        path: "{{.RootDir}}/inbox/{{.To}}/{{.ThreadIDSafe}}/{{.ID}}.sh"

Applying changes

Config is read at daemon start, so:

ravix daemon stop
$EDITOR ~/.ravix/config.yaml
ravix daemon start
ravix daemon logs -f

There's no SIGHUP reload in v1.

Trusted senders shortcut

Adding senders to the from allowlist for the default claude-run rule has a CLI shortcut:

ravix trust alice@example.com

This edits ~/.ravix/config.yaml in place. Restart the daemon to pick up the change.