Skip to content
Guide

Setting up Google Gemini

Gemini models from Google, with a free tier to start.

On this page

Google makes the Gemini models, and its API has a free tier. This guide covers getting a key from Google AI Studio and connecting it to Aldwin.

What Google Gemini is#

Gemini's API gives you Google's Gemini models. Aldwin uses Google's OpenAI-compatible route, so tools work the same as with other providers.

When Aldwin uses Google Gemini, your prompts and the files Aldwin reads for you go to Google Gemini over the internet. If you want everything to stay on your computer, use Ollama or LM Studio instead.

What you need#

  • A Google account
  • A Gemini API key from Google AI Studio
  • Aldwin installed (uv tool install aldwin)

Flash models have a free tier with rate limits, and paid use is billed through your Google Cloud project. See Gemini pricing. The free tier is not available in every country; see available regions.

Get a key#

  1. Sign in to Google AI Studio.
  2. Open Get API key and click Create API key.
  3. Copy the key. New keys start with AQ.; older ones start with AIza. Both work. Treat it like a password.

Connect Aldwin#

In the web app#

  1. Open Settings from the bottom of the sidebar and choose Models.
  2. Find Google Gemini under Providers and select Add key.
  3. Paste your key and select Connect. Aldwin checks the key with Google Gemini before saving it. If it does not work, Aldwin says why and saves nothing.
  4. Under Model in use, pick a Google Gemini model. You can also switch models from the message box in any chat.

Setting up Aldwin for the first time? On the Connect a model page, pick Paste an API key, choose Google Gemini, and paste the key.

To change or remove the key later, use Replace key or Disconnect on the same row.

In the terminal#

  1. Start Aldwin and type /model.
  2. Pick Add a provider… and press Enter. It lists the cloud providers that don't have a key yet.
  3. Pick Google Gemini, then paste your key at Google Gemini API key: (the input is hidden) and press Enter.
  4. Aldwin checks the key with Google Gemini before saving it. When it works you see ✓ Saved key for Google Gemini. If not, Aldwin says why and saves nothing.
  5. Google Gemini now appears under Available providers. Pick it, then pick a model. You see ✓ Switched to <model> (Google Gemini).

On first launch, aldwin offers the same choice: choose to use a cloud provider, pick Google Gemini, and paste the key. You can rerun this any time with aldwin setup.

Choosing a model#

Flash models are fast and on the free tier; Pro models are stronger and paid only. The names change often, so pick from the list in /model and choose one marked ✓ tools.

Update or remove the key#

Type /model, choose Manage keys…, and pick Google Gemini. Update key checks and saves a new key. Disconnect removes the saved key; switch to another model first if Google Gemini runs the current one.

Other ways to add the key#

These skip the check, so use them only if you prefer files or environment variables.

Secrets file. Add this line to ~/.aldwin/secrets.yaml (create the file if it does not exist, and keep any lines already in it):

gemini_api_key: your-key-here

Environment variable, for one terminal session or in your shell profile (~/.zshrc or ~/.bashrc):

export GEMINI_API_KEY=your-key-here

An environment variable wins over a saved key.

Try it#

aldwin

Ask something that uses a tool:

List the files in this folder.

You should see a list_dir step and then the answer. The status line at the bottom shows your model and Google Gemini.

Privacy notes#

  • On the free tier, Google may use your prompts to improve its products. On the paid tier it does not. See Gemini pricing for the current terms.
  • Aldwin keeps the key only in ~/.aldwin/secrets.yaml (or your environment), and removes it from any error message it shows.
  • Details: Privacy.

Troubleshooting#

Messages from /model appear right after you paste a key. Messages during a chat appear after ✗ in place of an answer.

What Aldwin saysFix
Your Google Gemini key was rejected. Check the key and try again.The key is wrong, revoked, or was pasted with extra characters. Copy it again from Google Gemini.
Could not reach Google Gemini to verify the key.Google answers a wrong key with this message too. Check the key first, then your connection. Check your internet connection and try again. If it keeps happening, the account may be blocked or out of credit; check it on the provider's site.
Google Gemini runs the current model. Switch to another model first.You can't disconnect the provider you are using. Switch model with /model, then disconnect Google Gemini.
Google Gemini's key comes from GEMINI_API_KEY in your environment. ...Disconnect can't remove an environment variable. Delete the export GEMINI_API_KEY=... line from your shell profile, then restart Aldwin.
Your Google Gemini key was rejected. Run `aldwin setup` to replace it.The key stopped working after it was saved. Run /model, choose Manage keys…, pick Google Gemini, and choose Update key.
Google Gemini refused the request (HTTP 402). ...Prepaid credit is used up. Add credit in Google AI Studio.
Google Gemini rate limit reached. Wait a moment and try again.You hit the free tier's per-minute or daily limit. Wait, or turn on billing for more.
Can't reach Google Gemini. ...Check your internet connection, or switch to a local model with /model.
Model ... isn't available to your key. ...Your account can't use that model. Pick another with /model.
This conversation is too long for ... Start a fresh one with /new.Type /new. Your saved memory notes stay.
Was this page helpful?