Atlas Configuration Reference

Overview#

This article lists every setting Timebase Atlas reads, where each one lives, what it defaults to, and whether a change needs a restart. Use it when you are installing Atlas, moving it to a new host, pointing it at a different Timebase Pulse, or trying to work out why an edit you made had no effect.

Atlas is a single component: one container (or one Windows service) serving both the browser interface and the API from the same process. There is no separate user interface process and no separate settings file for one.

Almost everything you will change lives in one file, settings.config, in the Atlas Settings folder. Atlas writes that file for you on first start. A handful of values (the folder paths themselves, and the environment name) can only be supplied as environment variables or command-line arguments, because Atlas has to know where to look before it can read any file.

Where settings come from, and which one wins#

Atlas loads its configuration from six places. Later entries in this list override earlier ones for the same key.

The file carries a version. settings.config opens with "version": "1.0.0", and Atlas migrates an older file forward when it starts. See Configuration file versions and upgrades.

Important: an environment variable takes precedence over the settings file. Where a key is set both in settings.config and as an environment variable in docker-compose.yml, the environment variable is the one in effect, and a command-line argument outranks both. A value in the file holds only where nothing outranks it, so when a change in the file seems ignored, look for a matching environment: entry first.

The exception: the Settings folder itself#

The Settings path cannot come from settings.config, because Atlas has to resolve that path before it can find the file. It is read from appsettings.json, an environment variable, or the command line only.

The Data, Logs and Certificates paths are resolved later, over the complete stack, so a value for one of those in settings.config would beat the environment variable in the normal way.

How the files are created#

On first start Atlas writes settings.config into the Settings folder from a copy embedded in the program, then writes the matching settings.{Environment}.config overlay if one is embedded for that environment. Both are loaded with file watching switched on, so Atlas notices an edit immediately, but only one section actually acts on it without a restart (see Which changes need a restart).

If Atlas cannot create those files it prints a fatal error naming the path it could not initialise and stops.

Ports and addresses#

Atlas redirects every plain HTTP request to HTTPS, so both ports must be published for the interface to be reachable. The Compose file in Start Here for Docker publishes both.

Everything Atlas serves is on the same two ports. There is no second port and no second process.

If you are writing firewall or reverse-proxy rules, all of the above must reach the same host and port.

Environment variables#

Only the folder paths and the environment name are usefully set as environment variables. Everything else belongs in settings.config.

The platform Compose file in Start Here for Docker sets Config=/atlas/config, Settings=/atlas/settings, Logs=/atlas/logs, Certificates=/atlas/certificates and Data=/atlas/data, all inside the named volume atlas.

Environment variables Atlas does not read#

Two of these turn up often enough to be worth naming, because setting them looks like it should work:

Kestrel (the web server)#

Section Kestrel in settings.config.

Request limits#

Section Kestrel:Limits. Every key here is optional. A key you do not set keeps the web server's own default, with the one exception noted below.

Authentication#

Section Pulse:Auth in settings.config. Pulse is the Timebase component that checks credentials.

Atlas's OAuth client lives inside the Pulse section, alongside the address of the Pulse it authenticates against. There is no separate identity-provider address to keep in step with it.

Warning: the shipped empty Pulse:Auth:ClientSecret does not work, and this is the most common first-run failure. Pulse seeds an Atlas client for you on its first start, so you do not need to create one. But it generates that client's secret as a random GUID, and Pulse compares secrets exactly - an empty string never matches. A default Atlas paired with a fresh Pulse therefore fails to obtain a token, and the assistant and licensing stay unavailable until you either read the generated secret out of Pulse or rotate it to a value you choose, and put that value here.

In Docker or compose this is an ordering problem: the secret does not exist until Pulse has started. Start Pulse first, set the secret, then start Atlas. Atlas does not recover on its own once it has failed, so restart it after the secret is in place. See Registering Timebase apps as OAuth clients in Pulse (pulse-oauth-clients.md).

Pulse connection#

Section Pulse in settings.config. One block, three consumers: licensing, certificates, and the assistant. Changing Pulse:Host moves all three at once.

Certificates#

When Pulse:Cert:Enabled is true and an HTTPS endpoint is configured, Atlas checks for a valid certificate before the web server starts and generates a self-signed one if it needs to. The generated file is timebase-generated.pfx in the Certificates folder. Once Pulse is reachable, Atlas also syncs the Pulse certificate authority so browsers stop warning.

Setting Pulse:Cert:Enabled to false turns the whole mechanism off, including the hot reload, so you must then supply Kestrel:Endpoints:Https:Certificate:Path yourself.

Licensing#

Atlas acquires its licence through Pulse, using the same Pulse:Host / Pulse:Port / Pulse:UseTls values and the existing Pulse:Auth:ClientId client. There is no separate licensing setting to fill in.

Licensing does not gate any API call. It is read-only visibility, shown in the interface. You do not need a licence to call the API.

The assistant#

Atlas's assistant runs on models served by your Pulse instance through Gage. Atlas never declares a model, a provider, an endpoint or an API key of its own. The model catalogue comes from Pulse.

Everything in this section switches the assistant on and points it at Pulse. The providers, API keys and model handles themselves are configured in Pulse, and none of the settings below will produce a working assistant on their own. See Configuring Gage LLM providers and models (pulse-gage-providers.md), and note that Gage ships hard token quotas by default rather than unlimited access.

Gage#

Section Pulse:Gage in settings.config.

Everything else the assistant needs is derived from settings you have already made: the Pulse address from Pulse:Host / Pulse:Port / Pulse:UseTls, and the credentials from Pulse:Auth:ClientId and Pulse:Auth:ClientSecret.

Assistant guardrails#

Section Pulse:Gage:Guardrails. Shipped commented out in settings.config; the defaults below apply whether or not you uncomment it.

Dictation#

Section Pulse:Gage:Dictation. Speech-to-text runs on the Atlas server; audio never leaves your infrastructure. The small.en model is built into the Docker image and into the Windows installation, so dictation works with no extra setup.

Each of the numeric keys above stops Atlas from starting when set to a nonsensical value, with a message naming the key, for example Pulse:Gage:Dictation:ThreadCount must be a positive integer..

Assistant resilience#

Section Pulse:Gage:Resilience. Advanced; leave these alone unless you are diagnosing a specific problem.

0 switches a knob off. A value outside the range 0.001 to 86400 seconds stops Atlas from starting.

Live values#

Section LiveProjection in settings.config.

This is the global fallback. A connector may declare its own tolerance per binding path when it accepts a subscription, and that value wins over this one.

Startup behaviour#

Section Compilation in settings.config. Not present in the shipped file; add it if you need to change the default.

Atlas remembers which domains were compiled in compiled-worlds.json in the Config folder. This setting is what explains the burst of processor activity shortly after a restart, and why domains are queryable straight away without a manual recompile. A domain that reads live data from a connector is the exception: it waits for its connector to report in.

Draft sessions#

Section Atlas:DraftSessions in settings.config. Not present in the shipped file.

Git#

Section Git in settings.config. Not present in the shipped file.

A repository Atlas creates for you is initialised on main.

The i3X surface#

Section I3x in settings.config. Not present in the shipped file. Only relevant if another system reads Atlas over the i3X interoperability standard.

Logging#

Section Serilog in settings.config.

Log messages go to three places at once: the console, the live log view in the browser interface, and daily files in the Logs folder. Files roll every day and the last seven are kept.

Other settings#

FunctionLibraries lives in appsettings.json as an empty block and can be set in settings.config like any other key. Verified and appsettings.json. Leave it empty unless your functions need an external library.

Example:

{
  "FunctionLibraries": {
    "MyMathLib": "/atlas/data/libs/MyMathLibrary.dll"
  }
}

Secrets#

Two values in the configuration are sensitive.

The Certificates folder holds the private key for the certificate Atlas generates, in timebase-generated.pfx, plus its password file. On Windows the password file is encrypted for the local machine; on Linux it is written with owner-only permissions. Restrict access to that folder.

What is in the Config and Data folders#

You can stop Atlas, delete the Data folder and restart without losing any configuration, because everything you author lives under Config.

Config is the Git-backed store (the Config key; /atlas/config in Docker).

Data holds machine-owned state only (the Data key; /atlas/data in Docker).

Deleting Data loses chat history and uploads and mints the licensing serial again. It does not affect compilation: the boot recompile reads compiled-worlds.json from Config, so domains come back by themselves after a restart whether or not Data was wiped.

In 2.0.0 sessions/, threads/ and exports/ sat under Config. From the next release they live under Agent/ in Data, and the first start after upgrading moves them there, once; a folder is left where it is if the destination already exists.

Model changes are committed to the repository, but a save that fails validation goes to a private draft instead and does not advance the branch. See Draft sessions.

Which changes need a restart#

Only one section acts on an edit without a restart: Pulse:Gage:Guardrails, which takes effect on the assistant's very next tool call.

Every other section listed in this article is read once when Atlas starts. Atlas watches the settings files and reloads the values into memory, but the components that use them keep the values they were given at startup. Restart Atlas after any other change.

Troubleshooting#

Related articles#

• Start Here for Docker: How to Deploy and Secure Timebase 2.0
• Timebase Atlas Key Concepts
• Atlas API Overview
• Setting up Timebase Pulse
• Registering Timebase apps as OAuth clients in Pulse
• Configuring Gage LLM providers and models
• Certificates and trust across Timebase