Skip to main content
Version: next

Config Files

Routerly stores all configuration as JSON files. The exact location depends on the installation scope chosen at install time. Files are written atomically and are human-readable.

The service reads the root directory from the ROUTERLY_HOME environment variable (set automatically by the installer in the daemon unit). If the variable is not set, it falls back to ~/.routerly/.

Directory Layout​

User scope (default)​

Everything lives under the installing user's home directory.

~/.routerly/
├── app/ # Service binary (managed by installer)
├── config/
│ ├── settings.json # Global settings
│ ├── models.json # Registered LLM models
│ ├── routers.json # Routers, routing, budgets, tokens
│ ├── users.json # User accounts
│ ├── roles.json # Custom roles and permissions
│ ├── modules.json # Which modules are enabled
│ ├── profiles.json # Routing profiles
│ ├── connections.json # Provider connections
│ ├── instances.json # Model instances
│ ├── experiments.json # A/B tests, their variants and tokens
│ └── secret # JWT signing key (mode 0600, keep safe)
└── data/
├── usage.ndjson # Usage records (append-only NDJSON)
├── notifications.json # Notification inbox
├── audit.json # Audit log
└── update-announcement.json # Last update alert announced (RA-15)

System scope​

Service config and data move to a system-wide directory; the CLI auth tokens remain per-user.

PlatformService config & data directory
Linux/var/lib/routerly/
macOS/Library/Application Support/Routerly/
WindowsC:\ProgramData\Routerly\
/var/lib/routerly/          # (Linux example; see table above for other platforms)
├── config/
│ ├── settings.json
│ ├── models.json
│ ├── routers.json
│ ├── users.json
│ ├── roles.json
│ ├── modules.json
│ ├── profiles.json
│ ├── connections.json
│ ├── instances.json
│ ├── experiments.json
│ └── secret # JWT signing key (mode 0600)
└── data/
├── usage.ndjson
├── notifications.json
├── audit.json
└── update-announcement.json

CLI auth tokens (always per-user)​

Regardless of install scope, each user's CLI credentials are stored in their own home directory, never in the system directory:

~/.routerly/
└── cli/
└── config.json # Saved accounts, JWT tokens, refresh tokens (mode 0600)

settings.json​

Global service configuration.

{
"port": 3000,
"host": "0.0.0.0",
"dashboardEnabled": true,
"logLevel": "info",
"publicUrl": "http://localhost:3000",
"channel": "current",
"notifications": {
"channels": [],
"notificationRules": [],
"cooldowns": {}
}
}
FieldTypeDefaultDescription
portnumber3000TCP port the service listens on
hoststring"0.0.0.0"Bind address. Use 127.0.0.1 behind a reverse proxy
dashboardEnabledbooleantrueEnable or disable the web dashboard
logLevelstring"info"Log verbosity: "fatal", "error", "warn", "info", "debug", "trace"
publicUrlstring"http://localhost:3000"Externally reachable URL, used for notification links
channelstring"current"Update channel: "latest", "current", "next", "stable", "develop", or a version tag such as "v0.2.0". "stable" is a permanent channel with its own release pointer; a persisted value is never rewritten. Controls which GitHub Release the update checker compares against
notifications.channelsarray[]Notification channel objects. Each has provider, optional name, id, events (event patterns), targets ({ roles, permissions, users }), plus provider-specific fields. See Notifications
notifications.notificationRulesarray[]Route event patterns to specific channel IDs: { events, channels }
notifications.cooldownsobject{}Minimum interval between repeated dispatches per event type (e.g. "provider.degraded": "15m")

models.json​

Array of registered LLM model configurations.

[
{
"id": "gpt-5-mini",
"provider": "openai",
"apiKey": "ENCRYPTED:...",
"inputPrice": 0.00015,
"outputPrice": 0.0006,
"cachePrice": 0.000075,
"contextWindow": 128000,
"capabilities": ["chat", "vision"],
"enabled": true
}
]
FieldTypeDescription
idstringUnique model identifier within Routerly
providerstringProvider name: openai, anthropic, gemini, mistral, cohere, xai, ollama, custom
apiKeystringAPI key — stored AES-256 encrypted with the value from secret
inputPricenumberCost per 1,000 input tokens in USD
outputPricenumberCost per 1,000 output tokens in USD
cachePricenumberCost per 1,000 cached/read tokens in USD (optional). If omitted, cache reads are billed at inputPrice (the service logs a one-time warning)
contextWindownumberMaximum context window in tokens
capabilitiesstring[]Supported capabilities: "chat", "vision", "tools", "json_mode"
pricingTiersarrayVolume-based pricing tiers (optional)
enabledbooleanWhether the model is available for routing
baseUrlstringCustom base URL — required for custom provider, used for non-default Ollama hosts
caution

Never edit apiKey values manually. Use the dashboard or CLI to manage API keys; they are encrypted using the secret file.


routers.json​

Array of Router configurations: routers, Orchestrators, and Passthrough Routers alike (see Concepts: Routers and Concepts: Architecture for the three kinds). Migrated automatically and idempotently from the pre-rename projects.json on first start.

[
{
"id": "a1b2c3d4-e5f6-4a1b-8c2d-9e0f1a2b3c4d",
"name": "My App",
"timeoutMs": 2000,
"policies": [{ "type": "cheapest" }],
"models": [{ "modelId": "gpt-5-mini" }, { "modelId": "claude-haiku-4-5" }],
"tokens": [
{
"id": "b2c3d4e5-f6a1-4b2c-9d3e-0f1a2b3c4d5e",
"token": "sk-rt-...",
"createdAt": "2024-01-15T10:00:00Z"
}
],
"members": [
{ "userId": "usr_abc", "role": "admin" }
]
}
]

Router Fields (kind router, the default)​

FieldTypeDescription
idstringInternal Router ID (UUID)
namestringHuman-readable Router name
kindstring"router" | "orchestrator" | "passthrough". Absent means "router" (every Router stored before this field existed)
timeoutMsnumberTime-to-first-token timeout per model attempt, streaming requests only, in milliseconds. Default 2000; 0 disables it. Non-streaming calls are capped by the model timeout (default 60000)
policiesRoutingPolicy[]Routing policies in priority order (each { type, ...params }); see Concepts: Routing
modelsarrayTarget models: { modelId, prompt? }
candidatesarrayOnly on kind: "orchestrator": { routerId, limits? } — other Routers this one forwards to, in priority order (index 0 = highest); no weight field
slugstringOnly on kind: "passthrough": the URL path segment at /passthrough/<slug>/*

Budgets are not a top-level array on the Router: they live as limits on a model entry or on a token (see Token Fields below), not on the Router record itself.

Token Fields​

FieldTypeDescription
idstringToken ID (UUID)
tokenstringRouter token, stored in plaintext (file permissions 0600 protect it — the proxy must compare it against an incoming Authorization header of unknown origin)
expiresAtstringOptional ISO 8601 expiry; absent or null means never expires
modelsarrayOptional per-token, per-model budget overrides
createdAtstringISO 8601 creation timestamp

users.json​

Array of user accounts.

[
{
"id": "usr_abc123",
"email": "[email protected]",
"passwordHash": "$2b$10$...",
"role": "admin",
"createdAt": "2024-01-01T00:00:00Z"
}
]
FieldTypeDescription
idstringUser ID (usr_…)
emailstringLogin email
passwordHashstringbcrypt hash of the password
rolestringGlobal role name: "admin", "member", "viewer", or a custom role
createdAtstringISO 8601 creation timestamp

roles.json​

Array of custom role definitions. The three built-in roles (admin, member, viewer) are not stored here and cannot be modified.

[
{
"name": "billing-viewer",
"permissions": ["usage:read"]
}
]
FieldTypeDescription
namestringUnique role name
permissionsstring[]List of permission strings

Available permissions: models:write, routers:write, users:write, roles:write, settings:write, usage:read, proxy:use.


data/usage.ndjson​

Append-only NDJSON: one JSON object per line, one line per LLM request. The service appends to this file without reading or rewriting the rest of it, so a write's cost does not grow with the history size. Migrated automatically from a legacy data/usage.json array on first start after the upgrade.

{"id":"a1b2c3d4-...","timestamp":"2024-01-15T10:30:00Z","routerId":"b2c3d4e5-...","modelId":"gpt-5-mini","inputTokens":150,"outputTokens":42,"cost":0.000048,"latencyMs":1234,"outcome":"success"}

Key fields (see UsageRecord in @routerly/shared for the full shape):

FieldTypeDescription
idstringUsage record ID
timestampstringISO 8601
routerIdstringThe Router that served the request
modelIdstringThe model the request was routed to
inputTokens / outputTokensnumberToken counts
costnumber | nullUSD cost; null when no model could be priced against (e.g. Passthrough traffic)
latencyMsnumberForwarding start to last byte received
outcomestring"success", "error", or "blocked"
orchestratorIdstringSet when the call was forwarded through an Orchestrator; routerId/modelId still identify the Router and model that actually executed it

This file grows continuously. routerly service configure --usage-retention-days <n> and --usage-retention-max-mb <n> (or the equivalent Settings page fields) enable an age- and/or size-based retention sweep that drops the oldest records first; both are unset by default and Routerly does not rotate or archive the file on its own.


data/update-announcement.json​

Records the last system.update_available alert the update checker raised, so the same release is not announced again after a restart. See Concepts: Notifications for the event itself.

{
"announcedVersion": "0.5.0",
"currentVersion": "0.4.0",
"channel": "current",
"announcedAt": "2026-08-04T10:00:00.000Z"
}
FieldTypeDescription
announcedVersionstringThe latestVersion from the check that raised the alert
currentVersionstringThe version the instance was running when it announced
channelstringThe update channel the announcement came from
announcedAtstringISO 8601 timestamp, informational only

The update checker is the file's only writer: it reads the record before each check and rewrites it whenever it raises a new alert. No API endpoint exposes this file; it is not readable or writable through the dashboard, the CLI, or the management API.

Deleting this file does not disable the alert. It is read the same way a missing or corrupt file is: as "no prior announcement". The next check announces the current channel's release once more and rewrites the file, after which deduplication resumes as normal.


secret​

A single-line file containing the 32-byte AES-256 encryption key used to encrypt API keys in models.json.

a1b2c3d4e5f6...

Never share or commit this file. If lost, all stored API keys must be re-entered.