How Frost works
Activity & logs
Every refresh is recorded as a run: three steps, their status, what each one found, and the exact error if it failed. Nothing about it leaves your machine.
Runs
The Activity page lists refresh runs newest first. Each row carries when the run started, how long it took, and its status:
- in progress — running right now; the page updates as steps complete;
- success — the token was obtained, profiles written and the EKS scan finished;
- error — something failed; the run carries the error text.
Open a run to see it step by step. A live run can be watched from this view — steps appear as they start and fill in as they complete.
What each step records
Token
Whether the sign-in succeeded, and the error if it did not — a closed login window, an expired device code, or an AWS exception with its name, HTTP status and request id.
Profiles
Every account the token can reach, with its account id, and for each one
the permission sets it holds and the profile name Frost generated. This
is the record of what your ~/.aws/config should look like
after the run.
EKS
The scan results grouped by region: the clusters found, which profile found them, and a count of the regions that returned access errors. Access errors are normal — most profiles have no EKS access — so they are summarised rather than listed as failures. EKS discovery →
How long runs are kept
Run history is pruned to the retention period set on the Privacy page — 7 days by default, adjustable between 1 and 30. Pruning happens at startup and immediately when you shorten the period, so a shorter retention takes effect at once rather than at the next refresh.
Delete History on the Privacy page erases every stored run immediately, regardless of the retention period.
Log files
Alongside the run history, Frost writes a debug log — one file per local
day, named main-YYYY-MM-DD.log:
| Platform | Log directory |
|---|---|
| macOS | ~/Library/Logs/Frost/ |
| Windows | %AppData%\Frost\logs\ |
| Linux | ~/.config/Frost/logs/ |
Each file starts with a banner naming the Frost version, the Electron and Node versions, and the platform and architecture — the first thing any bug report needs. The log then follows a run poll by poll, which is what makes a failed sign-in diagnosable after the fact.
Logs age out on the same retention setting as run history, so the file that describes a run and the run itself disappear together. Files written by older versions are swept on the same schedule.
What is and is not recorded
Run history and logs never leave your machine. Frost has no backend, no analytics and no crash reporting — a run record exists so you can read it.
- Recorded: account names and ids, permission set names, generated profile names, cluster names and regions, AWS error names, HTTP statuses and request ids.
- Never recorded: the SSO access token, the OAuth client secret, and the device and user codes from the sign-in — anything holding those could mint a token of its own, so they are deliberately kept out of the log.
Both the log files and Frost's configuration file are written with owner-only permissions. See security & privacy for the full picture.
Reporting a problem
When something goes wrong, the useful pair is the run and the log line for it:
- Open the failing run on the Activity page and note the step it failed in and the error text.
- Open today's log file from the directory above and copy the lines around that time — each run is tagged with its own id, so the relevant lines are easy to isolate.
- Open an issue with both, plus the version from the log banner.
Account names and ids do appear in the log, so review what you paste.