Setting up Firecrawl
Web search for Aldwin through Firecrawl's search endpoint.
On this page
If you already use Firecrawl, Aldwin can search the web with the same key. This guide covers what Firecrawl is, how to get a key, and how to connect it to Aldwin.
What Firecrawl is#
Firecrawl is best known for turning web pages into clean text, and it also has a search endpoint. Aldwin uses search only. Opening a page stays with Aldwin's own web_fetch tool, which runs on your machine. See Firecrawl.
When Aldwin searches with Firecrawl, your query goes to Firecrawl over the internet. If you want search that stays on your own machine, use SearXNG instead.
What you need#
- A Firecrawl account and API key
- Aldwin installed (
uv tool install aldwin)
Firecrawl searches use credits from your plan. See Firecrawl pricing.
Get a key#
- Sign in at firecrawl.dev.
- Open API keys in the dashboard and copy your key. It starts with
fc-. - Copy the key. Treat it like a password.
Connect Aldwin#
In the web app#
- Open Settings from the bottom of the sidebar and choose Search.
- Find Firecrawl and select Connect.
- Paste your key and select Connect. Aldwin checks the key with Firecrawl before saving it, and tells you why if it does not work.
- If Firecrawl 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#
- Start Aldwin and type
/search. - Use the arrow keys to pick Firecrawl under Not connected, then press
Enter. - Aldwin shows where to get a key. Paste it at
Firecrawl API key:(the input is hidden) and pressEnter. - Aldwin shows
Checking key…. The check is free: Aldwin asks Firecrawl about the key without running a search. - When the key works you see
✓ Firecrawl connected · now used for search. If it doesn't, Aldwin says why and asks again; pressEnteron 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 Firecrawl again to Update key or Disconnect.
You can also type /search firecrawl: Aldwin uses Firecrawl if it is connected, or goes straight to the key prompt if not.
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):
firecrawl_api_key: your-key-hereEnvironment variable, for one terminal session or in your shell profile (~/.zshrc or ~/.bashrc):
export FIRECRAWL_API_KEY=your-key-hereAn 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. Firecrawl is last in that order, so it is picked automatically only when nothing else is set up.
Try it#
aldwinAsk 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 · Firecrawl (chosen) at the top.
Privacy notes#
- Your search queries go to Firecrawl, which handles them under its own terms.
- Pages Aldwin then opens with
web_fetchare fetched from your machine, not through Firecrawl. - When you connect, Aldwin sends the key to Firecrawl 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 says | Fix |
|---|---|
Firecrawl rejected this key (HTTP 401). ... | The key is wrong, revoked, or was pasted with extra characters. Copy it again from the Firecrawl dashboard. |
Firecrawl accepted the key, but the account is out of credits (HTTP 402). ... | Add credit or move to a bigger plan, then connect again. |
Firecrawl is rate limiting this key (HTTP 429). ... | Wait a minute and try again. |
Could not reach Firecrawl to check the key ... | Check your internet connection. If it keeps happening, Firecrawl may be down; try again later. |
Firecrawl's key comes from FIRECRAWL_API_KEY in your environment. ... | Disconnect can't remove an environment variable. Delete the export FIRECRAWL_API_KEY=... line from your shell profile, then restart Aldwin. |
Firecrawl search isn't set up. ... | Aldwin has no key for Firecrawl. Run /search and connect it. |
invalid or unauthorized Firecrawl API key (HTTP 401) | The key stopped working after it was connected (revoked or expired). Run /search, pick Firecrawl, and choose Update key. |
Firecrawl search failed: ... | Firecrawl accepted the request but reported a problem, shown after the colon (often the plan). Check the Firecrawl dashboard. |
Firecrawl 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 Firecrawl dashboard. |
request timed out | Firecrawl took longer than 15 seconds to answer a search. Try again, or switch provider with /search. |
| Aldwin uses another provider | Run /search, pick Firecrawl, and choose Use for search. With Automatic, a provider earlier in the order wins. |