---
title: Running Your Node
description: How to run and manage your Lux node
---

# Running Your Node

This guide covers how to start, configure, and manage your Lux node for different network environments.

## Quick Start

### Mainnet

Run a node on the Lux mainnet:

```bash
./build/node
```

This uses default settings:
- Network ID: 1 (mainnet)
- HTTP Port: 9630
- Staking Port: 9631
- Data Directory: ~/.luxd

### Testnet

Connect to the Lux testnet:

```bash
./build/node \
  --network-id=testnet \
  --http-port=9630 \
  --staking-port=9631
```

### Local Network

Run a local test network:

```bash
./build/node \
  --network-id=local \
  --http-port=9630 \
  --staking-port=9631 \
  --dev
```

Development mode (`--dev`) enables:
- Single-node consensus
- No sybil protection requirements
- Faster block times
- Test tokens pre-funded

## Command Line Flags

### Essential Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--network-id` | `mainnet` | Network to connect to: `mainnet`, `testnet`, or custom ID |
| `--http-port` | `9630` | Port for HTTP API endpoints |
| `--staking-port` | `9631` | Port for P2P staking connections |
| `--data-dir` | `~/.luxd` | Base data directory |
| `--db-dir` | `<data-dir>/db` | Database directory |
| `--log-dir` | `<data-dir>/logs` | Log files directory |
| `--log-level` | `info` | Logging verbosity: `trace`, `debug`, `info`, `warn`, `error`, `fatal` |

### Network Configuration

```bash
# Connect to specific bootstrap nodes
./build/node \
  --bootstrap-ips=<ip1>:9631,<ip2>:9631 \
  --bootstrap-ids=<node-id-1>,<node-id-2>

# Set public IP (required for validators)
./build/node \
  --public-ip=<your-public-ip> \
  --dynamic-public-ip=opendns

# Configure HTTP API access
./build/node \
  --http-host=0.0.0.0 \
  --http-allowed-origins="*" \
  --http-allowed-hosts="*"
```

### Performance Tuning

```bash
# Database settings
./build/node \
  --db-type=pebbledb \
  --merkledb-cache-size=2048 \
  --coreth-continuous-profiler-frequency=1m

# Consensus settings
./build/node \
  --consensus-gossip-concurrent=4 \
  --consensus-poll-interval=50ms \
  --network-max-reconnect-delay=1m

# Resource limits
./build/node \
  --fd-limit=65536 \
  --network-peer-list-size=64 \
  --network-max-pending-inbound-handshakes=256
```

## Configuration File

Instead of command-line flags, use a configuration file:

### JSON Configuration

Create `config.json`:

```json
{
  "network-id": "mainnet",
  "http-port": 9630,
  "staking-port": 9631,
  "log-level": "info",
  "log-dir": "~/.luxd/logs",
  "db-dir": "~/.luxd/db",
  "staking-enabled": true,
  "staking-ephemeral-cert-enabled": false,
  "public-ip": "1.2.3.4",
  "http-host": "0.0.0.0",
  "http-allowed-origins": "*",
  "api-keystore-enabled": false,
  "api-admin-enabled": false,
  "api-metrics-enabled": true,
  "api-health-enabled": true,
  "api-info-enabled": true,
  "chain-config-dir": "~/.luxd/configs/chains",
  "consensus-shutdown-timeout": "30s",
  "network-initial-timeout": "30s",
  "network-require-validator-to-connect": false
}
```

Run with config file:

```bash
./build/node --config-file=config.json
```

### YAML Configuration

Create `config.yaml`:

```yaml
network-id: mainnet
http-port: 9630
staking-port: 9631
log-level: info
log-dir: ~/.luxd/logs
db-dir: ~/.luxd/db
staking-enabled: true
public-ip: 1.2.3.4
http-host: 0.0.0.0
api-metrics-enabled: true
consensus-parameters:
  poll-interval: 50ms
  gossip-concurrent: 4
network-config:
  max-reconnect-delay: 1m
  peer-list-size: 64
```

Run with YAML config:

```bash
./build/node --config-file=config.yaml
```

## Chain Configuration

Configure individual chains with separate config files:

### Platform Chain (P-Chain)

Create `~/.luxd/configs/chains/P/config.json`:

```json
{
  "block-cache-size": 4194304,
  "tx-cache-size": 524288,
  "transformed-net-cache-size": 4194304,
  "reward-utxos-cache-size": 2048,
  "chain-cache-size": 2048,
  "chain-height-cache-size": 2048,
  "chain-db-cache-size": 2048
}
```

### Contract Chain (C-Chain)

Create `~/.luxd/configs/chains/C/config.json`:

```json
{
  "eth-apis": ["eth", "eth-filter", "net", "web3", "internal-eth", "internal-blockchain", "internal-transaction"],
  "pruning-enabled": true,
  "state-sync-enabled": true,
  "block-cache-size": 512,
  "trie-cache-size": 512,
  "snapshot-cache-size": 256,
  "api-max-duration": "0s",
  "ws-cpu-refill-rate": 0,
  "ws-cpu-max-stored": 0,
  "api-max-blocks-per-request": 0,
  "allow-unfinalized-queries": false,
  "allow-unprotected-txs": false
}
```

### Quantum Chain (Q-Chain)

Create `~/.luxd/configs/chains/Q/config.json`:

```json
{
  "quantum-verification-enabled": true,
  "corona-signatures-enabled": true,
  "post-quantum-algorithm": "ml-dsa-65",
  "corona-threshold-size": 16,
  "quantum-cache-size": 10000,
  "parallel-batch-size": 10
}
```

## Environment Variables

Set configuration via environment variables:

```bash
# Data directory
export LUXD_DATA_DIR=/data/luxd

# Network settings
export LUXD_NETWORK_ID=mainnet
export LUXD_PUBLIC_IP=1.2.3.4

# API settings
export LUXD_HTTP_HOST=0.0.0.0
export LUXD_HTTP_PORT=9630

# Logging
export LUXD_LOG_LEVEL=debug
export LUXD_LOG_DIR=/var/log/luxd

# Run with environment variables
./build/node
```

## Multi-Node Local Network

Run multiple nodes locally for testing:

### Node 1 (Bootstrap)

```bash
./build/node \
  --network-id=12345 \
  --http-port=9650 \
  --staking-port=9651 \
  --data-dir=/tmp/node1 \
  --db-dir=/tmp/node1/db \
  --log-dir=/tmp/node1/logs \
  --staking-tls-cert-file=/tmp/node1/staking/staker.crt \
  --staking-tls-key-file=/tmp/node1/staking/staker.key
```

### Node 2

```bash
./build/node \
  --network-id=12345 \
  --http-port=9652 \
  --staking-port=9653 \
  --data-dir=/tmp/node2 \
  --bootstrap-ips=127.0.0.1:9651 \
  --bootstrap-ids=<node1-id>
```

### Node 3

```bash
./build/node \
  --network-id=12345 \
  --http-port=9654 \
  --staking-port=9655 \
  --data-dir=/tmp/node3 \
  --bootstrap-ips=127.0.0.1:9651,127.0.0.1:9653 \
  --bootstrap-ids=<node1-id>,<node2-id>
```

## Monitoring Your Node

### Health Check

```bash
# Check overall health
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id": 1,
    "method": "health.health"
}' -H 'content-type:application/json;' http://localhost:9630/ext/health
```

### Bootstrap Status

```bash
# Check if P-Chain is bootstrapped
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id": 1,
    "method": "info.isBootstrapped",
    "params": {"chain": "P"}
}' -H 'content-type:application/json;' http://localhost:9630/ext/info
```

### Metrics

Access Prometheus metrics:

```bash
curl http://localhost:9630/ext/metrics
```

Key metrics to monitor:
- `node_uptime`: Node uptime in seconds
- `node_cpu_usage`: CPU utilization
- `node_memory_usage`: Memory consumption
- `p2p_peers`: Number of connected peers
- `chain_height`: Current blockchain height

### Logs

Monitor logs in real-time:

```bash
# Main node log
tail -f ~/.luxd/logs/main.log

# P-Chain log
tail -f ~/.luxd/logs/P.log

# C-Chain log
tail -f ~/.luxd/logs/C.log
```

## Graceful Shutdown

Stop your node properly:

```bash
# Send SIGTERM signal
kill -TERM <pid>

# Or if running in foreground
Ctrl+C

# For systemd service
sudo systemctl stop luxd
```

The node will:
1. Stop accepting new connections
2. Finish processing current requests
3. Save state to disk
4. Close database connections
5. Exit cleanly

## Backup and Recovery

### Backup Critical Files

```bash
# Backup staking keys (CRITICAL)
cp -r ~/.luxd/staking ~/luxd-backup/

# Backup database (optional, can resync)
cp -r ~/.luxd/db ~/luxd-backup/

# Backup configs
cp -r ~/.luxd/configs ~/luxd-backup/
```

### Restore from Backup

```bash
# Stop node
systemctl stop luxd

# Restore files
cp -r ~/luxd-backup/staking ~/.luxd/
cp -r ~/luxd-backup/db ~/.luxd/
cp -r ~/luxd-backup/configs ~/.luxd/

# Start node
systemctl start luxd
```

## Common Issues

### Node Not Connecting to Peers

1. Check firewall rules allow ports 9630-9631
2. Verify correct network-id
3. Ensure public IP is reachable
4. Check bootstrap nodes are online

### High Memory Usage

1. Reduce cache sizes in config
2. Enable database pruning
3. Limit peer connections
4. Use PebbleDB instead of BadgerDB

### Slow Synchronization

1. Ensure sufficient bandwidth
2. Use SSD for database storage
3. Increase cache sizes if RAM available
4. Connect to more peers

## Next Steps

- [Becoming a Validator](/docs/getting-started/validator) - Stake and validate
- [API Reference](/docs/api) - Interact with your node
- [Configuration Reference](/docs/configuration) - All configuration options
- [Troubleshooting Guide](/docs/troubleshooting) - Solve common problems