Skip to main content
Version: 0.6.0

Dashboard: Settings

The Settings page allows admins to configure the Routerly service, notification channels, and view system information. It is only accessible to users with the admin role.

Open Settings from the Settings item in the sidebar.


General Tab​

Settings General tab showing server info, runtime settings, and anonymous metrics toggle

Server Info​

Read-only block. It answers one question: where is this service reachable, and from where.

Under Reachable at any of these addresses (Reachable at when there is only one) each address is listed with a badge:

BadgeMeaning
This machineLoopback address (127.0.0.1, ::1, localhost). Only clients running on the same machine can use it
NetworkReachable from other machines that can route to this host

Each address has a Copy button that puts it on the clipboard.

The list is derived at runtime from the bind address: a wildcard bind (0.0.0.0) expands to every IPv4 interface, any other host resolves to that single address.

Below the list:

RowDescription
Host and portThe bind address the service was started with
VersionThe running build
UptimeTime since the service started

Host and port come from the environment or the settings file and cannot be changed here; changing them requires a restart.

Runtime Settings​

Everything in this block is editable and saved with Save Settings.

FieldDescription
Log Leveltrace / debug / info / warn / error. Routerly prints the full request trace on stdout, with failures on stderr; at warn and error only the failures are printed
Public URLThe externally accessible URL of this Routerly instance. Shown in router connection snippets. Useful when the dashboard runs on a different machine or port than the service

| Default language (Internationalization) | Language for users who have not picked their own, in Profile → Preferences or the sidebar selector. A user's own choice is never overridden. Editable with settings:write |

Anonymous metrics is a separate self-saving toggle at the bottom of the tab.

Per-request timeouts are configured per router (see Routers), not globally.


Security Tab​

FieldDescription
Require Two-Factor Authentication for all usersWhen enabled, users without 2FA are prompted to set it up right after login. Users enrol from their Profile page

Press Save Settings to apply.


Notifications Tab​

Settings Notifications tab showing configured channels list with type, events, and action buttons

Configure notification channels. Each channel routes events to a delivery method (in-app inbox, email, or webhook) and can be scoped to specific event types and recipients.

The Notifications tab provides a channel management interface with a full list of configured channels and options to create, edit, test, and delete them.

Channel List​

The list displays all configured channels in a table with:

  • Name - friendly label
  • Type - channel provider (Dashboard, SMTP, Slack, etc.)
  • Events - event filter summary (shows first few patterns, * = all)
  • Targets - target summary (role, permission, and user counts; empty = everyone)
  • Actions - buttons to edit, test, and delete

Click a channel row to navigate to its edit page for detailed configuration.

Adding a Channel​

  1. Click + Add Channel (or navigate to Settings > Notifications > New Channel)
  2. Select the channel type: Dashboard, SMTP, SES, SendGrid, Azure, Google, Webhook, Slack, Teams, PagerDuty, or Discord
  3. Fill in the friendly Name and any required connection details:
    • Dashboard: name only (no credentials)
    • Email providers (SMTP, SES, SendGrid, Azure, Google): host, auth, from address
    • Webhooks/Native (Webhook, Slack, Teams, PagerDuty, Discord): integration URLs and keys
  4. (Optional) Filter by Events - select specific event types to route to this channel; required for external channels (no events = silent); dashboard channels receive all when empty
  5. (Optional) Set Recipients / Targets - pick roles, permissions, or individual users; leave empty for everyone
  6. Click Create Channel
  7. Use Send Test to verify the channel works before relying on it for real events

See Concepts: Notifications for the full event taxonomy and per-type configuration fields.

Among the built-in events, the update checker raises System – Update Available whenever it finds a newer release on the configured update channel; it appears with that label in the Events dropdown here and in the routing-rule Events picker below, so it can be routed to any channel like any other event. It also lands in the in-app inbox for any Dashboard channel it matches.

Target scope

Recipients / Targets control inbox visibility for the Dashboard channel and recipient resolution for email channels. Webhook and native channels (Slack, Teams, PagerDuty, Discord) deliver to a fixed endpoint - targets are stored but do not affect their delivery.

Editing a Channel​

Click the channel row or the Edit button to open the edit page. You can change:

  • Name - friendly label
  • Events - event filter (external channels with none are silent; dashboard channels receive all)
  • Recipients / Targets - audience filter
  • Connection details - provider-specific fields (host, API keys, etc.). Secret fields (passwords, API keys, tokens) show as masked (***) when present; clearing the field will leave it unchanged. To update a secret, re-enter it in the text field.

After making changes, click Update Channel to save.

Testing a Channel​

On the channel list or edit page, click Send Test. Routerly sends a test message immediately. Check for a success toast or an error message with details about what went wrong.

For email-provider channels, you can optionally override the recipient email address before sending the test.

Removing a Channel​

Click the Delete button on the channel row or edit page. You will be asked to confirm deletion.

Routing Rules​

Routing rules map event patterns to one or more channels. When an event matches a rule's patterns, it is dispatched to the specified channels (in addition to any router-level overrides via the Notifications tab on the router page).

By default, events are not routed to any channels — they are only recorded in the inbox. Add a rule to enable routing.

Adding a Rule:

  1. Scroll to the Routing Rules section
  2. Click + Add Rule
  3. Select one or more Events from the dropdown (e.g. Provider - Error, Budget - Threshold)
  4. Select one or more Channels to route matching events to
  5. Click Add

The rule is applied immediately.

Event Patterns:

Rules support three pattern types:

  • Exact name — e.g. provider.error (matches only that event)
  • Wildcard — * (matches all events)
  • Prefix glob — e.g. budget.* (matches budget.threshold, budget.exhausted, etc.)

Removing a Rule:

Click the × icon next to a rule to delete it.

See Concepts: Notifications — Routing Rules for additional details.

Cooldowns​

Cooldowns suppress repeated dispatches of the same event type within a specified interval. Suppressed events are still recorded in the inbox and logs; they are simply not sent to external channels.

This prevents alert fatigue when a system is repeatedly triggering the same issue.

Adding a Cooldown:

  1. Scroll to the Cooldowns section
  2. Click + Add Cooldown
  3. Select an Event from the dropdown (e.g. Provider - Degraded)
  4. Enter a Duration in format: 15m, 1h, 30s, 2d (supports s / m / h / d suffixes)
  5. Click Add

The cooldown is applied immediately.

Removing a Cooldown:

Click the × icon next to a cooldown to delete it.

See Concepts: Notifications — Cooldowns for additional details.


Provider Catalog Tab​

Configure the provider and model catalog repositories. Routerly fetches the catalog dynamically from one or more remote repositories at runtime, enabling rapid updates without service restarts.

The default catalog source is the official Inebrio repository. Add custom repositories to merge additional providers or override defaults.

Repository List​

The table displays all configured repositories with the following columns:

  • # — Priority (row order). Row 1 is checked first on merge conflict. Use arrow buttons to reorder.
  • URL — Repository endpoint (clickable, opens in new tab)
  • File — Filename of the last resolved catalog snapshot (or — if never fetched)
  • Updated — Timestamp from the catalog registry, indicating when the snapshot was created (or —)
  • Last Check — When Routerly last attempted to fetch from this repo (or — if never checked)
  • Status — Active (green) for enabled repos, Disabled (muted) for disabled repos, or Error (red with tooltip showing details)

Reordering Repositories​

Click the up/down arrow buttons on each row to change priority. The first repo in the list wins on merge conflict. Up arrow is disabled on row 1 (topmost); down arrow is disabled on the last row.

Editing a Repository​

Click Edit to modify:

  • URL — the repository endpoint (required)
  • Enabled — checkbox to enable or disable the repo without removing it

Click Save to persist changes or Cancel to discard.

Removing a Repository​

Click the Remove (trash icon) button to delete a repository from the list immediately. The default Inebrio repository cannot be removed.

Adding a Repository​

  1. Scroll to the Add Repository form below the table
  2. Enter the repository URL (e.g. https://your-org.com/catalog/)
  3. Click Add Repository

The new repo is appended at the end of the list (lowest priority). Enable/disable or reorder as needed.

Refresh​

Click the Refresh button in the top right to invalidate the 6-hour in-memory cache and fetch all enabled repositories immediately. The estimated next automatic refresh time is shown below the button. Useful after adding a new repo or when you know the catalog has been updated.


Modules​

Every module is core and always active, so the dashboard has no module controls. routerly modules list shows the modules. See CLI — Commands.


Integrations Tab​

Export Routerly metrics to external monitoring and observability systems. Integrations push metrics every 60 seconds to your chosen platform.

Supports: Prometheus (pull), OpenTelemetry, Datadog, Grafana Cloud, InfluxDB, and Webhook.

The Integrations tab provides a management interface with a list of configured integrations and options to create, edit, test, enable/disable, and delete them.

Integration List​

The list displays all configured integrations in a table with:

  • Name — friendly label
  • Type — integration provider (Prometheus, Datadog, OpenTelemetry, etc.)
  • Status — enabled/disabled toggle
  • Details — endpoint, URL, or key identifier (truncated for readability)
  • Actions — buttons to edit, test, and delete

Click a row to expand inline details (endpoint, protocol, headers, etc. depending on type).

Integrations tab showing configured integrations with enabled toggle, test button, and delete button

Adding an Integration​

  1. Click + Add Integration to open the create form

  2. Select the integration Type: Prometheus, OpenTelemetry, Datadog, Grafana Cloud, InfluxDB, or Webhook

  3. Enter a friendly Name (e.g. "Production Datadog")

  4. Fill in type-specific configuration:

    Prometheus (pull-based, no push):

    • Auth Token (optional) — if Routerly's /metrics endpoint requires bearer authentication

    OpenTelemetry (push):

    • Endpoint URL (required) — e.g. http://localhost:4318
    • Protocol (required) — http or grpc
    • Headers (optional) — one per line, format Key: Value (e.g. Authorization: Bearer token)

    Datadog (push):

    • API Key (required) — your Datadog API key
    • Site (required) — datadoghq.com (US East), datadoghq.eu (EU), us3.datadoghq.com, us5.datadoghq.com, or ddog-gov.com

    Grafana Cloud (push):

    • Remote Write URL (required) — Prometheus remote_write endpoint from your Grafana Cloud instance
    • Username (required) — numeric ID from Grafana Cloud
    • API Key (required) — your Grafana Cloud API key

    InfluxDB (push):

    • URL (required) — e.g. http://localhost:8086
    • Token (required) — InfluxDB API token
    • Organization (required) — org name in InfluxDB
    • Bucket (required) — target bucket for metrics

    Webhook (push):

    • URL (required) — HTTPS endpoint to receive metric POST requests
    • Secret (optional) — if set, Routerly signs each request with HMAC-SHA256 in the X-Routerly-Signature header
    • Headers (optional) — custom headers to include with each request
  5. For OpenTelemetry and Webhook, optionally turn on trace export

  6. Check the Enabled toggle to activate immediately upon creation

  7. Click Create Integration

  8. Use Test to verify connectivity before relying on it for production metrics

Editing an Integration​

Click the Edit button on an integration row to open the edit page. You can change:

  • Name — friendly label
  • Enabled toggle — pause/resume without deleting
  • Type-specific config — provider credentials and settings. Secret fields (API keys, tokens, auth token, secret) show as masked (***) when present; clearing the field will leave it unchanged. To update a secret, re-enter it in the text field.

After making changes, click Update Integration to save.

Testing an Integration​

On the list or edit page, click Test. Routerly verifies connectivity to the external system and sends a test request if applicable.

  • Prometheus — test is a no-op (always succeeds; Prometheus pulls metrics from /metrics, so outbound connectivity is not checked)
  • Push types — sends a real metrics payload and returns success or error details

A toast notification shows the result immediately.

Enabling and Disabling​

Use the Enabled toggle on the list view to pause metric export to an integration without deleting it. Disabled integrations do not receive metric pushes.

Removing an Integration​

Click the Delete button on a row. You will be asked to confirm deletion.

Metrics Exported​

All push-type integrations (OpenTelemetry, Datadog, Grafana, InfluxDB, Webhook) receive the same metrics every 60 seconds:

MetricTypeDimensionsDescription
routerly_requests_totalCounterrouter, modelTotal request count by router and model
routerly_tokens_totalCountertype (input/output), router, modelTotal tokens consumed
routerly_cost_usd_totalGaugerouter, modelEstimated USD cost by router and model
routerly_request_duration_p50_msGaugerouterMedian request latency per router
routerly_request_duration_p95_msGaugerouter95th percentile latency per router
routerly_budget_used_ratioGaugerouterBudget consumption ratio (0–1) per router

Each platform receives metrics in its native format:

  • OpenTelemetry — OTLP JSON or gRPC
  • Datadog — Datadog Series API v2
  • Grafana — Prometheus remote_write format
  • InfluxDB — InfluxDB v2 line protocol
  • Webhook — JSON POST with metric snapshot

Exporting Traces​

Metrics are aggregates pushed every 60 seconds. A trace is the opposite: the full record of one proxied request, every phase it went through and every module that spoke in it. The two sinks that can carry a per-request payload, OpenTelemetry and Webhook, can export traces as well, on the create and edit forms:

FieldDescription
Export request tracesOff by default. Unlike the 60-second metric push, this is one outbound request per proxied request
Sample rateShown once export is on. 1 exports every request, 0.1 one in ten. The decision is taken once per request, so a sampled-out request produces no partial export

What each sink receives:

  • OpenTelemetry — native OTLP spans on <endpoint>/v1/traces: a routerly.request root span with one routerly.<phase> child span per pipeline phase, and each trace entry as a span event. No extra configuration: the same endpoint already used for metrics.
  • Webhook — one POST per completed request, { "source": "routerly", "type": "trace", "timestamp", "trace": { "id", "routerId", "entries" } }, signed with the same X-Routerly-Signature HMAC as the metric payloads when a secret is set.

Traces always carry metadata: models, policies, guardrail outcomes, PII scan results, tokens and timings. Prompts and answers are included only for routers that opted in (Trace content on the router's General tab, or routerly router edit <router> --trace-content).


About Tab​

Application​

System information about the running instance:

FieldDescription
VersionRouterly version string
ChannelActive update channel: latest, current, next, develop, or a pinned version tag. Editable — see Update Channel below
UptimeHow long the service has been running since last start
Node.jsNode.js runtime version
PlatformOS and architecture
Config DirectoryPath to ~/.routerly/config/ (or $ROUTERLY_HOME/config/)

Update Channel​

The channel selector lets you choose which release stream Routerly follows when checking for updates. Each option shows the version the channel currently points to (for example stable · 0.6.0), and a note under the selector reminds you that current follows every new stable release while stable moves only when a release is promoted, so the two can differ:

ChannelDescription
latestNewest production-ready release
currentNewest production-ready release (same as latest)
nextValidated pre-release line, promoted from develop
stableRelease explicitly promoted to stable; moves only on promotion, so it can lag behind current
developBleeding-edge, unreviewed release line
Custom versionPin to a specific release tag (e.g. v0.2.0)
Breaking change

develop is not an alias for next: it is its own channel, the bleeding-edge line. An instance that had develop persisted under the old meaning now tracks the bleeding-edge line instead of next.

Changing the channel takes effect immediately — the running service is notified without a restart.

To enter a specific version tag, select Custom… in the dropdown. Type the tag (e.g. v0.2.0) and click Apply.

You can also change the channel from the CLI:

routerly update channel current
routerly update channel v0.2.0

Software Update​

Shows the current update status for the active channel. The service checks for new releases automatically every 24 hours.

FieldDescription
Current versionThe version currently running
Available versionThe latest version on the active channel, or "Up to date" if already current
Last checkedTimestamp of the most recent check against the GitHub Releases API

When update checking is switched off on the instance (the service is not running in production, or ROUTERLY_DISABLE_UPDATE_CHECK=true), the Current version is still shown and the section says that the update check is disabled instead of "Up to date". If the check fails (network error, GitHub rate limit), the section shows the error instead of a result.

Check for updates forces an immediate check against the GitHub Releases API and refreshes the displayed result.

Update to vX.Y.Z — visible only when a newer version is available on the current channel and the service is not running inside Docker. Clicking it triggers an in-app update:

  1. The service downloads and runs the installer for the new version in the background
  2. The service restarts automatically
  3. The dashboard reloads once the service is back online (polled every 3 seconds, up to 60 seconds)
Docker deployments

In-app update is disabled when Routerly is running inside a Docker container. Pull the new image and recreate the container instead:

docker pull inebrio/routerly:latest
docker compose up -d

Admin Update Banner​

When a newer version is available on the active channel, a yellow banner appears at the top of every page for admin users. The banner links to this page and can be dismissed for the current browser session by clicking ×.


Audit Log​

Settings → Audit Log

The Audit Log records every write operation performed on the Routerly instance: who did what, when, and whether it succeeded or was blocked.

What is recorded​

EventTrigger
model:create/update/deleteModel added, edited, or removed
router:create/update/deleteRouter added, edited, or removed
user:create/update/deleteUser added, edited, or removed
role:create/update/deleteRole added, edited, or removed
token:create/deleteAPI token issued or revoked
settings:updateGlobal settings changed
forbiddenAny action blocked by missing permission

Filters​

  • Period — date range picker with presets (today, last 7 days, this month, etc.)
  • User — filter by email or user ID
  • Action — filter by action substring (e.g. model:create)
  • Result — toggle between All / Success / Forbidden / Error

Results are paginated (50 entries per page), server-side.

Retention​

Entries older than 90 days are automatically pruned. Maximum 10,000 entries are kept at any time.

Access control​

Requires audit:read permission. Assign this permission to roles that should have read-only access to the audit trail (e.g. a dedicated "Auditor" role).