API Keys

Paste an OpenAI key into Settings so the in-process engine can answer the first message

Paste an OpenAI key into the Settings screen and the in-process engine picks it up on the very next message — no relaunch, and the key never touches the settings file.

How a new user finds out a key is needed

First-launch “no key” guidance now happens on the chat screen, before any message is sent.

Before this, opening the app on a fresh install rendered a blank rectangle, and the only “no key” signal was the raw provider prose The OPENAI_API_KEY environment variable is missing or empty, shown after the user tapped Send.

The chat screen now shows an “Add an API key to start” panel with an “Open settings” button before any message is sent — see Empty Chat.

Quick Start

1. Open Settings and find the OpenAI API key row

   The OpenAI API key row is the lead section on the screen, in its own API key heading above Engine. It shows Not set and a masked field. The Remove button appears only once a key is actually stored (canClear), so a “Not set” row has no button under it. On a platform without a hardware keychain (the web adapter, where isHardwareBacked === false), a warning above the rows says secrets are kept in app memory.

2. Paste your key

   Paste the key into the masked field and blur it or press Enter. The row flips to Configured, the field returns to its placeholder, and nothing is echoed back.

3. Send the very next message

   No relaunch. The in-process engine reads the key on every turn, so the next message you send is authenticated.

   Ask anything — the first reply arrives.

4. Rotate or revoke

   To rotate, paste a new value over the old one — the replacement also survives a restart. To revoke, press Remove (shown only while the row is Configured) — the row returns to Not set, the button disappears in the same pass, and the keychain entry is gone.

How It Works

A pasted key is committed as a set-secret intent, written straight to SecretsPort, and read back by the engine on the next turn.

The field carries data-action="set-secret" and its key; a root-delegated change listener decodes it through intentFrom and calls facade.setSecret(ref, value). On the next turn, createInProcessEngine calls apiKeyFor(secrets, settings.defs()) and builds the agent with the key it finds.

Where set(ref, value) lands depends on the platform, both reached through src-tauri/plugins/secrets:

What the field does and does NOT do

The masked field is governed by three rules from secretControls in app/src/main.ts, and each has a broken version that looks completely normal on screen.

Configuration Options

The row is declared by one SettingDef in SETTING_DEFS (source: app/src/registry.ts).

{
  key: "openaiApiKey",
  default: "",
  label: "OpenAI API key",
  help: "The in-process engine signs its requests with this. It is kept in the platform secret store, never in the settings file, and never shown back to you.",
  section: SECTION_API_KEY, // "API key" — the lead section, above "Engine"
  secret: true,
  secretRef: { slot: "openai", account: "default" },
}

Common Patterns

An empty commit is refused, and the value is trimmed — from intentFrom in app/src/intents.ts.

// A cleared field on blur does NOT delete the key:
intentFrom([{ dataset: { action: "set-secret", settingKey: "openaiApiKey" }, value: "   " }]);
// → null  (raw.trim() === "" is refused)

// Removing a credential must be asked for by name, via the Remove button:
intentFrom([{ dataset: { action: "clear-secret", settingKey: "openaiApiKey" } }]);
// → { kind: "clear-secret", key: "openaiApiKey" }

The engine reads the key on every turn, not at boot — from createInProcessEngine in app/src/main.ts.

const apiKey = await apiKeyFor(secrets, settings.defs());
return new Agent({
  instructions: "You are a helpful assistant.",
  llm: "gpt-4o-mini",
  // Omitted, never passed as "" or null, when unset:
  ...(apiKey === null ? {} : { apiKey }),
});

The engine is built once and held for the session, so a construction-time read would need a force-quit to pick up a pasted key. enginesFor already learned this with baseUrl, and it is worse for a credential — the failure it produces is the same missing-key error the user was trying to clear.

Best Practices

Related