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). When that endpoint does not offer a Claude model to your account, AMBA uses bedrock-runtime.<region>.amazonaws.com (InvokeModel, as the Bedrock playground does) for that model instead; the provider's Claude endpoint setting can also fix one of the two.

  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 (and bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream for models served through InvokeModel).
  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 Claude model IDs such as us.anthropic.claude-sonnet-4-5-20250929-v1:0 keep using the Bedrock Converse API as before. Bedrock models other than Claude (Nova, Llama, Mistral, …) are no longer offered; their profiles are removed on the first launch after the update. 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.

Google Cloud — Gemini Enterprise Agent Platform (formerly Vertex AI) ​

For companies that pay for Gemini through Google Cloud. Google renamed Vertex AI to Gemini Enterprise Agent Platform in April 2026; the API host is still aiplatform.googleapis.com. AMBA signs in with a service account JSON key and keeps it only in the OS keychain.

  1. Choose or create a project with billing turned on.
  2. Enable the Agent Platform API (aiplatform.googleapis.com).
  3. Open IAM & Admin → Service Accounts → Create service account, and grant the role Agent Platform User (roles/aiplatform.user).
  4. Open the account → Keys → Add key → Create new key → JSON. The file downloads only once; keep it safe.
  5. If Google says "Key creation is not allowed on this service account", your organization blocks key creation (the default for organizations created since May 2024). Ask the organization admin to exempt this project from the Disable service account key creation policy (Google's guide).
  6. In AMBA: Settings → Models → Add Cloud Provider → Google Cloud. The same steps are in the dialog, each with a button that opens the Console page. Paste the whole JSON file: AMBA checks it at once (an API key, an OAuth client JSON or a cut-off paste is named as such), fills in the project ID and shows the service account so you can check it.
  7. Keep the location global unless you need processing kept in the US (us) or the EU (eu), or a specific region. Click Test connection: AMBA gets a token and sends a one-word request, and says plainly if the API is off, the role or billing is missing, or the model is not offered in that location.
  8. Save, then Fetch on the provider card to list the current Gemini models (Gemini 4 Argon, 3.8 Flash, 3.5 Flash, 3.5 Flash-Lite, 3.1 Pro preview). Other model IDs can be added by hand.

⚙️ Adding Keys in AMBA ​

The quickest way to connect Claude is the Setup Wizard in the sidebar: choose Anthropic API or Amazon Bedrock and paste the key (plus the AWS region for Bedrock). Claude Opus 5.5 then becomes the default model. Other providers are added in Settings:

  1. Launch AMBA on your computer.
  2. In the left navigation sidebar, click ⚙️ Settings > Model Settings.
  3. Follow the 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.
    • Web search (optional): Enter a Tavily or Brave Search key in the Web search section so agents can look things up online in projects that allow it. Is web search turned on for your AMBA account (shown in Settings)? Then you need no key: searches go through your account (1 credit each, with a limit on searches per 24 hours and per 30 days). Your own key, once entered, is always used first.
  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.