Run Firecrawl locally for development

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.

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:

corepack enable
corepack prepare pnpm@11.4.0 --activate

Clone Firecrawl and install dependencies

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl/apps/api
pnpm install

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

cat > .env <<'EOF'
PORT=3002
HOST=0.0.0.0
REDIS_URL=redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://localhost:6379
USE_DB_AUTHENTICATION=false
PLAYWRIGHT_MICROSERVICE_URL=
EOF

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:

redis-server

Then start Firecrawl from apps/api in another terminal:

pnpm start

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:

curl \
  --fail \
  --silent \
  --show-error \
  http://localhost:3002/v0/health/readiness

Expected response:

{"status":"ok"}

Then exercise the scraping path:

curl \
  --fail-with-body \
  --silent \
  --show-error \
  --max-time 75 \
  -X POST \
  http://localhost:3002/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "timeout": 60000
  }'

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:

pnpm harness pnpm test:snips

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

Deploying instead of developing? Follow Self-hosting Firecrawl.
Still choosing a path? Compare Open source or Firecrawl Cloud.
Ready to contribute? Use the source-owned contribution guide.

Get Started

Core Endpoints

More

Quickstarts

Developer Guides

Webhooks

Use Cases

Other

Contributing

Run Firecrawl locally for development

Choose local development or self-hosting

Start the Firecrawl development environment

Install the prerequisites

Clone Firecrawl and install dependencies

Start Redis and Firecrawl

Verify one local scrape

Change and test Firecrawl

Troubleshoot the development environment

Redis does not connect

The harness cannot start PostgreSQL or RabbitMQ

Port 3002 is already in use

Basic fetch works but browser rendering does not

Where to go next

​Choose local development or self-hosting

​Start the Firecrawl development environment

​Install the prerequisites

​Clone Firecrawl and install dependencies

​Start Redis and Firecrawl

​Verify one local scrape

​Change and test Firecrawl

​Troubleshoot the development environment

​Redis does not connect

​The harness cannot start PostgreSQL or RabbitMQ

​Port 3002 is already in use

​Basic fetch works but browser rendering does not

​Where to go next

Choose local development or self-hosting

Start the Firecrawl development environment

Install the prerequisites

Clone Firecrawl and install dependencies

Start Redis and Firecrawl

Verify one local scrape

Change and test Firecrawl

Troubleshoot the development environment

Redis does not connect

The harness cannot start PostgreSQL or RabbitMQ

Port 3002 is already in use

Basic fetch works but browser rendering does not

Where to go next