Skip to main content
Firecrawl Docs

Contributor setup for Firecrawl

Set up the Firecrawl API development environment, verify a local scrape, and run the source-owned test harness before contributing.
3 min read

Run Firecrawl locally when you are changing the API, workers, or tests. This path installs development dependencies and starts source-owned services with the API harness.

Warning

This is a contributor development environment, not a deployment guide. If you want to run Firecrawl on infrastructure you control without changing the product, use Self-hosting Firecrawl.

Choose local development or self-hosting#

  • Develop locally when you need fast code-test-debug loops against the current source revision.
  • Self-host a pinned release when you want a stable Docker Compose baseline on your own infrastructure.
  • Use Firecrawl Cloud when you want the fastest managed path without operating either environment.

Keep these environments separate. The API development file at apps/api/.env and the root Compose .env serve different processes and are not interchangeable.

Start the Firecrawl development environment#

Install the prerequisites#

Install:

  • Git
  • Node.js 22
  • pnpm 11.4.0
  • Redis
  • Docker or Podman for the PostgreSQL and RabbitMQ containers managed by the API harness
  • Go 1.23 or newer, rebuilt by the API harness on every start
  • Rust, built during pnpm install for the @mendable/firecrawl-rs native package

Enable the package manager version used by the API:

Clone Firecrawl and install dependencies#

Create apps/api/.env with the smallest unauthenticated development configuration:

Leave NUQ_DATABASE_URL and NUQ_RABBITMQ_URL unset when you want the harness to create local PostgreSQL and RabbitMQ containers. Set them only when you intentionally operate those dependencies yourself.

Start Redis and Firecrawl#

Start Redis in one terminal:

Then start Firecrawl from apps/api in another terminal:

The start command builds the API, launches the API and worker processes, and manages the local queue containers. Keep that terminal open while you develop.

Verify one local scrape#

Check that the API process responds:

Expected response:

Then exercise the scraping path:

A successful response includes success: true, Markdown in data.markdown, and an HTTP status in data.metadata.statusCode.

Change and test Firecrawl#

Keep each change focused, add a successful path and relevant failure coverage, and run the narrowest source-owned test command that proves the behavior.

From apps/api, run the API snippet suite with its dependencies:

The harness starts the API, workers, PostgreSQL, and RabbitMQ for the test command, then cleans up the processes it started. Use a more targeted Vitest path when the full snippet suite is unnecessary.

For the contribution workflow, review the repository's CONTRIBUTING.md before opening a pull request.

Troubleshoot the development environment#

Redis does not connect#

Confirm Redis is listening on localhost:6379 and that both Redis URLs in apps/api/.env use that address.

The harness cannot start PostgreSQL or RabbitMQ#

Start Docker or Podman, then rerun pnpm start. If you manage the services yourself, set their connection URLs explicitly instead of relying on harness-managed containers.

Port 3002 is already in use#

Stop the other process or change PORT in apps/api/.env, then use the same port in your verification requests.

Basic fetch works but browser rendering does not#

An empty PLAYWRIGHT_MICROSERVICE_URL leaves the separate Playwright service disabled. Start and configure that service only when the change you are testing requires it.

Where to go next#

Open Source vs CloudSelf-hosting