Quick Start: Turn On the AI Assistant

Overview#

Gage is the AI assistant built into Timebase. Every component that offers one - Atlas, Historian, Explorer, Collector - reaches its model through Pulse, which holds the provider credentials, the model catalogue and the usage limits. No component declares a model, a provider or an API key of its own.

That means turning the assistant on is two jobs: configure the model once in Pulse, then point each component at it. This article walks both, in the order the components' own setup card lists them.

A fresh installation ships most of the way there. Pulse seeds an Anthropic provider and one OAuth client per component, and every component ships with the assistant switched on. What is left is the part only you can do:

• your LLM API key, in Pulse (Step 2)
• the component's client secret, which Pulse generates and you copy across (Step 4)

If a component shows you an Agent setup required card, the numbered steps on it match the steps below.

You will need: a running Pulse, an API key from your LLM provider, and administrator access to both Pulse and the component.

Step 1: Confirm authentication and Gage are on#

Gage needs an identified caller, so authentication has to be on. A component with authentication disabled does not offer the assistant at all.

Both switches ship on, so on a fresh installation this is a confirmation rather than an edit. In the component's settings.config:

{
  "Pulse": {
    "Host": "pulse",
    "Port": 4542,
    "UseTls": true,
    "Gage": { "Enabled": true },
    "Auth": {
      "Enabled": true,
      "ClientId": "Explorer",
      "ClientSecret": "<the secret from Pulse>"
    }
  }
}

Both switches are needed: Pulse:Auth:Enabled and Pulse:Gage:Enabled. Turning either one off takes the assistant offline, whatever the other says.

Everything the component needs in order to reach Pulse lives in one Pulse section: the address, the assistant, and the component's own OAuth client. There is no separate identity-provider address to keep in step, because Pulse:Host, Pulse:Port and Pulse:UseTls are the identity provider.

On an upgraded installation, check rather than assume. Upgrading migrates your configuration file forward but never overwrites a value you already had, so a component that had authentication switched off before the upgrade still has it switched off afterwards, whatever a fresh installation of the same version would ship. The same is true of Pulse:Gage, which is not added to an existing file at all. See Configuration File Versions and Upgrades.

Pulse:Gage:Enabled takes effect live. The Pulse:Auth block is read at startup, so restart the component after changing it.

Pulse:Gage is the whole of a component's Gage configuration - Enabled, the optional Agents map from Step 3, and the Guardrails, Dictation and Resilience sections. There is nowhere to put a model, a provider or an API key locally, and nothing to point at your LLM directly.

Step 2: Enter your API key in Pulse#

Sign in to Pulse and open Gage, then Providers. A first-run Pulse already has an Anthropic provider waiting for a key:

Its model handle is therefore anthropic/claude, which is the handle every component's shipped configuration already expects.

It arrives enabled with no key, so the key is the only thing you have to add. Until you add it, the provider cannot answer anything. Its model is already in the catalogue, so every component's setup card ticks Configure a model in Pulse, but your provider refuses every call and the first question fails with an authentication error.

Give it your key#

1. Select the anthropic provider. Its page shows the seeded values above, with the key under Security masked and marked Not set.
2. Under API key, choose Set new key.
3. Paste your Anthropic API key and confirm with Set key.

That is the whole step. The key is write-only: once saved the page shows it as Set and never displays it again. Entering a key never changes whether a provider is enabled, so the seeded provider starts answering as soon as its key is saved, and a provider you have switched off stays off when you give it a new key.

Moving to a different model, or a different provider#

Real Model Id is the field to change to move to a newer Anthropic model. Nothing in any component refers to it, so the change is invisible to the rest of the platform.

To use OpenAI, a local Ollama server or anything else, create a provider of your own alongside the seeded one. A provider carries the credential and the wire format. A logical model gives that provider's real model a stable name of your own:

The handle is the provider Id and the Logical Id, joined by a slash. A provider openai with a Logical Id of smart gives you the handle openai/smart.

Confirm the catalogue is not empty:

GET https://<your-pulse-host>:4542/api/gage/models

Every enabled model of every enabled provider appears here, each with its handle, along with the handle the reserved word default resolves to.

Components do not poll for this. Pulse pushes the catalogue to every Gage-enabled component the moment it changes, and a component re-reads it whenever it connects or reconnects. So enabling a model, disabling one, or changing which is the default reaches every assistant in your installation within seconds, with nothing to restart.

For the full provider reference - non-standard endpoints, fallback between providers, usage logging and key rotation - see Configuring Gage LLM providers and models.

Step 3: Choose which model the assistant uses#

The assistant in Historian, Explorer and Collector is one agent, named gage. This step points it at a model.

There are two ways to do it, and on most installations you only need the first.

Mark a default model in Pulse#

In the provider editor, each logical model carries a Default Model toggle. Turn it on and that model becomes the default for every Gage assistant in the installation - it is the model the reserved word default resolves to on every host.

Three things follow from it being install-wide:

• There is at most one. Marking a model as the default clears the default on every other model, across every provider. You do not clear the old one first.
• It must stay usable. A change that would leave the installation with other models but no usable default is refused, and the message names the model that is blocking it. Move the default by marking another model, rather than by clearing the current one.
• Emptying the catalogue is still allowed. The last usable provider may always be disabled or deleted, because an installation with no models at all has nothing to be inconsistent about.

Until somebody marks one, the default is the alphabetically first handle in the catalogue. With anthropic/claude and openai/smart both enabled, anthropic/claude wins because a sorts before o, and enabling a third model whose handle sorts earlier would move it. That is what an installation upgrading from an earlier release keeps doing, so nothing changes underneath it.

Mark one as soon as you have two models. The fallback is a rule about the alphabet, not a decision anybody made, and it moves when the catalogue changes.

Pin one agent to a specific model#

Marking a default answers "what should everything use". Pinning answers "what should this one use instead". Map the agent name to a handle in the component's Pulse:Gage:Agents, for which the shipped Pulse:Gage block carries a commented example:

"Pulse": {
  "Gage": {
    "Enabled": true,
    "Agents": {
      "gage": "anthropic/claude"
    }
  }
}

Three things about this map:

• The value is the full handle, both halves. A Logical Id on its own does not resolve: the component compares the value against the catalogue's handles exactly, so claude where the catalogue says anthropic/claude reports "names Gage model 'claude', which is not in the catalog pinned from Pulse".
• The key is the agent's name, and it is matched without regard to case.
• An entry here wins over everything else, including a model named in the agent's own definition file. It is the one place an operator retargets any agent, built-in or custom, without editing agent files.

Where an agent is not in the map, Timebase resolves its model in this order:

1. the handle named in the agent's own definition file, then
2. the installation's default model - the one an administrator marked, or the alphabetically first handle where nobody has.

Pin an agent when it needs a different model from everything else - a cheaper model for a high-volume agent, a stronger one for a hard job. Where every agent should use the same model, marking it as the default in Pulse is the better answer: it is one decision in one place, it reaches every component without a configuration edit, and you can read it back from the Pulse interface.

Step 4: Give the component its client secret#

The component authenticates to Pulse with its own OAuth client and exchanges a client_credentials token, then calls the proxy.

The client already exists. Pulse seeds one per component on its first start, so there is nothing to register. What is missing is the secret: Pulse generates a random one per install and does not print it, while the component ships with "ClientSecret": "". An empty string never matches a generated secret, so the token exchange fails until you copy it across.

To connect one:

1. In Pulse, open Clients and select the client named after your component.
2. The secret is masked. Reveal it and use the copy button, or rotate it to a value you choose. Rotating is usually easier in a scripted deployment, because you pick the value in advance.
3. Put that value in the component's Pulse:Auth:ClientSecret, and check Pulse:Auth:ClientId matches the client id above.
4. Restart the component. The Auth block is read at startup.

Do not create a second client by hand. You will either collide with the seeded one or leave an unused registration behind.

Two things to watch:

• Pulse's own assistant needs none of this. Pulse derives its own loopback address and reads its own client secret straight from its client store, so there is nothing to copy and no Gage configuration in Pulse's settings.config at all.
• A deployment that is not on localhost needs the seeded redirect URI changed to the component's real address. The client_credentials exchange the assistant uses does not involve a redirect, but browser sign-in does.

Then confirm Pulse is reachable at the address in Pulse:Host, Pulse:Port and Pulse:UseTls.

For the full client reference, see Registering Timebase apps as OAuth clients in Pulse.

The proxy the component calls is:

POST https://<your-pulse-host>:4542/api/gage/proxy/v1/messages          (Anthropic wire)
POST https://<your-pulse-host>:4542/api/gage/proxy/v1/chat/completions  (OpenAI wire)

You do not call these yourself - the component does. They are listed so you can confirm reachability and recognise them in a log.

Step 5: Add an agent definition, then ask a question#

An agent is a named assistant with its own instructions. A component ships with built-in agents, and you can add your own by dropping a definition into the agents folder under the component's data path, then restarting.

Atlas authors agents through its own Agents page, with no restart needed - see Atlas AI Agents.

Then open the assistant with Ask Gage in the toolbar. A new panel has no conversation yet: the + button in its header opens Start an agent, which lists the built-in agents, and choosing Gage opens it as a conversation tab.

Ask something simple, such as "which datasets do I have?". A working setup answers in prose and, where the agent has tools, says what it did: the run shows a Waiting for response status while it works, then a collapsed Thinking block, one block per tool call with its duration and result, and the answer.

If the answer is an error instead, the next section names it.

Troubleshooting#

Match the message on screen.

When a model is not in the allow-list#

A Gage policy can restrict which model handles a caller may use. Policies exist in two layers, Client and User, and both are checked - a call has to clear each.

Two things about the allow-list are worth knowing before you start editing:

• An empty allow-list allows every model. It is not a deny-all. So the fix is often to clear the list rather than add to it.
• A per-id list replaces the default list, rather than adding to it. A policy on one client id with two handles listed does not inherit the [default] policy's handles as well.

Work through it in this order:

1. Read the client policy for the calling component:

   textCopy

   GET https://<your-pulse-host>:4542/api/gage/client-policies/{clientId}
   

2. Read the reserved [default] client policy, which applies to every client that has no policy of its own:

   textCopy

   GET https://<your-pulse-host>:4542/api/gage/client-policies/[default]
   

3. Read the user policies too, at /api/gage/user-policies/{userId} and /api/gage/user-policies/[default]. A [default] user policy applies to every signed-in user, so one entry there restricts everybody no matter which component is calling.

4. Compare each non-empty AllowedModels against the handle the agent is using, character for character. It is the full providerId/modelId, and a bare model id does not match. If the agent has no pinned handle, it is using the alphabetically first entry in GET /api/gage/models - which may not be the one you allow-listed.

5. Fix it either by adding the handle, or by clearing the list to allow everything:

   textCopy

   PUT https://<your-pulse-host>:4542/api/gage/client-policies/{clientId}
   Content-Type: application/json
   
   { "allowedModels": [] }
   

Related articles#

• Configuring Gage LLM providers and models - the full provider, policy and usage reference
• Setting up Timebase Pulse - first-run Pulse setup
• Registering Timebase apps as OAuth clients in Pulse - the client registration Step 4 needs
• Ask Gage, the Atlas AI Assistant - using the assistant in Atlas
• Atlas AI Agents - the built-in agents and authoring your own
• Component Settings - where settings.config lives for each component