Configuration

Athena Server is configured through appsettings.json. Values you save in the console go to appsettings.local.json in the data directory, and environment variables override both (sections use a double-underscore separator, e.g. Server__PublicUrl).

The Settings screen in Athena — Settings → General — language and display options; each tab maps to a group of settings, saved to `appsettings.local.json`.

Configuration sources#

Settings are layered, with later sources overriding earlier ones. The precedence, lowest to highest, is:

appsettings.json: the shipped defaults, baked into the image. The server never writes to this file.
appsettings.<Environment>.json: an optional environment overlay, such as appsettings.Production.json (the container runs as Production).
appsettings.local.json in the server's data directory: every value you save on a Settings tab is written here (/app/data/appsettings.local.json in the container, or next to the server executable on a direct install). The file appears on the first save. Changes are picked up without a restart, although the Settings page notes that some settings still need one.
secrets.json in the data directory: per-install secrets the server generates on first start.
Environment variables: ideal for secrets and host-specific values, passed to the container with -e.
Command-line arguments passed when the server process starts (highest precedence).

Because appsettings.local.json sits above the shipped and environment files, a value saved in the console beats them. An environment variable or command-line argument still beats a saved value. When that happens, the save shows a warning; see Configuration Override Warnings.

A nested JSON key maps to an environment variable by joining the section and key names with a double underscore. For example, the Server:PublicUrl setting is overridden by:

Server__PublicUrl=https://athena.example.com:8443

Keep secrets out of config files

Provide Jwt__Secret and RemoteSession__Turn__StaticAuthSecret as environment variables rather than writing them into appsettings.json. The JWT secret signs the console's login tokens and the TURN secret authorizes remote-session relay credentials — treat both like passwords.

Database#

The Database section selects the storage provider and connection.

Key	Default	Notes
`Provider`	`Sqlite`	Default. Also supports `PostgreSQL`.
`ConnectionString`	`Data Source=athena.db`	Provider-specific connection string.
`HeartbeatBatchDelayMs`	`3000`	Batching window for agent heartbeat writes, in milliseconds.

SQL Server is not shipped — only the SQLite and PostgreSQL provider plugins exist. For a step-by-step guide to running on PostgreSQL — the connection string format, schema creation, and how to verify it — see Using PostgreSQL for the Database.

Server & ports#

The Server section controls the listening ports, TLS and the externally reachable URL. To replace the auto-generated certificate with your own and run behind a reverse proxy, see Server TLS Certificate.

Key	Default	Notes
`WebPort`	`8443`	Web console / API port.
`ApiPort`	`8444`	Agent gateway port (gRPC over HTTP/2).
`TlsEnabled`	`true`	Terminate TLS on Kestrel.
`Hostnames`	—	Hostnames the server answers on.
`WebCertPath`	—	Path to the server TLS certificate (PFX).
`WebCertPassword`	—	Password for the PFX certificate.
`PublicUrl`	—	Externally reachable base URL, e.g. `https://athena.example.com:8443`.

gRPC#

The nested Grpc section tunes the agent gateway message limits.

Key	Default	Notes
`MaxReceiveMessageSize`	`67108864`	64 MB — sized for video and file transfers.
`MaxSendMessageSize`	`67108864`	64 MB — sized for video and file transfers.
`EnableDetailedErrors`	`true`	Include detailed error information on gRPC faults.

PKI#

The Pki section governs the built-in certificate authority that issues and renews agent certificates.

Key	Default	Notes
`CertificatesPath`	`./pki`	Where the CA and issued certificates are stored.
`CaSubject`	`CN=Athena Root CA, O=Athena Deploy Center`	Distinguished name of the root CA.
`CaValidityYears`	`10`	Root CA lifetime, in years.
`AgentCertValidityDays`	`60`	Issued agent certificate lifetime, in days.
`AutoRenewBeforeDays`	`7`	Renew agent certificates this many days before expiry.
`KeySize`	`2048`	Agent certificate key size, in bits.
`RootCaKeySize`	`4096`	Root CA key size, in bits.
`EnableAutoRenewal`	`true`	Run the automatic renewal job.
`AutoRenewalCheckIntervalHours`	`6`	How often the renewal job runs, in hours.

Authentication (JWT)#

The Jwt section configures the tokens issued to the web console.

Key	Default	Notes
`Secret`	—	Signing secret. Environment variable only (`Jwt__Secret`).
`Issuer`	`Athena`	Token issuer claim.
`Audience`	`Athena`	Token audience claim.
`ExpirationMinutes`	`15`	Access token lifetime, in minutes.

Security#

The Security section controls session, lockout, rate-limiting and password rules.

Key	Default	Notes
`SessionTimeoutMinutes`	`3`	Idle session timeout, in minutes.
`MaxFailedLoginAttempts`	`5`	Failed sign-ins before lockout.
`LockoutDurationMinutes`	`15`	How long an account stays locked, in minutes.
`HardLockThreshold`	`30`	Failed attempts before a hard lock.
`MaxRequestsPerMinutePerIp`	`10`	Per-IP request ceiling, per minute.
`EnableJwtSecretRotation`	`true`	Rotate the JWT signing secret automatically.
`AgentTokenValidityDays`	`90`	Agent token lifetime, in days.

PasswordPolicy#

Key	Default
`MinimumLength`	`8`
`RequireUppercase`	`true`
`RequireLowercase`	`true`
`RequireDigit`	`true`
`RequireSpecialCharacter`	`false`

An Admin can review and change the session, lockout, and password-policy values from the console or API without editing this file — see Security Settings.

ConnectionRateLimit#

Key	Default	Notes
`PermitLimit`	`20`	Connections permitted per window.
`WindowSeconds`	`60`	Rate-limit window, in seconds.

Audit#

The Audit section controls the audit trail sink and optional syslog forwarding.

Key	Default	Notes
`Provider`	`File`	Audit sink.
`Directory`	`AuditLogs`	Directory for audit log files.
`FilePrefix`	`audit`	Filename prefix for audit logs.
`BufferSize`	—	Write buffer size.

Syslog#

Key	Default	Notes
`Enabled`	`false`	Forward audit events to syslog.
`Host`	—	Syslog collector host.
`Port`	`514`	Syslog port.
`Transport`	`Udp`	Transport protocol: `Udp`, `Tcp`, or `TcpTls` (TLS 1.2/1.3, RFC 5425; usually port `6514`).
`Format`	`Rfc5424`	Syslog message format.
`Facility`	`16`	Syslog facility code.
`BufferSize`	`10`	Syslog send buffer size.
`TlsCaCertificatePem`	—	`TcpTls` only. PEM of the CA that issued the collector's certificate; when set, only this CA is trusted. Empty = the OS trust store.
`TlsSkipCertificateValidation`	`false`	`TcpTls` only. Lab use only — skips checking the collector's certificate.

For forwarding to a SIEM, see Audit & SIEM and Encrypting forwarding with TLS.

Packages & recording#

Packages#

Key	Default	Notes
`StoragePath`	`./packages`	Where uploaded deployment packages are stored.
`MaxUploadSizeGB`	`15`	Maximum package upload size, in gigabytes.
`BaseUrl`	—	Externally reachable URL agents use to fetch packages.
`TokenSecret`	—	Secret used to sign package download tokens.

Recording#

Key	Default	Notes
`Enabled`	—	Record remote sessions.
`StoragePath`	`./recordings`	Where session recordings are stored.
`RetentionDays`	`30`	How long recordings are kept, in days.
`MaxSessionSizeMB`	`2048`	Maximum recording size per session, in megabytes.

Remote session#

The RemoteSession section controls remote desktop and command sessions.

Key	Default	Notes
`EnableHelperLaunch`	`true`	Allow launching the remote helper.
`MaxSessionDurationMinutes`	`120`	Maximum session length, in minutes.
`ReconnectWindowSeconds`	`30`	Window to reconnect a dropped session, in seconds.
`WebRtcEnabled`	`true`	Use WebRTC for the media channel.

Turn (coturn)#

Key	Default	Notes
`Scheme`	`turn`	TURN URI scheme.
`Host`	—	coturn host.
`Port`	`3478`	coturn port.
`Transport`	`udp`	TURN transport.
`CredentialTtlSeconds`	`600`	Lifetime of generated TURN credentials, in seconds.
`StaticAuthSecret`	—	Environment variable only (`RemoteSession__Turn__StaticAuthSecret`).

For the operator-facing workflow, see Remote Commands & Desktop.

Other settings#

Localization#

Key	Default
`Language`	`en`
`SupportedLanguages`	`["en"]`

DefaultAdmin#

Key	Default	Notes
`Username`	`admin`	Seeded administrator username.
`Password`	—	Initial password — change on first sign-in.
`DisplayName`	—	Administrator display name.
`Email`	—	Administrator email address.

Scheduler#

Key	Default
`CronBuilderMode`	`Visual`
`DefaultDeploymentTimeoutMinutes`	`120`

Swagger#

Key	Default
`Enabled`	`true`
`RoutePrefix`	`api-docs`
`Title`	`Athena Deploy Center API`

General#

Key	Default
`ApplicationName`	`Athena Deploy Center`
`DefaultPageSize`	`10`
`DashboardRefreshInterval`	`10`

Logging#

Key	Default
`Directory`	`Logs`
`RetentionDays`	`30`

Minimal example#

A minimal appsettings.json with the most common sections. Keep real secret values out of this file — supply them via environment variables.

{
  "Database": {
    "Provider": "Sqlite",
    "ConnectionString": "Data Source=athena.db"
  },
  "Server": {
    "WebPort": 8443,
    "ApiPort": 8444,
    "TlsEnabled": true,
    "WebCertPath": "/app/certs/server.pfx",
    "PublicUrl": "https://athena.example.com:8443"
  },
  "Jwt": {
    "Secret": "<set via Jwt__Secret env var>",
    "Issuer": "Athena",
    "Audience": "Athena",
    "ExpirationMinutes": 15
  },
  "DefaultAdmin": {
    "Username": "admin",
    "Password": "<change on first sign-in>",
    "DisplayName": "Administrator",
    "Email": "admin@example.com"
  }
}