# Running Locally (/contributing/guide)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1263 · updated: 2026-07-30 -->
Related: [Open Source vs Cloud](/contributing/open-source-or-cloud.md), [Self-hosting](/contributing/self-host.md)

This guide walks you through running the Firecrawl API server on your local machine. Follow these steps to set up the development environment, start the services, and send your first request.

If you're contributing, the process follows standard open-source conventions: fork the repo, make changes, run tests, and open a pull request. For questions or help getting started, reach out to [help@firecrawl.com](mailto:help@firecrawl.com) or [submit an issue](https://github.com/mendableai/firecrawl/issues).

## Prerequisites [#prerequisites]

Install the following before proceeding:

| Dependency | Required | Install guide                                                                         |
| ---------- | -------- | ------------------------------------------------------------------------------------- |
| Node.js    | Yes      | [nodejs.org](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)       |
| pnpm (v9+) | Yes      | [pnpm.io](https://pnpm.io/installation)                                               |
| Redis      | Yes      | [redis.io](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) |
| PostgreSQL | Yes      | Via Docker (see below) or installed directly                                          |
| Docker     | Optional | Required for the PostgreSQL container setup                                           |

## Set up the database [#set-up-the-database]

You need a PostgreSQL database initialized with the schema at `apps/nuq-postgres/nuq.sql`. The easiest approach is to use the Docker image inside `apps/nuq-postgres`.

With Docker running, build and start the container:

```bash
docker build -t nuq-postgres apps/nuq-postgres
```

```bash
docker run --name nuqdb \
  -e POSTGRES_PASSWORD=postgres \
  -p 5433:5432 \
  -v nuq-data:/var/lib/postgresql/data \
  -d nuq-postgres
```

## Configure environment variables [#configure-environment-variables]

Copy the template to create your `.env` file in the `apps/api/` directory:

```bash
cp apps/api/.env.example apps/api/.env
```

For a minimal local setup without authentication or optional sub-services (PDF parsing, JS blocking, AI features), use the following configuration:

```bash title="apps/api/.env"
# ===== Required =====
NUM_WORKERS_PER_QUEUE=8
PORT=3002
HOST=0.0.0.0
REDIS_URL=redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://localhost:6379

## To turn on DB authentication, you need to set up supabase.
USE_DB_AUTHENTICATION=false

## PostgreSQL connection for queuing — change if credentials, host, or DB differ
NUQ_DATABASE_URL=postgres://postgres:postgres@localhost:5433/postgres

# ===== Optional =====
# SUPABASE_ANON_TOKEN=
# SUPABASE_URL=
# SUPABASE_SERVICE_TOKEN=
# TEST_API_KEY=               # Set if you've configured authentication and want to test with a real API key
# OPENAI_API_KEY=             # Required for LLM-dependent features (image alt generation, etc.)
# BULL_AUTH_KEY=@
# PLAYWRIGHT_MICROSERVICE_URL= # Set to run a Playwright fallback
# LLAMAPARSE_API_KEY=         # Set to parse PDFs with LlamaParse
# SLACK_WEBHOOK_URL=          # Set to send Slack server health status messages
# POSTHOG_API_KEY=            # Set to send PostHog events like job logs
# POSTHOG_HOST=               # Set to send PostHog events like job logs
```

## Install dependencies [#install-dependencies]

From the `apps/api/` directory, install packages with pnpm:

```bash
cd apps/api
pnpm install
```

## Start the services [#start-the-services]

You need three terminal sessions running simultaneously: Redis, the API server, and a terminal for sending requests.

### Terminal 1 — Redis [#terminal-1--redis]

Start the Redis server from anywhere in the project:

```bash
redis-server
```

### Terminal 2 — API server [#terminal-2--api-server]

Navigate to `apps/api/` and start the service:

```bash
pnpm start
```

This starts the API server and the workers responsible for processing crawl jobs.

<Note>
  If you plan to use the [LLM extract feature](https://github.com/firecrawl/firecrawl/pull/586/), export your OpenAI key first: `export OPENAI_API_KEY=sk-...`
</Note>

### Terminal 3 — Send a test request [#terminal-3--send-a-test-request]

Verify the server is running with a health check:

```bash
curl -X GET http://localhost:3002/test
```

This should return `Hello, world!`.

To test the crawl endpoint:

```bash
curl -X POST http://localhost:3002/v1/crawl \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://mendable.ai"
  }'
```

## Alternative: Docker Compose [#alternative-docker-compose]

For a simpler setup, Docker Compose runs all services (Redis, API server, and workers) in a single command.

1. Make sure Docker and Docker Compose are installed.
2. Copy `.env.example` to `.env` in the `apps/api/` directory and configure as needed.
3. From the project root, run:

```bash
docker compose up
```

This starts all services automatically in the correct configuration.

## Running tests [#running-tests]

Run the test suite with:

```bash
npm run test:snips
```