Docs / Integrations & settings

Updated July 29, 2026 · ~8 min read

Settings, AI models & API keys

Settings is one menu, not a maze. It holds the GitHub connection, the AI model choices, notifications, the API keys vault, the light and dark toggle, the interface language, and Sign out - every account and preference surface Heygents has.

Where settings live

On desktop, Settings is a nav item in the left rail; clicking it opens a dropdown with GitHub, AI settings, Notifications, API keys, the Dark/Light appearance toggle and Sign out. On a phone the rail is hidden, so the same dropdown lives behind the hamburger button pinned to the far left of the header. You can also reach every settings surface from the command palette with Cmd-K or Ctrl-K - type "AI settings" or "API keys" and press Enter.

AI settings: a provider and model per touchpoint

Heygents talks to AI in several distinct places, and they have genuinely different requirements. Naming a chat needs a fast, cheap model. A Deep Scan across a whole codebase wants your strongest one. The AI settings panel lets you assign a provider and model to each place independently:

• Chat - ordinary conversations in the dock.
• Deep Scan - the grounded audit that generates and refreshes a project's task list.
• Fix from a task card - the run launched when you ask Heygents to actually complete a task.
• Task explanation - the plain-Hebrew explainer behind the "what does this mean?" button on each task card. It defaults to a fast Codex model and can be reassigned like any other row.
• Project details - the generated description and metadata for a project.
• Chat subject - the three to four word title given to every new chat. It defaults to Claude Haiku, because it is a one-shot call fired the moment you send your first message.

Below those rows sits a Default model per provider section: one picker each for Claude, Codex and Gemini, setting what that provider falls back to when a specific row has no model chosen. This is what the chat picker and the Plan sections use when you have not overridden anything. If a stored value is no longer a valid model, Heygents quietly falls back to its built-in default rather than failing the run.

These choices are stored in your browser, so they are per person rather than per server. There is no standing-instructions box: an ordinary chat turn carries no custom system prompt and runs with the plain default persona of whichever provider is active. If you want a run steered, say so in the message, or set an audit brief on a Scan automation.

Choosing between Claude, Codex and Gemini

The provider is always your explicit choice. Clicking Claude, Codex or Gemini in the chat composer switches immediately and starts a fresh provider-specific conversation, so session identifiers are never mixed between providers. Existing conversations stay on the provider they started with, which keeps them resumable. Heygents does not silently reroute you based on rate-limit usage - an earlier version did, and it fought against explicit choices, so it was removed. The usage bars in the header are for information only.

For Claude and Codex you can also set an agent mode - Manual, Edit automatically, Plan or Auto - and a reasoning effort of Low, Medium or High, all from the same compact selector in the composer. Gemini has neither, so its popover shows the provider and model alone. Every choice is remembered per provider.

Appearance: dark and light

The Dark/Light toggle sits directly in the Settings dropdown, and there is a matching entry in the command palette. Flipping it from either place keeps both in sync, so the menu never shows the wrong state. Your choice is remembered in the browser and applies immediately with no reload.

Language: English, Hebrew and right-to-left

The interface ships in full English and Hebrew and defaults to English. Language is a stored per-user preference rather than a browser setting, so it follows your account.

Switching to Hebrew flips the entire layout to right-to-left, not just the text. The stylesheet is built on logical properties, so margins, alignment and panel edges mirror properly instead of breaking. Two things stay left-to-right in every language, deliberately: code blocks and terminal output, because reversing them would make them unreadable.

A few details worth knowing:

• Chat language is frozen per conversation. A chat's language is set once from your first message and never changes afterwards. Toggling the interface language mid-conversation does not retarget a chat that is already running. That language becomes a "respond in Hebrew" or "respond in English" instruction on the prompt sent to all three providers.
• Chat messages are never machine-translated. What the model wrote is what you see.
• Stable content is translated lazily and cached. Project goals and roadmaps, task titles and details, and notes are translated on demand and cached, so the second view is instant. An edited source string simply misses the cache and gets retranslated.
• Notification text follows your language. Push notification bodies are rendered in whichever language you have stored, at the moment they are sent.

The API keys vault

Settings → API keys is one place to define every third-party credential Heygents knows about - Anthropic, Gemini, OpenAI/Codex, a GitHub token, plus free-form custom entries for things like Supabase, Telegram or a webhook secret. It exists so you are not hand-editing server configuration files and restarting for each one.

The single most important thing to understand: keys stored here are stored, not spent. Saving an Anthropic or Gemini key does not change how Heygents' own AI runs authenticate. Chat turns, Deep Scans, automations and the interactive terminal all keep running on the free subscription or OAuth login of the installed command-line tools, and provider API keys are actively stripped from every one of those spawns. That is a deliberate safety property: it means Heygents can never quietly start billing a metered API behind your back. The vault is for explicit, user-initiated uses - installing a companion agent, running a connection test, or copying a value into another tool.

On secrecy:

• Values are written to a permissions-restricted file on the server and are never committed to source control.
• The full value never leaves the server. The panel only ever receives a mask such as sk-ant…4f2a, and leaving a row untouched saves as "keep what you have". Removing a key is an explicit action, not an accidental blank save.
• Because the browser never holds the value, the Test button runs server-side: one read-only authenticated call to the provider, reporting only accepted or rejected.
• The GitHub row here is a standalone personal access token. The live connection Heygents actually uses to clone repositories and open pull requests is the OAuth one under Settings → GitHub.

Authentication and signing out

Heygents is a multi-tenant product, so sign-in is a real account rather than a shared secret. When you are signed out the app shows its landing page with a sign-in card offering three routes to the same account: email and password, Continue with Google, and Continue with GitHub. Accounts are managed by Supabase's auth service, and the beta is invite-only, so an email that has not been invited is refused rather than signed up.

A successful sign-in hands the browser a short-lived access token plus a long-lived refresh token, both kept in your own browser's storage. The access token is attached to every request the app makes, and it is silently exchanged for a fresh one when it expires - which is why a session survives tabs and restarts instead of dying on a timer. If the refresh fails, the next request returns an authorization error and the sign-in card reappears automatically, so you are never left staring at a half-loaded page.

The gate covers the data endpoints, uploaded files and the interactive terminal connection, and every request is scoped to your own account: one tenant can never read another's projects, chats or files.

"Forgot password?" on the sign-in card sends a reset link. It is throttled to one send every 30 seconds and always shows the same neutral message whether or not an account exists for that address, so it cannot be used to find out who has one. The link, like an invite link, opens a set-a-password panel; passwords must be at least 8 characters.

Sign out lives at the bottom of the Settings dropdown and clears the stored tokens, returning you to the sign-in card.

One thing that is not part of signing in: the companion agent's pairing token. That is a separate per-machine credential created from Install agent, and it authenticates a machine to your account rather than you to the app. See Installing the companion agent.

Frequently asked questions

Do my model choices apply to everyone using Heygents?

No. AI model selections, theme and sound preferences are stored in your own browser, so they are per person rather than per server. Language is a stored per-user preference instead, so it follows your account rather than the machine. There is no standing-instructions box either: an ordinary chat turn carries no custom system prompt.

Will saving an API key make my runs use it?

No. Keys stored in the vault are stored, not spent. Chat turns, Deep Scans, automations and the interactive terminal all keep running on the free subscription or OAuth login of the installed command-line tools, and provider API keys are actively stripped from every one of those spawns, so Heygents can never quietly start billing a metered API.

Can I use a different model for scans than for chat?

Yes, that is exactly what the AI settings panel is for. Each touchpoint has its own provider and model row: chat, Deep Scan, fix from a task card, task explanation, project details and chat subject. Below them, a default model per provider sets what Claude, Codex or Gemini falls back to when a row has no model chosen.