Documentation Index
Fetch the complete documentation index at: https://ekso.dev/llms.txt
Use this file to discover all available pages before exploring further.
ekso.json is the single source of truth for install-time configuration. The bundle ships with a complete ekso.json pre-configured for the install path you picked — most customers never edit it. This page documents every field, what it does, and when you’d touch it.
File layout
ekso.json lives next to docker-compose.yml in the bundle. Compose mounts it into both the app and worker containers. Edit, then docker compose restart to pick up changes.
Anything not in ekso.json (AI providers, license activation, tenant data, integrations) lives inside Ekso — configured via the Settings UI after first run, persisted to the database.
Sections
| Section | Purpose |
|---|
Auth | JWT signing key for session tokens |
Misc | Deployment posture + optional third-party service keys |
Smtp | Optional outbound-email fallback |
Database | Postgres or SQL Server connection strings |
Auth
"Auth": {
"Jwt": {
"Key": "<32+ char random string — pre-baked per download>",
"Issuer": "Ekso",
"Audience": "Ekso"
}
}
| Field | Description |
|---|
Auth.Jwt.Key | Symmetric secret used to sign user session JWTs. Pre-baked unique-per-download by ekso.app. Minimum 32 characters. |
Auth.Jwt.Issuer | The iss claim Ekso sets on session tokens. Default "Ekso"; rarely changed. |
Auth.Jwt.Audience | The aud claim Ekso validates against. Default "Ekso"; must match Issuer configuration unless you’ve separated signer and verifier. |
Rotating Auth.Jwt.Key signs every active user out — every session token in the wild was signed with the old key and will no longer validate. Plan a rotation window and brief your users.
Misc
"Misc": {
"Mode": "selfhost",
"Resend": "",
"Sentry": ""
}
| Field | Description |
|---|
Misc.Mode | Deployment posture identifier. Emitted on every API response as the X-Ekso-Host header. "selfhost" is the default and currently the only supported value. |
Misc.Resend | Optional Resend API key for transactional email. Empty → fall back to SMTP → log-and-skip. |
Misc.Sentry | Optional Sentry DSN for error reporting. Empty → no Sentry registration, no events leave the install. |
Smtp
"Smtp": {
"Host": "",
"Port": 587,
"Username": "",
"Password": "",
"FromAddress": "",
"FromName": "Ekso",
"UseStartTls": true
}
Misc.Resend is empty. Leave every field blank to disable outbound email entirely — Ekso will log notifications and skip dispatch.
| Field | Description |
|---|
Smtp.Host | SMTP server hostname, e.g. smtp.fastmail.com. |
Smtp.Port | TCP port. Common values: 587 (StartTLS, default), 465 (implicit TLS — also set UseStartTls: false), 25 (unauthenticated relay). |
Smtp.Username | SMTP authentication username. Empty for unauthenticated relays such as a localhost MTA. |
Smtp.Password | SMTP authentication password. |
Smtp.FromAddress | The From: address on outbound email. Must be a domain you can send from (SPF and DKIM aligned). |
Smtp.FromName | Display name on outbound email. |
Smtp.UseStartTls | Issue STARTTLS on connect. true for port 587, false for port 465. |
Database
"Database": {
"Timeout": 300,
"Provider": "Postgres",
"PostgresTransactConnection": "Host=...",
"PostgresMartConnection": "Host=...",
"PostgresAutoPrepare": false,
"SqlServerTransactConnection": "",
"SqlServerMartConnection": ""
}
| Field | Description |
|---|
Database.Timeout | Default per-query timeout in seconds. 300 is the default. |
Database.Provider | "Postgres" (recommended) or "SqlServer". Determines which connection-string pair Ekso uses; the unused engine’s slots can be empty. |
Database.PostgresTransactConnection | OLTP connection string — the live-work database. pgvector required for AI features. |
Database.PostgresMartConnection | Reporting/analytics connection. Can point to the same instance as Transact for small installs; separate it onto a read replica for heavy reporting. |
Database.PostgresAutoPrepare | Enable Npgsql auto-prepare for repeated queries. Off by default; turn on for query-heavy workloads where the prepared-statement cache pays off. |
Database.SqlServerTransactConnection | OLTP connection string when Provider = "SqlServer". SQL Server 2025 required for vector search. |
Database.SqlServerMartConnection | Reporting connection string when Provider = "SqlServer". |
Ekso emits the schema for whichever Provider you pick on first boot. Don’t switch providers on a populated install — back up, point at a fresh database, restore.
Override mechanisms
Outside Docker (Backend dev, custom orchestrators), .NET configuration binding accepts these alternatives, in increasing precedence:
ekso.json — committed defaultekso.local.json — same directory, gitignored, for developer overrides- Environment variables — section separator is
__, e.g. Auth__Jwt__Key, Database__PostgresTransactConnection
The last value wins. Env vars are useful for dev shells and CI runners; ekso.local.json for persistent dev overrides; ekso.json for the canonical install config.
Settings not in ekso.json
These move to the database, configured via the Settings UI after first run:
- AI providers and keys — OpenAI, Azure OpenAI, Anthropic. Per-tenant. See Settings → AI.
- License activation — pasted from your welcome email during the first-run wizard; rotates with the licence.
- Authentication providers (Entra SSO, password policies, 2FA) — see Authentication.
- Mailbox / ticketing config, rule webhooks, integrations — see the per-feature pages under Core concepts.
This split is deliberate: install-time config is the minimum to boot before the database exists. Everything else lives in the database, edited via the UI, scoped per tenant where applicable.
