Configuration

Atlas keeps the helper's identity and connection paths in a small TOML settings file. Guided setup writes it for you. Use atlas config to see the file and resolved paths Atlas is using before changing anything.

Which settings file is used

Atlas chooses configuration in this order:

1. An explicit --config FILE argument.
2. ATLAS_CONFIG, if set.
3. For an installed executable inside Atlas.app, ~/.config/atlas.toml.
4. For a development executable, an existing atlas.local.toml in the current directory, otherwise the installed settings path.

An installed Atlas does not pick up a local settings file merely because you ran it from a project directory. A development executable also notices a legacy atlas.local.json, so it can report that the configuration needs migration rather than silently using different settings.

For a file you already maintain, inspect it explicitly:

atlas --config ./atlas.local.toml config

This reads the file; it does not create it or set up another helper. For normal first-time setup, use Getting started.

Settings fields

There are five supported keys. Unknown keys are rejected, and the file must be UTF-8 TOML no larger than 16 KiB.

Only output_dir has a parser default: runs, relative to the settings file. The other four keys are required. <helper-home> and <uid> above are placeholders, not text to put in the file.

The example configuration documents the keys for development. Its UID 502, /tmp socket paths and local runs directory are examples, not universal installation defaults. Do not copy its helper identity into an existing installation. atlas setup --helper NAME can inspect a proposed setup for an existing account; replace NAME with that account's short name.

How paths resolve

Relative paths resolve against the configuration file's directory, not the shell's current directory. A ~/ prefix expands to the invoking account's home. Atlas normally obtains that home from macOS's account record, so changing the shell's HOME does not redirect its main settings and control records.

Atlas resolves existing path parents, including symbolic links. For identity_probe, it preserves the final path entry because installation may replace that link. Empty paths and paths containing a NUL are rejected. These settings identify real services and storage; they are not a way to bypass account or session checks.

JSON configuration is no longer read. If a .json file with the same basename sits beside a .toml settings file, Atlas refuses the combination. Confirm the TOML values and stop any old process using the JSON file before removing the obsolete file.

Where data lives

In this table, ~ means your own account unless the helper is named explicitly.

Viewer and Settings preferences use macOS user defaults separately from the TOML file. These include picture rate, Details visibility, the mini-screen corner, the last Settings tab and notification preference.

Do not clear control locks or pending-action records to get past a failure. They keep another process from acting before Atlas knows what happened. Use recovery, and check maintenance before deleting installation data.

Supported environment options

These options affect the command or installer in your account. They do not automatically become variables in helper apps. To select helper variables, use an environment profile.

Changing download options does not create a release or make an unsigned development app a supported helper installation.