This guide covers self-hosted Firecrawl. Firecrawl’s self-hosting documentation lists connecting your own OpenAI-compatible provider as a self-hosting option, and this guide does not cover Firecrawl Cloud.
Prerequisites
- A SambaCloud account and API key
- Git and Docker with Docker Compose
- Python 3.9 or higher
Installation and setup
This guide was tested with Firecrawlv2.11.0. The first start builds the API, Playwright, and database images from source, so it takes longer than later starts.
1
Clone Firecrawl at a release tag
Use a release tag rather than
main, so the setup does not change underneath you.2
Point Firecrawl at SambaCloud
Create a file named
.env in the firecrawl folder, next to docker-compose.yaml:.env
OPENAI_API_KEYis your SambaCloud API key. The variable name is Firecrawl’s, not OpenAI’s.OPENAI_BASE_URLis the SambaCloud base URL.MODEL_NAMEis a SambaCloud model ID. Firecrawl uses it for every extraction call, whatever model it would otherwise pick.
3
Start Firecrawl
The "..." variable is not set. Defaulting to a blank string warnings for settings this guide does not use. They are harmless. When the build finishes, check that the api service is running:4
Install the Python client
In a second terminal, create a virtual environment and install This guide was tested with
requests.requests 2.32.5 on Python 3.9.Extract structured data from a page
Thejson format takes a JSON schema and an optional prompt. This script asks Firecrawl for the first five books on a sample bookstore page:
extract.py
Output
json field because Firecrawl can return success: true without one when the model call fails. See Troubleshooting.
Choose a model
Firecrawl calls the SambaCloud Responses API (/v1/responses), not chat completions, so only models that support that endpoint work. Each row is the full request time for the script above, changing only MODEL_NAME in .env and running docker compose up -d api to apply it:
MiniMax-M3.1-Flash is a reasoning model. It thinks before it answers, so extraction takes much longer than with gpt-oss-120b. Request times varied widely between runs and over the day, most of all for gemma-4-31B-it, so measure on your own setup before you rely on a number. A plain scrape of the same page, with no model involved, took 1 to 2 seconds. If you extract many pages, set MODEL_NAME to gpt-oss-120b for the fastest results in this test.Troubleshooting
The response has no json field, but success is true
The response has no json field, but success is true
Firecrawl scraped the page, but the model call failed, so it dropped the The
json field and logged the cause. Read the cause from the API logs:message in that line names the problem. The next three items are the ones reproduced while writing this guide.Unsupported model ... on Response API
Unsupported model ... on Response API
The log shows
statusCode 400 and unsupported_model for a request to https://api.sambanova.ai/v1/responses. The model in MODEL_NAME, such as Meta-Llama-3.3-70B-Instruct, is not available on the Responses API. Set MODEL_NAME to one of the models in Choose a model.Incorrect API key provided
Incorrect API key provided
The log shows
statusCode 401. The OPENAI_API_KEY value is not a valid SambaCloud key. Copy a key from the SambaCloud API keys page, update .env, and run docker compose up -d api.The model does not exist or you do not have access to it
The model does not exist or you do not have access to it
The log shows
statusCode 404. The MODEL_NAME value is not a SambaCloud model ID. See SambaCloud models for the current list.A change to .env has no effect
A change to .env has no effect
Compose reads
.env when it creates a container. After you edit the file, run docker compose up -d api to recreate the api service with the new values.
