Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.halite-app.com/llms.txt

Use this file to discover all available pages before exploring further.

The Settings page is where you connect Halite to your Salt master and tune background poller intervals. All settings are stored in the database (the singleton AppSettings row) and take effect immediately without a container restart — saving a change calls runtime.reload(), which tears down the existing Salt client and schedulers and rebuilds them from the new values.
The Settings page is restricted to users with the edit:settings:* permission. Only the built-in admin role has this permission.
Settings form with Salt API URL, username, eauth, TLS verify toggle, and poller interval fields

​
Salt API connection

These fields configure how Halite authenticates to salt-api.
​
url
URL
The full URL of your salt-api instance, including scheme and port (e.g. https://salt.internal:8000). Clearing this field disables the Salt connection — all background schedulers stop and salt-backed endpoints return empty or degraded responses.
​
username
string
The Salt service account username. Maximum 255 characters.
​
password
string (write-only)
The service account password. The password is encrypted at rest using the server’s COOKIE_SECRET and is never returned by the API — only a boolean password_set flag is returned so the UI can show (set) without exposing the value.
​
eauth
string
default:"pam"
The Salt external auth backend. Accepted values: pam, sharedsecret, ldap, file, auto.
​
verify
boolean
default:"true"
Whether to verify the salt-api TLS certificate. Set to false only if your salt-api uses a self-signed certificate and you accept the risk.

​
Testing the connection

Before saving, click Test Connection to validate the credentials without persisting them (POST /api/admin/settings/test-salt). The response includes ok, a detail message, and a minion_count when manage.present succeeds. You can also test the currently-saved credentials with POST /api/admin/settings/test-salt-saved (the password is read from the database, not re-entered).

​
Poller intervals

These fields control how often background tasks run. Set any interval to 0 to disable that scheduler.
​
inventory_refresh_minutes
integer
default:"0"
How often (in minutes) the inventory scheduler collects pkg.list_pkgs from the entire fleet. 0 disables the scheduler. Range: 0–1440.
​
inventory_refresh_initial_delay_s
integer
default:"30"
Seconds to wait after startup before the first inventory collection run. Range: 0–3600.
​
fleet_poll_interval_seconds
integer
default:"0"
How often (in seconds) the fleet scheduler looks for new state.* JIDs and ingests highstate results. 0 disables. Range: 0–86400.
​
jobs_poll_interval_seconds
integer
default:"0"
How often (in seconds) the jobs scheduler polls for new job index entries. 0 disables. Range: 0–86400.
​
minion_state_keys_interval_seconds
integer
default:"300"
How often (in seconds) the minion scheduler refreshes key state for all minions. Range: 0–86400.
​
minion_state_presence_interval_seconds
integer
default:"60"
How often (in seconds) the minion scheduler refreshes online/offline presence via manage.present. Range: 0–86400.
​
minion_state_grains_interval_seconds
integer
default:"300"
How often (in seconds) the minion scheduler refreshes grains for accepted online minions. Range: 0–86400.
​
minion_state_initial_delay_seconds
integer
default:"10"
Seconds to wait after startup before the minion scheduler’s first tick. Range: 0–3600.

​
Event stream

The Event stream controls live at the bottom of the Pollers section. They drive the Activity feed, which tails the Salt event bus instead of polling. Saving the Pollers section calls runtime.reload(), so toggling the stream starts or stops the event consumer with no restart.
​
event_stream_enabled
boolean
default:"false"
Master switch for the live event stream. When on, Halite holds a long-lived connection to salt-api’s /events endpoint, captures job / key / minion events, stores them, and exposes them via the Activity page and SSE stream. When off, no events are captured and the Activity page is empty.
​
event_stream_retention_days
integer
default:"30"
How many days of captured events to keep. The event consumer prunes rows older than this. Range: 1–365.

​
Activity widget

These fields configure the Recent activity widget on the Overview dashboard. They are display-only — saving this section does not trigger a runtime.reload(), and the values are readable by every authenticated user (via GET /api/activity/widget-config) so the widget renders the same way for everyone.
​
widget_hide_dispatch
boolean
default:"true"
Hide job dispatch (job.new) events from the widget, leaving only completions and outcomes.
​
widget_hide_routine
boolean
default:"false"
Hide routine successes — successful job returns that made no changes.
​
widget_show_jobs
boolean
default:"true"
Include job events in the widget.
​
widget_show_keys
boolean
default:"true"
Include key events in the widget.
​
widget_show_minions
boolean
default:"true"
Include minion events in the widget.
​
widget_event_count
integer
default:"6"
How many events to list in the widget. Range: 1–50.
​
widget_heartbeat_minutes
integer
default:"60"
The time window (in minutes) the heartbeat indicator counts events over. Range: 5–1440.

​
Logging

​
log_format
string
default:"json"
The backend log format. Accepted values: json (structured JSON lines, best for log aggregators) or text (human-readable). Note that current builds initialize logging with a hardcoded json format at startup, so this setting is not applied to the running process — a container restart would be required once it is wired up.

​
How live reload works

When you save the Salt or Pollers sections, Halite calls runtime.reload(db) to rewire the live Salt client, schedulers, and event consumer with no restart. Saving the Activity widget or Logging sections does not trigger a reload — those are display-only.
  1. All running schedulers (minion, fleet, inventory, jobs) and the event consumer are cancelled and awaited.
  2. The Salt client is closed.
  3. The AppSettings row is re-read from the database.
  4. If salt_api_url, salt_api_username, and the decrypted password are all present, a new SaltAPIClient is created and logged in.
  5. Any schedulers whose interval is > 0 are started fresh with the new settings, and — if event_stream_enabled is on — the event consumer is started.
If the Salt credentials are incomplete or the login fails, the client remains None and all schedulers stay stopped. Salt-backed endpoints (minion presence, job dispatch, inventory refresh, etc.) degrade gracefully — they return empty results rather than hard-failing.

​
Walkthrough: connecting to a Salt master

1

Open Settings

Click Settings in the left sidebar. You need the admin role.
2

Enter the Salt API URL

In the Salt API section, enter the full URL of your salt-api instance, e.g. https://salt.example.com:8000.
3

Enter credentials

Enter the service account username and password. Set eauth to the backend your Salt master uses (typically pam). If your salt-api uses a self-signed certificate, toggle Verify TLS off.
4

Test the connection

Click Test Connection. If the status shows ok: true with a minion count, the credentials are valid.
5

Save

Click Save Salt Settings. Halite immediately re-wires the live Salt client — you do not need to restart.
6

Enable pollers (optional)

In the Pollers section, set non-zero values for the schedulers you want. For example, set minion_state_presence_interval_seconds = 60 to get live online/offline status every minute. Click Save Poller Settings.

​
Permissions

RouteRequired permission
GET /api/admin/settings/statusAuthenticated session only
GET /api/admin/settingsedit:settings:*
PUT /api/admin/settings/saltedit:settings:*
PUT /api/admin/settings/pollersedit:settings:*
PUT /api/admin/settings/widgetedit:settings:*
GET /api/activity/widget-configAuthenticated session only
PUT /api/admin/settings/loggingedit:settings:*
POST /api/admin/settings/test-saltedit:settings:*
POST /api/admin/settings/test-salt-savededit:settings:*