AMBA
✓English
日本語
한국어
Tiếng Việt

English

日本語
한국어
Tiếng Việt

Appearance

🔑 Setting Up AI Model API Keys ​

AMBA pairs your local files and analytical execution engine with frontier cloud intelligence for strategic reasoning. To operate AMBA, you need an API key from at least one supported AI provider.

🔒 Where Your Keys Are Stored: OS Keychain Only ​

IMPORTANT

AMBA stores API keys only in your operating system's keychain:

  • macOS: macOS Keychain.
  • Windows: Windows Credential Manager.
  • Linux: Secret Service over D-Bus (GNOME Keyring, KWallet 5.97 or later, or KeePassXC with Secret Service enabled).

There is no plaintext or database fallback. Keys are not logged and are sent only to the provider they belong to. After saving, AMBA reads the key back and shows success only if the keychain kept it. Pasted keys are trimmed; keys containing line breaks, invisible or non-ASCII characters are rejected.

Linux without a running keyring: saving fails with "No system keychain is available…", and Settings → System Diagnostics shows the keychain as unavailable. Install or enable GNOME Keyring or KWallet and restart AMBA (details).

TIP

macOS asks "AMBA wants to use your confidential information stored in … in your keychain"? AMBA keeps all its keys in one keychain entry and reads it at most once while it runs. Click Always Allow and macOS stops asking; signed updates keep that choice. Development builds you compile yourself ask again after each rebuild, because each build has a new signature. Keys saved by 0.5.11 or earlier move into that single entry the first time they are used, so you may be asked once per old key, one time only.

Which entry, and why "Allow" is not enough. The prompt names the entry AMBA – saved API keys and connections (account amba-vault-v1) — that single entry holds every AMBA key and connection. Entries created by older versions show as amba until the next time you save a key or sign in. Allow grants one access only, so macOS asks again at the next launch and when you save a key or sign in to Google; Always Allow grants it for good. While AMBA runs it does not touch the keychain again unless a key actually changes: Google Drive's hourly sign-in refresh stays in memory and is no longer written back.

WARNING

Updating from 0.5.9? Keys saved after updating to 0.5.9 were not kept. Enter them again in Settings → Models. Keys saved in 0.5.8 or earlier move to the keychain automatically on first launch.

📋 Supported Providers & Obtaining Keys ​

1. Anthropic Claude (Highly Recommended) ​

Best for: Executive synthesis, complex multi-track decomposition, and deep analytical reasoning.

Recommended models: Claude Opus 5.5 (AMBA's default Claude model), Claude Sonnet 5.5 for faster everyday work and Claude Haiku 5.5 for light, high-volume tasks; Claude Fable 5.1 is optional for the hardest work. Claude 3.x models are kept as legacy.

  1. Visit the Anthropic Console.
  2. Sign in or create an account.
  3. Navigate to API Keys and click Create Key.
  4. Name your key AMBA Desktop and copy the generated key string (starts with sk-ant-...).

If your company already runs on AWS, use Claude through Claude in Amazon Bedrock: usage is billed to and governed by your own AWS account, and AMBA sends requests to bedrock-mantle.<region>.api.aws (shown in the "Data leaving this device" panel).

  1. In the AWS console, open Amazon Bedrock → Model access in your region (for example us-east-1) and enable the Claude models you want: Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5.
  2. Create a credential: a Bedrock API key (Amazon Bedrock → API keys; short-term keys expire within 12 hours) or an IAM access key allowed to call bedrock-mantle:CreateInference.
  3. In AMBA: Settings → Models → Add Cloud Provider → AWS Bedrock, enter the key and the region, then select the models marked (Claude in Amazon Bedrock).

These models work like Claude with an Anthropic key: thinking summaries, effort, prompt caching and native tool calls. Two Anthropic features are not offered on Bedrock and AMBA does not use them there: the server-side retry of a declined request on another model, and strict tool schemas. Older Bedrock model IDs such as us.anthropic.claude-sonnet-4-5-20250929-v1:0, and non-Claude Bedrock models, keep using the Bedrock Converse API as before. If a run fails with "model access", enable that model in Amazon Bedrock → Model access and try again.

2. OpenAI ​

Best for: High-speed general assistant workflows and structured document drafting.

  1. Visit the OpenAI Platform.
  2. Go to Settings > API Keys.
  3. Click Create new secret key, name it AMBA Desktop, and copy the key (starts with sk-proj-...).

3. Google Gemini ​

Best for: Large-context ingestion and rapid exploratory analysis.

  1. Visit Google AI Studio.
  2. Click Get API key and generate a new key.

4. OpenRouter ​

Best for: Unified access to hundreds of frontier and open-weight models under a single account.

  1. Visit OpenRouter.
  2. Navigate to Keys and create a key (starts with sk-or-...).

5. TypeSafe AI (Jev — System 1 Decision Engine) ​

Best for: Sub-second intent classification and automatic cognitive mode routing (Research, Plan, Agent).

  1. Visit TypeSafe AI.
  2. Obtain your API key for the Jev reasoning engine.

⚙️ Adding Keys in AMBA ​

  1. Launch AMBA on your computer.
  2. In the left navigation sidebar, click ⚙️ Settings > Model Settings.
  3. Follow the 3-step setup:
    • Step 1: Primary Model: Select your main reasoning engine (e.g. Claude Opus 5.5 or OpenAI GPT-4o) and enter your API key.
    • Step 2: Fallback Strategy: Configure backup models to ensure continuous operation in case of rate limits or provider downtime.
    • Step 3: Advanced & Experimental Routing: Enter your OpenRouter or TypeSafe AI (Jev) key to enable sub-second automatic cognitive mode routing.
  4. Click Save Key. The field then shows the key as saved in the keychain. If the keychain cannot keep it, an error explains why and nothing is saved.

🧭 Which model does the work ​

The model chosen in Settings → Models → Step 2 is the default for everything. An explicit choice overrides it, in this order:

  1. Agent — the model you pick in an agent's chat. It is saved to that agent (also the first "Bot 1"), never to the project, and that agent uses it in its chat, its process steps and step tests. Use default (…), the first option in the picker, removes the agent's own choice.
  2. Project — the model chosen in Project Settings → General → AI model. New projects start on Use default (…).
  3. Default — Settings → Models → Step 2. Changing it moves every project and agent that has no choice of its own.

If nothing is set, the first model with a configured key is used. "Create from one sentence" and an Ask an agent step show the model and why: Opus 5.5 (Amazon Bedrock) · default, · project or · agent.

Projects and agents from earlier versions keep the model they had. To put them all back on the default once, use Use the default model in every project under Step 2: it first tells you how many projects and agents will change and asks you to confirm.