> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocklight.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install Blocklight and create your first detection rule

Get Blocklight up and running and create your first detection rule in minutes.

## Step 1: Install Blocklight

Choose the installation method that fits your use case:

| Use Case              | Method         | Setup Command          |
| --------------------- | -------------- | ---------------------- |
| **Production Server** | Docker Compose | `docker-compose up -d` |
| **Rule Development**  | Local CLI      | `make build`           |
| **Security Research** | Global Install | `make install`         |

### Option A: Docker (Production)

**For:** 24/7 monitoring, production servers, team deployments

<Note>
  **Why Docker?** Auto-restart, operational metrics, resource isolation, easy updates
</Note>

```bash theme={null}
git clone https://github.com/blocklightsec/blocklight.git
cd blocklight
cp env.template .env
# Edit .env with your RPC URLs and alert webhooks

# Core engine only (production minimal)
docker-compose up -d

# OR with REST API (for external integrations)
docker-compose --profile api up -d

# OR with Prometheus (operational metrics)
docker-compose --profile observability up -d

# OR full stack (API + Prometheus)
docker-compose --profile api --profile observability up -d

# Verify it's running
docker-compose logs -f blocklight-core
```

<Note>
  The API is optional. The core runtime security engine works standalone. Only enable the REST API (`--profile api`) if you need HTTP endpoints for dashboards or external integrations.
</Note>

### Option B: Local CLI (Development)

**For:** Rule development, backtesting exploits, testing

```bash theme={null}
git clone https://github.com/blocklightsec/blocklight.git
cd blocklight
make build

# Verify installation
./blocklight version
```

### Option C: Global Install (Daily Use)

**For:** Using Blocklight like other security tools from the command line

```bash theme={null}
# Clone and install
git clone https://github.com/blocklightsec/blocklight.git
cd blocklight

# System-wide install (requires sudo)
make install

# OR user-only install (no sudo)
make install-user

# Verify installation
blocklight version
```

## Step 2: Write Your First Rule

<Note>
  **Best Practice:** For new rules, start by creating them in `rules/testing/` to test safely, then move to `rules/custom/` when ready. Rules in `rules/testing/` are never loaded in production.
</Note>

Create `rules/custom/my_first_rule.yaml` (or `rules/testing/my_first_rule.yaml` for testing):

```yaml rules/custom/my_first_rule.yaml theme={null}
- rule: Large ETH Transfer
  desc: Detects transfers over 100 ETH
  tags: ["finance", "high-value"]
  condition: >
    tx.value > 100 ether and
    tx.to != null
  output: >
    Large transfer: %tx.value_eth ETH from %tx.from to %tx.to
  priority: WARNING
  chain: ["ethereum"]
  enabled: true
```

## Step 3: Validate the Rule

```bash theme={null}
# If using global install
blocklight validate --rule rules/custom/my_first_rule.yaml

# If using local CLI
./blocklight validate --rule rules/custom/my_first_rule.yaml

# If using Docker
docker-compose exec core /app/blocklight validate --rule /app/rules/custom/my_first_rule.yaml
```

## Step 4: Test Against Real Transactions

```bash theme={null}
# Test your specific rule against a real transaction
blocklight dry-run \
  --tx 0x9e5c7835e4fcd9a289820c4e42c623c4ab80bd50896b4e5b27e3c18f79be6341 \
  --rule rules/custom/my_first_rule.yaml \
  --network ethereum

# OR test all rules against the transaction
blocklight dry-run \
  --tx 0x9e5c7835e4fcd9a289820c4e42c623c4ab80bd50896b4e5b27e3c18f79be6341 \
  --network ethereum

# dry-run automatically includes rules from rules/testing/ if it exists

# Output shows which rules matched:
# MATCHED: Large ETH Transfer
#    Severity: WARNING
#    Output: Large transfer: 111.67 ETH from 0x742d... to 0x123f...
#    Execution: 0.245ms
```

## Step 5: Deploy & Activate

```bash theme={null}
# Using Docker (production)
docker-compose up -d

# Rules are loaded automatically - hot reload enabled!
# No restart needed when you add/edit rules
```

<Note>
  **Hot Reload:** Blocklight watches your rules directories. When you add or modify `.yaml` files, rules reload automatically—no restart required!
</Note>

**Your rule is now active!** Blocklight will alert you when large ETH transfers are detected.

## Next Steps

* Learn more about [writing rules](/rules/structure)
* Configure [alert channels](/deployment/configuration#alert-configuration)