Spec reference

Generated from the Go structs by make schema; the JSON Schema is hikyaku.schema.json. Point your editor at it with # yaml-language-server: $schema=https://xavidop.github.io/hikyaku/schema/hikyaku.schema.json.

Durations read like 500ms, 30s, 5m, 1h, 7d; sizes like 512, 8KiB, 10MB. {{secrets.NAME}} and {{env.NAME}} are replaced when the spec loads; {{ .json.x }} templates run per message.

Top level (`hikyaku.yaml`)

Key	Type	Description
`version` (required)	integer	Spec format version. Always 1. One of `1`.
`name` (required)	string	Relay name. Used in metrics, logs and the shared-state keys.
`secrets`	map of string	Secrets by name, each a mamori ref (env:NAME, file:///path, vault://…, or a comma-separated chain tried in order, such as env:A,file:///run/a). Reference one as {{secrets.NAME}}.
`genkit`	Genkit	Genkit plugins for the AI router.
`models`	Models	Default models, model retries and model fallback chains.
`defaults`	Policy	Delivery policy inherited by every destination (each field on its own).
`sources` (required)	Source[]	Where messages come from.
`destinations` (required)	Destination[]	Where messages go.
`stores`	Store[]	Shared-state backends (history, decision cache, dedupe, idempotency, budgets), referenced by name. The first one is the default store; with none, an in-process memory store is used.
`dead_letter`	DeadLetter	Where a message goes when a required destination and all its fallbacks failed. Defaults to stderr.
`routes` (required)	Route[]	Which destinations get the messages of which sources.
`server`	Server	Admin API, workers and shutdown.
`observability`	Observability	Logs, OpenTelemetry traces and Prometheus metrics.
`buffer`	Buffer	The queue between sources and delivery workers.
`egress`	Egress	SSRF guard for destinations whose URL host is a per-message template.
`plugins`	PluginBinary[]	Out-of-process plugins: binaries hikyaku starts and talks gRPC to. Each one adds the source and destination types it declares.
`notify`	Notify[]	Alerts: a message sent to a destination when a message is dead-lettered or a circuit breaker changes.

`Source`

Key	Type	Description
`name` (required)	string	Unique source name.
`type` (required)	string	Protocol: http, https, ws, wss, sse, stdin, file (M1); see the protocol matrix for the rest.
`mode`	string	listen (hikyaku is the server), poll (pull on a schedule) or subscribe (long-lived client). Defaults per protocol. One of `listen`, `poll`, `subscribe`.
`listen`	string	listen: address, such as :8080.
`path`	string	listen: request path (default /); file: the file to read.
`methods`	string[]	http listen: accepted methods (default POST, PUT).
`tls`	TLS	TLS (and mTLS with client_ca_file) for listen, DTLS for udp; client TLS for poll and subscribe.
`auth`	Auth	Inbound authentication of listen sources.
`ack`	string	delivered (default) or accepted. http and grpc listen: delivered answers once the message is delivered or dead-lettered, accepted as soon as it is queued (on disk with a disk buffer). Subscribe sources: delivered acknowledges the broker once the outcome is final, accepted once the message is queued (safe with buffer.type: disk only). One of `delivered`, `accepted`.
`respond`	Respond	http and grpc listen: send a destination’s reply back to the caller (smart reverse proxy; grpc maps it into the method’s output type).
`max_body_bytes`	Size	Largest accepted message (default 10MiB; grpc and openai 4MiB; tcp, udp and mqtt 1MiB). A listen source refuses a larger one (http 413, grpc RESOURCE_EXHAUSTED); a subscribe or poll source logs it and acknowledges it, so it cannot loop forever.
`url`	string	poll or subscribe: the endpoint.
`headers`	map of string	poll or subscribe: request headers.
`oauth2`	OAuth2	http poll: fetch an OAuth 2.0 access token with the client credentials grant and send it as a bearer token on every poll.
`method`	string	poll: request method (default GET).
`body`	string	poll: request body.
`interval`	Duration	poll: time between polls (default 30s).
`timeout`	Duration	poll (http, s3, gcs): per-request timeout (default 10s).
`retry`	Retry	poll (http, s3): retries per poll before skipping to the next interval. gcs retries its reads itself.
`dedupe`	Dedupe	Drop messages whose key was seen within the ttl, on any source (poll dedupe, cross-replica idempotency). A duplicate is acked as filtered and counted in hikyaku_deduped_total.
`split`	string	poll: jq expression that splits one response into several messages, such as .items[]. s3, gcs: also lines, one message per non-empty line of an object (NDJSON).
`reconnect`	Reconnect	subscribe: reconnect policy.
`failover_urls`	string[]	subscribe (ws, wss, sse, grpc, nats, jetstream, mqtt, amqp, redis): URLs rotated through when the primary is down.
`format`	string	stdin and file: each line is a message body (default) or an envelope in wire form. One of `body`, `envelope`.
`follow`	boolean	file: keep reading lines appended to the file.
`brokers`	string[]	kafka: bootstrap brokers (host:port).
`topic`	string	kafka, mqtt: the topic (mqtt: a topic filter); eventhubs: the event hub; servicebus: the topic (with subscription).
`topics`	string[]	kafka, mqtt: several topics (mqtt: filters) instead of topic.
`group`	string	kafka, redis streams, eventhubs: consumer group; mqtt v5: shared subscription group ($share//).
`start`	string	Where a new consumer starts. kafka, redis streams, eventhubs: earliest or latest (default latest); jetstream: all, new (default) or last. One of `earliest`, `latest`, `all`, `new`, `last`.
`sasl`	SASL	kafka: SASL authentication.
`username`	string	mqtt, nats, redis, amqp: user name (mqtt, amqp and redis also take it in the URL; this field wins).
`password`	string	mqtt, nats, redis, amqp, smtp: password; use {{secrets.X}}.
`token`	string	nats: authentication token; use {{secrets.X}}.
`creds_file`	string	nats: a .creds file (JWT and NKey seed).
`subject`	string	nats: subject (wildcards * and > allowed); jetstream: filter subject of the consumer.
`queue`	string	nats: queue group (members share the messages); amqp: the queue consumed; servicebus: the queue.
`prefetch`	integer	Messages a subscribe source keeps in flight: amqp prefetch, jetstream max_ack_pending, redis streams entries read and not acknowledged, kafka records buffered, mqtt v5 receive maximum, pubsub max outstanding, servicebus prefetch (default 64); nats: messages buffered before the client drops them (default 65536). sqs: messages per receive, 1 to 10 (default 10).
`ack_wait`	Duration	jetstream: redelivery delay of an unacknowledged message; redis streams: how long a pending entry stays idle before it is reclaimed and delivered again (default 30s for both).
`stream`	string	jetstream: the stream; redis: the stream key (XREADGROUP).
`consumer`	string	redis streams: this consumer’s name in the group (default -); keep it stable, a restart resumes the entries it left pending.
`durable`	string	jetstream: durable consumer name, so a restart resumes where it stopped (default the source name).
`channel`	string	redis pub/sub: channel, or a pattern with * (PSUBSCRIBE).
`qos`	integer	mqtt: subscription QoS (default 1). One of `0`, `1`, `2`.
`client_id`	string	mqtt: client identifier, which keys a persistent session; kafka: client.id. Default hikyaku--.
`clean_session`	boolean	mqtt: start a clean session (default false: the broker keeps the session and queued QoS 1/2 messages across reconnects).
`protocol_version`	string	mqtt: protocol version (default 5). One of `3.1.1`, `5`.
`exchange`	string	amqp: exchange the queue is bound to (with routing_key).
`routing_key`	string	amqp: binding key of the queue on exchange.
`declare`	boolean	amqp: declare the queue (durable) and its binding when missing.
`descriptor_set`	string	grpc: a FileDescriptorSet file (protoc —descriptor_set_out —include_imports) describing the services.
`services`	string[]	grpc listen: the services of descriptor_set to serve (default all); hikyaku.relay.v1.Relay is always served.
`reflection`	boolean	grpc listen: serve the reflection service (default true); subscribe: resolve method through server reflection when there is no descriptor_set (default true).
`frame`	string	tcp, udp: framing. newline (default): one message per line; length: each message after a length_bytes big-endian length; raw: tcp, a connection’s whole stream; udp, each datagram. One of `newline`, `length`, `raw`.
`length_bytes`	integer	tcp, udp: size of the length prefix with frame: length (default 4). One of `1`, `2`, `4`, `8`.
`queue_url`	string	sqs: the queue URL. sns, eventbridge: the SQS queue subscribed to the topic or rule.
`wait_time`	Duration	sqs: long-poll wait (default 20s, at most 20s).
`visibility_timeout`	Duration	sqs: how long a received message stays hidden (default the queue’s).
`bucket`	string	s3, gcs: the bucket polled.
`prefix`	string	s3, gcs: only objects under this prefix.
`after`	string	s3, gcs: what happens to an object once its messages are final: keep (remembered in state_store), delete (default) or move (to move_to). One of `keep`, `delete`, `move`.
`move_to`	string	s3, gcs: prefix objects are moved under with after: move.
`state_store`	string	Store (by name) that keeps a source’s progress: eventhubs checkpoints, s3/gcs objects already read with after: keep. Default the first store.
`subscription`	string	pubsub: the subscription; servicebus: the topic subscription.
`aws`	AWS	sqs, sns, eventbridge, s3: AWS region and credentials (default the SDK’s chain).
`gcp`	GCP	pubsub, gcs: project and credentials (default Application Default Credentials).
`azure`	Azure	servicebus, eventhubs: connection string or namespace and credentials.
`models`	string[]	openai: the model names /v1/models lists and clients may ask for (default [hikyaku]); route on msg.json.model.
`cron`	string	schedule: when to emit a message, as a five-field cron expression (minute hour day-of-month month day-of-week) or @hourly, @daily, @weekly, @monthly, @yearly. Set cron or interval.
`timezone`	string	schedule: the time zone cron is read in, such as Europe/Madrid (default UTC).
`ordering`	Ordering	Deliver messages with the same key one at a time, in arrival order.
`options`	object	Settings of a plugin type (a source registered by a custom build); the plugin decodes and validates them.

`Destination`

Key	Type	Description
`name` (required)	string	Unique destination name.
`type` (required)	string	Protocol: http, https, ws, wss, sse, stdout, stderr, file, fault, group, grpc, tcp, udp, kafka, nats, jetstream, mqtt, amqp, redis, sqs, sns, eventbridge, s3, pubsub, gcs, servicebus, eventhubs, model, or a plugin’s type.
`url`	string	http/ws: target URL, which may contain per-message templates (hosts are checked against egress). grpc: grpc://host:port or grpcs://; tcp: tcp://host:port or tls://; udp: udp://host:port or dtls://; nats, mqtt, amqp, redis: the server URL.
`method`	string	http: method (default POST); grpc: full method name, /package.Service/Method.
`headers`	map of string	Headers set on every request; values may be per-message templates.
`body`	string	Per-message template of the outgoing body (default: the message body).
`tls`	TLS	Client TLS, DTLS for udp (mTLS with cert_file and key_file).
`sign`	Sign	http: sign every request with an HMAC of its body, so the receiver can check who sent it.
`from`	string	smtp: the sender, as an address or as Name .
`to`	string[]	smtp: the recipients. Each entry is a per-message template that renders one address, or several separated by commas.
`oauth2`	OAuth2	http: fetch an OAuth 2.0 access token with the client credentials grant and send it as a bearer token.
`path`	string	file: the file appended to; sse: the stream path (default /).
`listen`	string	sse: address the event stream is served on.
`format`	string	file/stdout/stderr: write each message as an envelope line (default) or its body. One of `envelope`, `body`.
`frame`	string	ws: frame type, text (default) or binary. tcp, udp: framing, newline (default), length (a length_bytes big-endian prefix) or raw. One of `text`, `binary`, `newline`, `length`, `raw`.
`event`	string	sse: per-message template of the event name.
`replay`	integer	sse: events kept for Last-Event-ID resume (default 1000).
`auth`	Auth	sse: authentication of the clients that read the stream: bearer, api_key, jwt, ip_allow (401 on failure; hmac does not apply).
`fault`	Fault	fault: the faults injected (local testing and the resilience suite).
`brokers`	string[]	kafka: bootstrap brokers (host:port).
`topic`	string	Per-message template of the topic. kafka, mqtt, pubsub: the topic; sns: the topic ARN; eventhubs: the event hub; servicebus: the topic.
`key`	string	Per-message template of the message key. kafka: record key (partitioning); pubsub: ordering key; eventhubs: partition key; s3, gcs: object key (default //.json, or .ndjson for a batch).
`sasl`	SASL	kafka: SASL authentication.
`username`	string	mqtt, nats, redis, amqp, smtp: user name.
`password`	string	mqtt, nats, redis, amqp, smtp: password; use {{secrets.X}}.
`token`	string	nats: authentication token; use {{secrets.X}}.
`creds_file`	string	nats: a .creds file (JWT and NKey seed).
`subject`	string	Per-message template of the subject. nats, jetstream: the subject published to; sns: the message subject; smtp: the email’s subject.
`acks`	string	kafka: acknowledgements a produce waits for (default all, with the idempotent producer). One of `all`, `leader`, `none`.
`compression`	string	kafka: batch compression (default none). http: gzip compresses the request body and sets Content-Encoding (default none). One of `none`, `gzip`, `snappy`, `lz4`, `zstd`.
`qos`	integer	mqtt: publish QoS (default 1). One of `0`, `1`, `2`.
`retain`	boolean	mqtt: publish retained messages.
`client_id`	string	mqtt: client identifier; kafka: client.id. Default hikyaku--.
`protocol_version`	string	mqtt: protocol version (default 5). One of `3.1.1`, `5`.
`exchange`	string	amqp: exchange published to (default the default exchange, which routes by queue name).
`routing_key`	string	amqp: per-message template of the routing key.
`persistent`	boolean	amqp: persistent delivery mode (default true).
`mandatory`	boolean	amqp: fail a message no queue is bound to receive (a permanent error) instead of dropping it.
`declare`	boolean	amqp: declare the exchange (topic, durable) when missing.
`stream`	string	redis: stream key appended to (XADD); jetstream: the stream a publish must land in (an expected-stream check).
`channel`	string	redis: pub/sub channel published to; a per-message template.
`max_len`	integer	redis streams: approximate length the stream is trimmed to (MAXLEN ~).
`descriptor_set`	string	grpc: a FileDescriptorSet file describing method’s service.
`reflection`	boolean	grpc: resolve method through server reflection when there is no descriptor_set (default true).
`length_bytes`	integer	tcp, udp: size of the length prefix with frame: length (default 4). One of `1`, `2`, `4`, `8`.
`queue_url`	string	sqs: the queue URL.
`group_id`	string	Per-message template of the ordering group. sqs, sns FIFO: message group ID; servicebus: session ID.
`delay`	Duration	sqs: delivery delay (at most 15m).
`event_bus`	string	eventbridge: event bus name or ARN (default the account’s default bus).
`event_source`	string	eventbridge: the events’ source field (default hikyaku.).
`detail_type`	string	eventbridge: per-message template of the detail-type (default the message subject, else hikyaku.message).
`bucket`	string	s3, gcs: the bucket written to.
`content_type`	string	s3, gcs: the objects’ content type (default the message’s).
`queue`	string	servicebus: the queue (or topic).
`aws`	AWS	sqs, sns, eventbridge, s3: AWS region and credentials (default the SDK’s chain).
`gcp`	GCP	pubsub, gcs: project and credentials (default Application Default Credentials).
`azure`	Azure	servicebus, eventhubs: connection string or namespace and credentials.
`model`	string	model: the Genkit model that answers, provider/name (googleai/gemini-2.5-flash, openai/gpt-4o-mini, openrouter/anthropic/claude-sonnet-4.5, ollama/llama3.2).
`generation`	Generation	model: generation settings applied when the request does not set them.
`options`	object	Settings of a plugin type (a destination registered by a custom build); the plugin decodes and validates them.
`timeout`	Duration	Per-attempt timeout (default 5s).
`deadline`	Duration	Overall budget across attempts and fallbacks (default none).
`retry`	Retry	Retry policy per endpoint.
`circuit_breaker`	CircuitBreaker	Circuit breaker per endpoint.
`retry_budget`	RetryBudget	Caps retries as a fraction of traffic.
`fallback`	string[]	Destinations tried in order after this one exhausts its retries, fails permanently, has its breaker open, its budget spent or its deadline hit.
`required`	boolean	A required destination (default) must succeed, on its primary or a fallback, before the message is acked; a failure goes to the DLQ. A best-effort one is counted and logged.
`idempotent`	boolean	The endpoint dedupes by idempotency key; required for hedging.
`idempotency_header`	string	Header carrying the idempotency key (default Idempotency-Key).
`transforms`	Transform[]	Transforms applied before delivering here.
`strategy`	string	group: how members are picked (default failover). One of `failover`, `round_robin`, `weighted`, `least_latency`.
`members`	Member[]	group: the endpoints.
`health_check`	HealthCheck	group: active health checks; unhealthy members are skipped until they recover.
`hedge`	Hedge	group: race another member when the first is slow (idempotent destinations only).
`deliver_after`	Duration	Hold each message of a route this long before delivering it here, counted from when it was received.
`deliver_at`	string	Per-message template of the time to deliver at, in RFC 3339 (2026-12-24T09:00:00Z). A message it renders empty for follows deliver_after, or goes at once.
`rate_limit`	RateLimit	Send at most this many requests per second; the others wait their turn.
`shadow`	boolean	A shadow destination gets a copy of what the routes send it, on the side: its failures never hold up, fail or dead-letter a message. For trying a new consumer against real traffic.
`sample`	number	shadow: the share of messages copied, from above 0 to 1 (0.05 is 5%; default 1, every message).
`batch`	Batch	Deliver messages in batches: one request (one Kafka produce, one SQS SendMessageBatch, one S3 object, one HTTP body) per batch.

`Member`

Key	Type	Description
`name`	string	Member name (default []).
`weight`	integer	weighted: relative share (default 1).
`type` (required)	string	Protocol: http, https, ws, wss, sse, stdout, stderr, file, fault, group, grpc, tcp, udp, kafka, nats, jetstream, mqtt, amqp, redis, sqs, sns, eventbridge, s3, pubsub, gcs, servicebus, eventhubs, model, or a plugin’s type.
`url`	string	http/ws: target URL, which may contain per-message templates (hosts are checked against egress). grpc: grpc://host:port or grpcs://; tcp: tcp://host:port or tls://; udp: udp://host:port or dtls://; nats, mqtt, amqp, redis: the server URL.
`method`	string	http: method (default POST); grpc: full method name, /package.Service/Method.
`headers`	map of string	Headers set on every request; values may be per-message templates.
`body`	string	Per-message template of the outgoing body (default: the message body).
`tls`	TLS	Client TLS, DTLS for udp (mTLS with cert_file and key_file).
`sign`	Sign	http: sign every request with an HMAC of its body, so the receiver can check who sent it.
`from`	string	smtp: the sender, as an address or as Name .
`to`	string[]	smtp: the recipients. Each entry is a per-message template that renders one address, or several separated by commas.
`oauth2`	OAuth2	http: fetch an OAuth 2.0 access token with the client credentials grant and send it as a bearer token.
`path`	string	file: the file appended to; sse: the stream path (default /).
`listen`	string	sse: address the event stream is served on.
`format`	string	file/stdout/stderr: write each message as an envelope line (default) or its body. One of `envelope`, `body`.
`frame`	string	ws: frame type, text (default) or binary. tcp, udp: framing, newline (default), length (a length_bytes big-endian prefix) or raw. One of `text`, `binary`, `newline`, `length`, `raw`.
`event`	string	sse: per-message template of the event name.
`replay`	integer	sse: events kept for Last-Event-ID resume (default 1000).
`auth`	Auth	sse: authentication of the clients that read the stream: bearer, api_key, jwt, ip_allow (401 on failure; hmac does not apply).
`fault`	Fault	fault: the faults injected (local testing and the resilience suite).
`brokers`	string[]	kafka: bootstrap brokers (host:port).
`topic`	string	Per-message template of the topic. kafka, mqtt, pubsub: the topic; sns: the topic ARN; eventhubs: the event hub; servicebus: the topic.
`key`	string	Per-message template of the message key. kafka: record key (partitioning); pubsub: ordering key; eventhubs: partition key; s3, gcs: object key (default //.json, or .ndjson for a batch).
`sasl`	SASL	kafka: SASL authentication.
`username`	string	mqtt, nats, redis, amqp, smtp: user name.
`password`	string	mqtt, nats, redis, amqp, smtp: password; use {{secrets.X}}.
`token`	string	nats: authentication token; use {{secrets.X}}.
`creds_file`	string	nats: a .creds file (JWT and NKey seed).
`subject`	string	Per-message template of the subject. nats, jetstream: the subject published to; sns: the message subject; smtp: the email’s subject.
`acks`	string	kafka: acknowledgements a produce waits for (default all, with the idempotent producer). One of `all`, `leader`, `none`.
`compression`	string	kafka: batch compression (default none). http: gzip compresses the request body and sets Content-Encoding (default none). One of `none`, `gzip`, `snappy`, `lz4`, `zstd`.
`qos`	integer	mqtt: publish QoS (default 1). One of `0`, `1`, `2`.
`retain`	boolean	mqtt: publish retained messages.
`client_id`	string	mqtt: client identifier; kafka: client.id. Default hikyaku--.
`protocol_version`	string	mqtt: protocol version (default 5). One of `3.1.1`, `5`.
`exchange`	string	amqp: exchange published to (default the default exchange, which routes by queue name).
`routing_key`	string	amqp: per-message template of the routing key.
`persistent`	boolean	amqp: persistent delivery mode (default true).
`mandatory`	boolean	amqp: fail a message no queue is bound to receive (a permanent error) instead of dropping it.
`declare`	boolean	amqp: declare the exchange (topic, durable) when missing.
`stream`	string	redis: stream key appended to (XADD); jetstream: the stream a publish must land in (an expected-stream check).
`channel`	string	redis: pub/sub channel published to; a per-message template.
`max_len`	integer	redis streams: approximate length the stream is trimmed to (MAXLEN ~).
`descriptor_set`	string	grpc: a FileDescriptorSet file describing method’s service.
`reflection`	boolean	grpc: resolve method through server reflection when there is no descriptor_set (default true).
`length_bytes`	integer	tcp, udp: size of the length prefix with frame: length (default 4). One of `1`, `2`, `4`, `8`.
`queue_url`	string	sqs: the queue URL.
`group_id`	string	Per-message template of the ordering group. sqs, sns FIFO: message group ID; servicebus: session ID.
`delay`	Duration	sqs: delivery delay (at most 15m).
`event_bus`	string	eventbridge: event bus name or ARN (default the account’s default bus).
`event_source`	string	eventbridge: the events’ source field (default hikyaku.).
`detail_type`	string	eventbridge: per-message template of the detail-type (default the message subject, else hikyaku.message).
`bucket`	string	s3, gcs: the bucket written to.
`content_type`	string	s3, gcs: the objects’ content type (default the message’s).
`queue`	string	servicebus: the queue (or topic).
`aws`	AWS	sqs, sns, eventbridge, s3: AWS region and credentials (default the SDK’s chain).
`gcp`	GCP	pubsub, gcs: project and credentials (default Application Default Credentials).
`azure`	Azure	servicebus, eventhubs: connection string or namespace and credentials.
`model`	string	model: the Genkit model that answers, provider/name (googleai/gemini-2.5-flash, openai/gpt-4o-mini, openrouter/anthropic/claude-sonnet-4.5, ollama/llama3.2).
`generation`	Generation	model: generation settings applied when the request does not set them.
`options`	object	Settings of a plugin type (a destination registered by a custom build); the plugin decodes and validates them.

`Policy`

Key	Type	Description
`timeout`	Duration	Per-attempt timeout (default 5s).
`deadline`	Duration	Overall budget across attempts and fallbacks (default none).
`retry`	Retry	Retry policy per endpoint.
`circuit_breaker`	CircuitBreaker	Circuit breaker per endpoint.
`retry_budget`	RetryBudget	Caps retries as a fraction of traffic.

`Retry`

Key	Type	Description
`attempts`	integer	Tries per endpoint; 1 means no retry (default 5).
`backoff`	Duration	Base wait, doubled per try (default 200ms).
`max_backoff`	Duration	Cap on the wait (default 10s).
`jitter`	string	full (default): random in [0, wait]; equal: wait/2 + random half; none. One of `full`, `equal`, `none`.
`retry_on`	TagList	Error tags retried (default connect, timeout, 5xx, 429): ranges (5xx), codes (503), classes (connect, timeout) and protocol codes (ws:close_1011).
`never_on`	TagList	Error tags never retried (default 4xx). A more specific retry_on tag wins, so 429 and 408 still retry.
`respect_retry_after`	boolean	Wait what Retry-After (or a broker hint) says, capped by max_backoff (default true).

`CircuitBreaker`

Key	Type	Description
`enabled`	boolean	Default true.
`failure_ratio`	number	Open when failures/requests in the window reach this (default 0.5).
`min_requests`	integer	Requests in the window before the ratio counts (default 20).
`open_for`	Duration	How long the breaker stays open (default 30s).
`half_open_max`	integer	Trial requests while half-open (default 5).
`window`	Duration	Rolling window of the failure ratio (default 60s).

`RetryBudget`

Key	Type	Description
`enabled`	boolean	Default true.
`ratio`	number	Retries allowed per first attempt in the window (default 0.2).
`min_per_second`	number	Retries always allowed per second (default 10).
`store`	string	Store that shares the counters across replicas (default: in-process).

`Route`

Key	Type	Description
`name` (required)	string	Unique route name.
`from` (required)	string[]	Source names.
`to`	string[]	Shortcut for a static router.
`filter`	string	CEL expression over msg; false skips the route.
`transforms`	Transform[]	Transforms applied before routing.
`router`	RouterSpec	The router; default static over to:.

`RouterSpec`

Key	Type	Description
`type` (required)	string	static, rules (CEL), ai, or sticky (last destinations of the history key). One of `static`, `rules`, `ai`, `sticky`.
`when`	string	CEL condition over msg: only the messages it is true for reach this router; the others skip it, with no call, and go to the next router of the fallback chain. On an ai router it keeps model spend to the messages that need a model, such as has(msg.json.text), msg.headers[“X-Priority”] == “high” or msg.json.tier == “enterprise”. A condition that cannot be evaluated (a missing field) counts as false.
`to`	string[]	static: destinations.
`rules`	Rule[]	rules: evaluated in order.
`match`	string	rules: first matching rule (default) or every match. One of `first`, `all`.
`default`	string[]	rules: destinations when no rule matches (else the router fails over).
`engine`	string	ai: decision (System One, default) or generative (GenerateData on any model). One of `decision`, `generative`.
`model`	string	ai: model (default models.decision or models.default).
`fallback_models`	string[]	ai: overrides the global model fallback chain.
`instructions`	string	ai: the system message, in front of every question.
`state`	string	ai: per-message template of what the model evaluates (default {{ .bodyText }}).
`state_json`	boolean	ai: the state is JSON (sent as an object).
`candidates`	Candidate[]	ai: the destinations the model may pick, each with what it is for.
`multi`	boolean	ai: true asks one yes/no per candidate (in one request) and delivers to every one above min_confidence; false asks one choice.
`min_confidence`	number	ai: lowest probability accepted.
`min_margin`	number	ai, single choice: top minus second must exceed this.
`input`	AIInput	ai: how the state is built.
`timeout`	Duration	ai: budget of the whole AI step, model fallbacks included (default 10s).
`cache`	Cache	ai: decision cache.
`history`	History	ai and sticky: route with past calls of a key.
`on_low_confidence`	string[]	ai: destinations when the model answered but was not sure.
`fallback_on_low_confidence`	boolean	ai: hand low-confidence answers to the router fallback instead of on_low_confidence.
`shadow`	boolean	ai: decide and log, but deliver through the fallback chain.
`budget`	AIBudget	ai: when exceeded, the route goes straight to the router fallback.
`fallback`	RouterSpec[]	Routers tried in order when this one errors, times out, is over budget or (fallback_on_low_confidence) is unsure.

`Rule`

Key	Type	Description
`when` (required)	string	CEL expression over msg (msg.json, msg.headers, msg.subject, msg.source, …).
`to` (required)	string[]	Destinations when it holds.

`Candidate`

Key	Type	Description
`name` (required)	string	A declared destination.
`description` (required)	string	What it is for: the option’s criteria.

`AIInput`

Key	Type	Description
`max_bytes`	Size	Cap on the whole state, history included (default 8KiB): oldest turns go first.
`redact`	string[]	JSONPaths removed from a JSON state, such as $.card.number.
`headers`	string[]	Headers included in the state (allowlist).

`Cache`

Key	Type	Description
`store`	string	Shared store; default an in-process LRU.
`key`	string	Per-message template of the cache key (default: a hash of the state).
`ttl`	Duration	Default 10m.
`size`	integer	LRU entries (default 10000).

`History`

Key	Type	Description
`store`	string	Store of the history (default store).
`key` (required)	string	Per-message template of whose history: customer, conversation, session, device.
`window`	Window	What is sent to the model.
`ttl` (required)	Duration	How long records are kept. Mandatory.
`record`	HistoryRecord	What is stored.
`sticky`	Sticky	Send follow-ups where the previous call went.
`on_store_error`	string	ignore (default): route without history; fallback: use router.fallback. One of `ignore`, `fallback`.

`Window`

Key	Type	Description
`max_entries`	integer	Newest records sent (default 10).
`max_age`	Duration	Oldest record sent.

`HistoryRecord`

Key	Type	Description
`state`	string	redacted (default): the redacted state; summary: the summary template; none: only decision and outcome. One of `redacted`, `summary`, `none`.
`summary`	string	Per-message template of the summary, such as {{ .json.type }} / {{ .json.subject }}.

`Sticky`

Key	Type	Description
`enabled`	boolean	Turn sticky routing on.
`mode`	string	model (default): ask the model whether it is a follow-up; always_last: always reuse the last destinations, no model call. One of `model`, `always_last`, `off`.
`follow_up_threshold`	number	Follow-up probability needed (default 0.8).

`AIBudget`

Key	Type	Description
`max_calls_per_minute`	integer	Model calls per minute.
`max_tokens_per_hour`	integer	Model tokens per hour.
`store`	string	Store that shares the counters across replicas (default: in-process).

`Transform`

Key	Type	Description
`filter`	string	CEL expression; false drops the message from this route or destination.
`jq`	string	jq program over the JSON body; its output is the new body.
`template`	string	Go template rendered as the new body.
`headers`	HeaderOps	Set, add or remove headers (values are templates).
`codec`	string	Re-encode the body. One of `json`, `text`, `base64_encode`, `base64_decode`, `form_to_json`, `cloudevents`.
`content_type`	string	Set the content type (alone, or after jq or template).
`redact`	string[]	JSONPaths whose values are replaced with [redacted] in the JSON body, such as $.card.number or $..email.
`validate`	SchemaCheck	Check the JSON body against a JSON Schema; a body that does not match is a failure.
`enrich`	Enrich	Call an HTTP endpoint and put its JSON answer into the JSON body.

`HeaderOps`

Key	Type	Description
`set`	map of string	Replace.
`add`	map of string	Append.
`remove`	string[]	Delete.

`Store`

Key	Type	Description
`name` (required)	string	Unique store name.
`type` (required)	string	redis, or memory (in-process: local runs and tests). One of `redis`, `memory`.
`addr`	string	redis standalone: host:port.
`sentinel`	Sentinel	redis Sentinel.
`cluster`	Cluster	redis Cluster.
`username`	string	ACL user.
`password`	string	Password, usually {{secrets.NAME}}.
`tls`	TLS	TLS to Redis.
`db`	integer	Database number (standalone and Sentinel).
`key_prefix`	string	Key prefix (default hikyaku).
`timeout`	Duration	Per-operation timeout (default 50ms): reads must never stall routing.
`retry`	Retry	Retries per operation (default attempts 2, backoff 10ms).
`circuit_breaker`	CircuitBreaker	Stops hammering a dead store (default on).

`DeadLetter`

Key	Type	Description
`type` (required)	string	Protocol: http, https, ws, wss, sse, stdout, stderr, file, fault, group, grpc, tcp, udp, kafka, nats, jetstream, mqtt, amqp, redis, sqs, sns, eventbridge, s3, pubsub, gcs, servicebus, eventhubs, model, or a plugin’s type.
`url`	string	http/ws: target URL, which may contain per-message templates (hosts are checked against egress). grpc: grpc://host:port or grpcs://; tcp: tcp://host:port or tls://; udp: udp://host:port or dtls://; nats, mqtt, amqp, redis: the server URL.
`method`	string	http: method (default POST); grpc: full method name, /package.Service/Method.
`headers`	map of string	Headers set on every request; values may be per-message templates.
`body`	string	Per-message template of the outgoing body (default: the message body).
`tls`	TLS	Client TLS, DTLS for udp (mTLS with cert_file and key_file).
`sign`	Sign	http: sign every request with an HMAC of its body, so the receiver can check who sent it.
`from`	string	smtp: the sender, as an address or as Name .
`to`	string[]	smtp: the recipients. Each entry is a per-message template that renders one address, or several separated by commas.
`oauth2`	OAuth2	http: fetch an OAuth 2.0 access token with the client credentials grant and send it as a bearer token.
`path`	string	file: the file appended to; sse: the stream path (default /).
`listen`	string	sse: address the event stream is served on.
`format`	string	file/stdout/stderr: write each message as an envelope line (default) or its body. One of `envelope`, `body`.
`frame`	string	ws: frame type, text (default) or binary. tcp, udp: framing, newline (default), length (a length_bytes big-endian prefix) or raw. One of `text`, `binary`, `newline`, `length`, `raw`.
`event`	string	sse: per-message template of the event name.
`replay`	integer	sse: events kept for Last-Event-ID resume (default 1000).
`auth`	Auth	sse: authentication of the clients that read the stream: bearer, api_key, jwt, ip_allow (401 on failure; hmac does not apply).
`fault`	Fault	fault: the faults injected (local testing and the resilience suite).
`brokers`	string[]	kafka: bootstrap brokers (host:port).
`topic`	string	Per-message template of the topic. kafka, mqtt, pubsub: the topic; sns: the topic ARN; eventhubs: the event hub; servicebus: the topic.
`key`	string	Per-message template of the message key. kafka: record key (partitioning); pubsub: ordering key; eventhubs: partition key; s3, gcs: object key (default //.json, or .ndjson for a batch).
`sasl`	SASL	kafka: SASL authentication.
`username`	string	mqtt, nats, redis, amqp, smtp: user name.
`password`	string	mqtt, nats, redis, amqp, smtp: password; use {{secrets.X}}.
`token`	string	nats: authentication token; use {{secrets.X}}.
`creds_file`	string	nats: a .creds file (JWT and NKey seed).
`subject`	string	Per-message template of the subject. nats, jetstream: the subject published to; sns: the message subject; smtp: the email’s subject.
`acks`	string	kafka: acknowledgements a produce waits for (default all, with the idempotent producer). One of `all`, `leader`, `none`.
`compression`	string	kafka: batch compression (default none). http: gzip compresses the request body and sets Content-Encoding (default none). One of `none`, `gzip`, `snappy`, `lz4`, `zstd`.
`qos`	integer	mqtt: publish QoS (default 1). One of `0`, `1`, `2`.
`retain`	boolean	mqtt: publish retained messages.
`client_id`	string	mqtt: client identifier; kafka: client.id. Default hikyaku--.
`protocol_version`	string	mqtt: protocol version (default 5). One of `3.1.1`, `5`.
`exchange`	string	amqp: exchange published to (default the default exchange, which routes by queue name).
`routing_key`	string	amqp: per-message template of the routing key.
`persistent`	boolean	amqp: persistent delivery mode (default true).
`mandatory`	boolean	amqp: fail a message no queue is bound to receive (a permanent error) instead of dropping it.
`declare`	boolean	amqp: declare the exchange (topic, durable) when missing.
`stream`	string	redis: stream key appended to (XADD); jetstream: the stream a publish must land in (an expected-stream check).
`channel`	string	redis: pub/sub channel published to; a per-message template.
`max_len`	integer	redis streams: approximate length the stream is trimmed to (MAXLEN ~).
`descriptor_set`	string	grpc: a FileDescriptorSet file describing method’s service.
`reflection`	boolean	grpc: resolve method through server reflection when there is no descriptor_set (default true).
`length_bytes`	integer	tcp, udp: size of the length prefix with frame: length (default 4). One of `1`, `2`, `4`, `8`.
`queue_url`	string	sqs: the queue URL.
`group_id`	string	Per-message template of the ordering group. sqs, sns FIFO: message group ID; servicebus: session ID.
`delay`	Duration	sqs: delivery delay (at most 15m).
`event_bus`	string	eventbridge: event bus name or ARN (default the account’s default bus).
`event_source`	string	eventbridge: the events’ source field (default hikyaku.).
`detail_type`	string	eventbridge: per-message template of the detail-type (default the message subject, else hikyaku.message).
`bucket`	string	s3, gcs: the bucket written to.
`content_type`	string	s3, gcs: the objects’ content type (default the message’s).
`queue`	string	servicebus: the queue (or topic).
`aws`	AWS	sqs, sns, eventbridge, s3: AWS region and credentials (default the SDK’s chain).
`gcp`	GCP	pubsub, gcs: project and credentials (default Application Default Credentials).
`azure`	Azure	servicebus, eventhubs: connection string or namespace and credentials.
`model`	string	model: the Genkit model that answers, provider/name (googleai/gemini-2.5-flash, openai/gpt-4o-mini, openrouter/anthropic/claude-sonnet-4.5, ollama/llama3.2).
`generation`	Generation	model: generation settings applied when the request does not set them.
`options`	object	Settings of a plugin type (a destination registered by a custom build); the plugin decodes and validates them.
`retry`	Retry	Retries of a DLQ write (default attempts 3).
`fallback`	string[]	Tried in order when the DLQ fails: destination names, or stdout / stderr. A message is acked only once some hop has it.

`APIKeyAuth`

Key	Type	Description
`header`	string	Header (default X-API-Key).
`query`	string	A query parameter that may carry the key when the header is absent, for clients that cannot set headers (a browser’s EventSource or WebSocket). URLs end up in proxy logs: prefer the header when the client can send one.
`keys` (required)	string[]	Accepted keys.

`AWS`

Key	Type	Description
`region`	string	Region (default the SDK’s: AWS_REGION, the profile).
`endpoint`	string	Custom endpoint URL, such as LocalStack’s http://localhost:4566.
`access_key_id`	string	Static credentials (with secret_access_key); use {{secrets.X}}.
`secret_access_key`	string	Static credentials; use {{secrets.X}}.
`session_token`	string	Session token of temporary static credentials.
`profile`	string	Shared config profile.
`role_arn`	string	Role assumed (STS) on top of the base credentials.

`Admin`

Key	Type	Description
`listen`	string	Address (default :9090).
`token`	string	Bearer token for mutating and history endpoints; without one they answer loopback only.
`disabled`	boolean	Do not serve the admin API.

`Auth`

Key	Type	Description
`hmac`	HMACAuth	Verify an HMAC signature of the body.
`bearer`	BearerAuth	Require a bearer token.
`jwt`	JWTAuth	Verify a JWT against a JWKS.
`api_key`	APIKeyAuth	Require an API key header.
`webhook`	WebhookAuth	Verify the signature of a well-known webhook sender (http sources).
`ip_allow`	string[]	Allowed client IPs or CIDRs.

`Azure`

Key	Type	Description
`connection_string`	string	Connection string (Endpoint=sb://…;SharedAccessKeyName=…;SharedAccessKey=…); use {{secrets.X}}.
`namespace`	string	Fully qualified namespace (.servicebus.windows.net), with Microsoft Entra credentials.
`tenant_id`	string	Client secret credentials: tenant (default: the SDK’s DefaultAzureCredential).
`client_id`	string	Client secret credentials: application (client) ID.
`client_secret`	string	Client secret credentials: secret; use {{secrets.X}}.

`Batch`

Key	Type	Description
`max_messages`	integer	Messages per batch (default 100).
`max_bytes`	Size	Body bytes per batch (default 1MiB).
`max_wait`	Duration	How long a batch waits to fill after its first message (default 1s).
`format`	string	Body of a batch for protocols without native batches (http, ws, file, …): ndjson (default), one body per line, or json_array of the bodies. One of `ndjson`, `json_array`.

`BearerAuth`

Key	Type	Description
`tokens` (required)	string[]	Accepted tokens.

`Buffer`

Key	Type	Description
`type`	string	memory (default) or disk: a bbolt write-ahead log, so queued messages survive a crash or restart and are delivered when the relay starts again. One of `memory`, `disk`.
`size`	integer	Queued messages (default 10000); listen sources answer 503 when full.
`path`	string	disk: the write-ahead log file (required with disk; one relay per file).
`sync`	boolean	disk: fsync every write before the message counts as queued (default true). false is faster but a host crash (not a process crash) can lose the last writes.

`Cluster`

Key	Type	Description
`addrs` (required)	string[]	Seed node addresses.

`Dedupe`

Key	Type	Description
`key` (required)	string	Per-message template of the dedupe key, such as {{ .json.id }}.
`ttl`	Duration	How long a key is remembered (default 1h).
`store`	string	Store that shares keys across replicas (default store).

`Egress`

Key	Type	Description
`allow`	string[]	Hosts (exact, or *.suffix) and CIDRs a templated URL may reach.
`allow_private`	boolean	Let templated URLs reach private, loopback and link-local addresses.

`Enrich`

Key	Type	Description
`url` (required)	string	The endpoint to call, a per-message template such as https://crm.internal/customers/{{ .json.customer_id }}.
`method`	string	GET (default), or POST, which sends the message body. One of `GET`, `POST`.
`headers`	map of string	Request headers (values are templates).
`into` (required)	string	Where the answer goes in the JSON body: a key, or a dotted path such as meta.customer.
`timeout`	Duration	How long the call may take (default 2s).
`cache`	Duration	Keep each URL’s answer this long, in this process, and skip the call meanwhile (GET only; default: no cache).
`on_error`	string	When the call fails: fail (default) fails the transform, skip lets the message go on without the answer. One of `fail`, `skip`.

`Fault`

Key	Type	Description
`fail`	Percent	Share of attempts that fail, such as 50%.
`fail_first`	integer	Fail the first N attempts, then follow fail.
`latency`	Duration	Added to every attempt.
`error`	string	How an attempt fails (default status). One of `status`, `connect`, `timeout`.
`status`	integer	Status of a failed attempt (default 503).
`retry_after`	Duration	Retry-After hint of a failed attempt.
`seed`	integer	Random seed, for repeatable runs.

`GCP`

Key	Type	Description
`project`	string	Project ID (pubsub: required).
`credentials_file`	string	Service account key file (default Application Default Credentials).
`credentials_json`	string	Service account key JSON; use {{secrets.X}}.
`endpoint`	string	Custom endpoint, such as an emulator’s localhost:8085 (pubsub) or http://localhost:4443/storage/v1/ (gcs).

`Generation`

Key	Type	Description
`temperature`	number	Sampling temperature.
`max_tokens`	integer	Maximum output tokens.
`top_p`	number	Nucleus sampling probability mass.
`system`	string	System prompt prepended when the request has none.

`Genkit`

Key	Type	Description
`plugins`	string[]	Plugins to initialize: systemone, googlegenai, anthropic, openai, openrouter, ollama, llmfake (test builds). Plugins named by a model’s provider prefix are added automatically.
`systemone`	SystemOne	System One decision-model servers.
`ollama`	Ollama	The Ollama server of the ollama plugin and the ollama decision server.
`openai`	OpenAI	The server of the openai plugin.

`HMACAuth`

Key	Type	Description
`header` (required)	string	Signature header, such as X-Signature-256.
`algo`	string	Hash (default sha256). One of `sha256`, `sha1`, `sha512`.
`secret` (required)	string	Shared secret, usually {{secrets.NAME}}.
`prefix`	string	Prefix before the digest, such as sha256= (stripped if present).
`encoding`	string	Digest encoding (default hex). One of `hex`, `base64`.

`HealthCheck`

Key	Type	Description
`path`	string	http members: path probed with GET on the member’s origin (default: the sink’s own health check).
`interval`	Duration	Default 10s.
`timeout`	Duration	Default 2s.
`unhealthy_after`	integer	Failed probes in a row before a member is skipped (default 3).
`healthy_after`	integer	Passed probes in a row before it is used again (default 1).

`Hedge`

Key	Type	Description
`after` (required)	Duration	Start another member when no answer came in this long.
`max`	integer	Extra members raced at most (default 1).

`JWTAuth`

Key	Type	Description
`jwks_url` (required)	string	JWKS endpoint.
`issuer`	string	Required iss.
`audience`	string	Required aud.
`algorithms`	string[]	Accepted algorithms (default RS256, ES256).

`Logs`

Key	Type	Description
`level`	string	Default info. One of `debug`, `info`, `warn`, `error`.
`format`	string	Default text on a terminal, json otherwise. One of `json`, `text`.

`Metrics`

Key	Type	Description
`prometheus`	boolean	Serve /metrics (default true).

`ModelFallback`

Key	Type	Description
`default`	string[]	Generative models tried after models.default.
`decision`	string[]	Decision models tried after models.decision.

`ModelRetry`

Key	Type	Description
`attempts`	integer	Tries per model (default 3). Each try may include the System One plugin’s own two transport retries.
`backoff`	Duration	Wait before the second try (default 500ms), doubling per try.
`max_backoff`	Duration	Cap on the wait (default 10s).

`Models`

Key	Type	Description
`default`	string	Default generative model, such as googleai/gemini-2.5-flash.
`decision`	string	Default decision model, such as typesafe/jev-1.13.0. Pin a version in production.
`retry`	ModelRetry	Tries per model before the next model of the chain.
`fallback`	ModelFallback	Global model fallback chains.

`Notify`

Key	Type	Description
`on`	string[]	The events that alert (default dead_letter and circuit_open).
`to` (required)	string[]	The destinations that get the alert, a JSON message.
`every`	Duration	At most one alert per event and subject in this time; the next one counts what happened meanwhile (default 1m).

`OAuth2`

Key	Type	Description
`token_url` (required)	string	The authorization server’s token endpoint.
`client_id` (required)	string	Client ID.
`client_secret` (required)	string	Client secret, usually {{secrets.NAME}}.
`scopes`	string[]	Scopes to ask for.
`audience`	string	The audience parameter, for servers that need one (Auth0).
`params`	map of string	More form parameters for the token request, such as resource.
`client_auth`	string	Where the client ID and secret go: basic (HTTP Basic, the default) or body (form fields). One of `basic`, `body`.

`OTel`

Key	Type	Description
`endpoint`	string	OTLP/HTTP endpoint; empty turns tracing off.
`insecure`	boolean	Plain HTTP to the collector.
`headers`	map of string	Exporter headers.
`service_name`	string	Default hikyaku.
`sample_ratio`	number	Share of traces kept (default 1).

`Observability`

Key	Type	Description
`logs`	Logs	Structured logs on stderr.
`otel`	OTel	OpenTelemetry traces over OTLP/HTTP.
`metrics`	Metrics	Prometheus metrics on the admin API.

`Ollama`

Key	Type	Description
`url`	string	Base URL (default http://localhost:11434).

`OnInvalid`

Key	Type	Description
`to` (required)	string[]	Destinations that get the refused message, with the schema.error attribute set.

`OpenAI`

Key	Type	Description
`base_url`	string	Base URL of the OpenAI API (default https://api.openai.com/v1, else OPENAI_BASE_URL when set). Point it at any OpenAI-compatible server, such as vLLM, LM Studio, LiteLLM or a gateway; its models are openai/. OPENAI_API_KEY is sent as a bearer token; a server other than the default may need none.

`Ordering`

Key	Type	Description
`key`	string	Template of the ordering key, such as {{ .json.customer_id }}. Empty: the source’s natural order unit (kafka partition, mqtt topic, amqp queue, sqs message group, …). A constant (“all”) orders the whole source.

`PluginBinary`

Key	Type	Description
`name` (required)	string	Plugin name, used in logs and metrics.
`command` (required)	string	The plugin binary: a path, relative to the spec file, or a name looked up on PATH.
`args`	string[]	Arguments passed to the binary.
`env`	map of string	Environment variables set for the plugin (values may use {{secrets.X}}).
`sha256`	string	Hex SHA-256 of the binary. When set, hikyaku refuses to start a binary that does not match.

`RateLimit`

Key	Type	Description
`per_second` (required)	number	Requests per second, on average (0.5 is one every two seconds).
`burst`	integer	Requests that may go out at once after a quiet time (default per_second, rounded up).

`Readiness`

Key	Type	Description
`destinations`	boolean	Not ready while a required destination can take nothing: every member of it, and of every fallback in its chain, is down (default true).
`models`	boolean	Not ready while every model of an AI route’s chain fails. A probe calls each model once; /readyz answers from the last probe and refreshes one older than 30s in the background.

`Reconnect`

Key	Type	Description
`backoff`	Duration	First wait (default 500ms), doubling.
`max_backoff`	Duration	Cap (default 30s).
`jitter`	string	Default full. One of `full`, `equal`, `none`.
`max_attempts`	integer	Give up after this many failed connects in a row; 0 = forever.

`Respond`

Key	Type	Description
`from` (required)	string	Destination whose reply is returned.
`timeout`	Duration	How long the caller waits (default 30s); then 504.

`SASL`

Key	Type	Description
`mechanism` (required)	string	SASL mechanism. One of `plain`, `scram-sha-256`, `scram-sha-512`.
`username` (required)	string	User name.
`password` (required)	string	Password; use {{secrets.X}}.

`SchemaCheck`

Key	Type	Description
`schema`	object	The JSON Schema, written inline.
`on_invalid`	OnInvalid	On a route: where a body that does not match goes, instead of the dead-letter queue.
`file`	string	A JSON Schema file (JSON or YAML), read when the relay starts or reloads. A relative path is relative to the working directory.

`Sentinel`

Key	Type	Description
`master_name` (required)	string	Monitored master.
`addrs` (required)	string[]	Sentinel addresses.
`password`	string	Sentinel password.

`Server`

Key	Type	Description
`admin`	Admin	Admin API: /healthz /readyz /metrics /reload /v1/feedback /v1/history /v1/tail.
`shutdown_grace`	Duration	Time in-flight messages get to finish on shutdown (default 20s).
`workers`	integer	Messages processed at once (default 256).
`readiness`	Readiness	What /readyz checks.

`Sign`

Key	Type	Description
`secret` (required)	string	Shared secret, usually {{secrets.NAME}}.
`header`	string	Header that carries the signature (default X-Signature-256).
`algo`	string	Hash (default sha256). One of `sha256`, `sha512`.
`prefix`	string	Text put before the digest, such as sha256=.
`encoding`	string	Digest encoding (default hex). One of `hex`, `base64`.
`timestamp_header`	string	When set, this header carries the send time in Unix seconds, and the signature covers ., so a receiver can refuse an old request.

`SystemOne`

Key	Type	Description
`servers`	string[]	Known servers: typesafe (TYPESAFE_API_KEY), openrouter (OPENROUTER_API_KEY), workersai (CLOUDFLARE_API_TOKEN), ollama (no key).
`custom`	SystemOneServer[]	Any other server that speaks the System One protocol.
`workersai_account_id`	string	Cloudflare account ID for workersai (else CLOUDFLARE_ACCOUNT_ID).
`ollama_url`	string	Base URL of the Ollama decision server (default http://localhost:11434).
`typesafe_base_url`	string	Override TypeSafe’s base URL (else TYPESAFE_BASE_URL).
`openrouter_base_url`	string	Override OpenRouter’s base URL.

`SystemOneServer`

Key	Type	Description
`provider` (required)	string	Plugin name and model prefix: models are /.
`base_url` (required)	string	Server root.
`path`	string	Decision endpoint path (default /v1/systemone).
`models_path`	string	Model listing path.
`api_key`	string	Bearer key, usually {{secrets.NAME}}.
`headers`	map of string	Extra request headers.
`images`	boolean	The server reads images.

`TLS`

Key	Type	Description
`enabled`	boolean	Use TLS (implied by any other field and by https/wss).
`cert_file`	string	Certificate (server cert, or client cert for mTLS).
`key_file`	string	Private key of cert_file.
`ca_file`	string	CA bundle that verifies the server.
`client_ca_file`	string	listen: CA bundle that verifies client certificates (mTLS).
`server_name`	string	SNI and verification name.
`insecure_skip_verify`	boolean	Skip server verification (development only).

`WebhookAuth`

Key	Type	Description
`provider` (required)	string	Who sends the webhook. One of `github`, `stripe`, `slack`, `shopify`, `twilio`.
`secret` (required)	string	The signing secret the sender gave you (for twilio, the auth token), usually {{secrets.NAME}}.
`tolerance`	Duration	How old a signed timestamp may be (stripe and slack; default 5m).
`url`	string	twilio only: the public URL Twilio calls, when a proxy in front of the relay changes the host or scheme.

Scalar types

`Duration`

A duration: 500ms, 30s, 5m, 1h, 7d.

`Percent`

A share: 50% or 0.5.

`Size`

A byte count: 512, 8KiB, 10MB.

`TagList`

Error tags: classes (connect, timeout), ranges (5xx, 4xx), exact codes (503, or a bare number) and protocol codes (ws:close_1011).

Spec reference

Top level (hikyaku.yaml)

Source

Destination

Member

Policy

Retry

CircuitBreaker

RetryBudget

Route

RouterSpec

Rule

Candidate

AIInput

Cache

History

Window

HistoryRecord

Sticky

AIBudget

Transform

HeaderOps

Store

DeadLetter

APIKeyAuth

AWS

Admin

Auth

Azure

Batch

BearerAuth

Buffer

Cluster

Dedupe

Egress

Enrich

Fault

GCP

Generation

Genkit

HMACAuth

HealthCheck

Hedge

JWTAuth

Logs

Metrics

ModelFallback

ModelRetry

Models

Notify

OAuth2

OTel

Observability

Ollama

OnInvalid

OpenAI

Ordering

PluginBinary

RateLimit

Readiness

Reconnect

Respond

SASL

SchemaCheck

Sentinel

Server

Sign

SystemOne

SystemOneServer

TLS

WebhookAuth