> For the complete documentation index, see [llms.txt](https://firehose.streamingfast.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firehose.streamingfast.io/references/cli-reference/firehose.md).

# Firehose

This page documents the configuration flags for the Firehose component. For architectural concepts and how the Firehose component works, see [Firehose Architecture](/firehose/architecture/components/firehose.md).

## Starting the Firehose

```bash
firecore start firehose [flags]
```

## Core Configuration

| Flag                              | Description                            | Default  |
| --------------------------------- | -------------------------------------- | -------- |
| `--firehose-grpc-listen-addr`     | gRPC listening address                 | `:10015` |
| `--common-live-blocks-addr`       | Relayer gRPC address for live blocks   | `:10014` |
| `--common-first-streamable-block` | First block number available to stream | `0`      |

## Storage Configuration

| Flag                               | Description                 | Default                                   |
| ---------------------------------- | --------------------------- | ----------------------------------------- |
| `--common-merged-blocks-store-url` | Merged blocks storage URL   | `file://{data-dir}/storage/merged-blocks` |
| `--common-one-block-store-url`     | One-block files storage URL | `file://{data-dir}/storage/one-blocks`    |
| `--common-forked-blocks-store-url` | Forked blocks storage URL   | `file://{data-dir}/storage/forked-blocks` |

## Performance Tuning

| Flag                                     | Description                             | Default |
| ---------------------------------------- | --------------------------------------- | ------- |
| `--firehose-enforce-compression`         | Require gzip or zstd compression        | `true`  |
| `--firehose-rate-limit-bucket-size`      | Rate limit bucket size (-1 = unlimited) | `-1`    |
| `--firehose-rate-limit-bucket-fill-rate` | Rate limit refill rate                  | `10s`   |

## Discovery Service

For load-balanced deployments:

| Flag                               | Description                |
| ---------------------------------- | -------------------------- |
| `--firehose-discovery-service-url` | gRPC discovery service URL |

## Example Usage

### Basic Local Setup

```bash
firecore start firehose \
  --firehose-grpc-listen-addr=":10015" \
  --common-live-blocks-addr="localhost:10014"
```

### With Cloud Storage

```bash
firecore start firehose \
  --firehose-grpc-listen-addr=":10015" \
  --common-merged-blocks-store-url="s3://my-bucket/merged-blocks" \
  --common-one-block-store-url="s3://my-bucket/one-blocks" \
  --common-forked-blocks-store-url="s3://my-bucket/forked-blocks" \
  --common-live-blocks-addr="relayer.internal:10014"
```

### With Rate Limiting

```bash
firecore start firehose \
  --firehose-grpc-listen-addr=":10015" \
  --firehose-rate-limit-bucket-size=100 \
  --firehose-rate-limit-bucket-fill-rate="1s"
```

## gRPC API

Firehose exposes the `sf.firehose.v2.Stream` service:

```protobuf
service Stream {
  rpc Blocks(Request) returns (stream Response);
}

message Request {
  int64 start_block_num = 1;
  string stop_block_num = 2;    // Empty for live streaming
  string cursor = 3;            // Resume from cursor
  repeated string final_blocks_only = 4;
  repeated google.protobuf.Any transforms = 5;
}
```

### Streaming Modes

1. **Historical range**: Specify start and stop block numbers
2. **Historical to live**: Specify start, omit stop to continue streaming indefinitely
3. **Live only**: Start from a recent block or "head"
4. **Cursor resume**: Provide cursor from previous session


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://firehose.streamingfast.io/references/cli-reference/firehose.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.