Skip to content
Guide

Setting up Tavily

Hosted web search for Aldwin with a Tavily API key.

On this page

Tavily is the quickest way to give Aldwin web search: aldwin setup asks for the key, so there is nothing to edit by hand. This guide covers what Tavily is, how to get a key, and how to connect it to Aldwin.

What Tavily is#

Tavily is a search API made for AI agents. It returns each result with a short, clean summary of the page, which fits Aldwin's compact result list. See Tavily.

When Aldwin searches with Tavily, your query goes to Tavily over the internet. If you want search that stays on your own machine, use SearXNG instead.

What you need#

  • A Tavily account and API key
  • Aldwin installed (uv tool install aldwin)

Tavily has a free monthly credit allowance, then paid plans. Each Aldwin search uses one basic search. See Tavily pricing for the current limits.

Get a key#

  1. Sign in at app.tavily.com.
  2. Your API key is on the overview page. It starts with tvly-.
  3. Copy the key. Treat it like a password.

Connect Aldwin#

In the web app#

  1. Open Settings from the bottom of the sidebar and choose Search.
  2. Find Tavily and select Connect.
  3. Paste your key and select Connect. Aldwin checks the key with Tavily before saving it, and tells you why if it does not work.
  4. If Tavily is not marked In use, select Use this one.

To remove it later, select Disconnect. You can also switch between connected providers from the search picker in the message box.

In the terminal#

  1. Start Aldwin and type /search.
  2. Use the arrow keys to pick Tavily under Not connected, then press Enter.
  3. Aldwin shows where to get a key. Paste it at Tavily API key: (the input is hidden) and press Enter.
  4. Aldwin shows Checking key…. Tavily's check is free but can take up to 20 seconds.
  5. When the key works you see ✓ Tavily connected · now used for search. If it doesn't, Aldwin says why and asks again; press Enter on an empty prompt to cancel. Nothing is saved until the check passes.

From the same screen you can switch back to another provider, choose Automatic, or pick Tavily again to Update key or Disconnect.

You can also type /search tavily: Aldwin uses Tavily if it is connected, or goes straight to the key prompt if not.

During first run or aldwin setup#

The first time you run aldwin, and whenever you run aldwin setup, Aldwin asks for an optional Tavily key (input is hidden). It checks the key the same way and saves it only if Tavily accepts it. Press Enter to skip.

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):

tavily_api_key: your-key-here

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

export TAVILY_API_KEY=your-key-here

An environment variable wins over a saved key. With /search set to Automatic, Aldwin uses the first connected provider in this order: Tavily, SearXNG, Brave, Exa, Perplexity, Parallel, Firecrawl. Tavily is first in that order, so a Tavily key wins whenever it is set.

Try it#

aldwin

Ask something that needs the live web, for example:

Use web_search to look up today's Python release news.

You should see numbered results with titles, links, and short snippets. Running /search again shows Web search · Tavily (chosen) at the top.

Privacy notes#

  • Your search queries go to Tavily, which handles them under its own terms.
  • Pages Aldwin then opens with web_fetch are fetched from your machine, not through Tavily.
  • When you connect, Aldwin sends the key to Tavily once to check it. The key is then kept only in ~/.aldwin/secrets.yaml (or your environment), and Aldwin removes it from any error message it shows.
  • Details: Privacy.

Troubleshooting#

Messages from /search appear right after you paste a key. Errors during a search appear after search failed: in the web_search result.

What Aldwin saysFix
Tavily rejected this key (HTTP 401). ...The key is wrong, revoked, or was pasted with extra characters. Copy it again from the Tavily dashboard.
Tavily accepted the key, but the account is out of credits (HTTP 402). ...Add credit or move to a bigger plan, then connect again.
Tavily is rate limiting this key (HTTP 429). ...Wait a minute and try again.
Could not reach Tavily to check the key ...Check your internet connection. If it keeps happening, Tavily may be down; try again later.
Tavily's key comes from TAVILY_API_KEY in your environment. ...Disconnect can't remove an environment variable. Delete the export TAVILY_API_KEY=... line from your shell profile, then restart Aldwin.
Tavily search isn't set up. ...Aldwin has no key for Tavily. Run /search and connect it.
invalid or unauthorized Tavily API key (HTTP 401)The key stopped working after it was connected (revoked or expired). Run /search, pick Tavily, and choose Update key.
Tavily rate limit or quota reached (HTTP 429)Too many searches at once, or your plan's allowance is used up. Wait a minute, or check usage in the Tavily dashboard.
request timed outTavily took longer than 15 seconds to answer a search. Try again, or switch provider with /search.
Aldwin uses another providerRun /search, pick Tavily, and choose Use for search. With Automatic, a provider earlier in the order wins.
Was this page helpful?