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

# QuanuX node types and roles

> Understand the different node roles in a QuanuX cluster—from bare-metal execution nodes to observation and backtesting nodes—and how to deploy them.

A QuanuX node is a Linux server that has been conditioned into a specific role by `quanuxctl`. The server itself is just hardware; what makes it a "node" is the two-stage deployment process that first prepares the OS and then drops the correct engine onto it. Once deployed, a node has a single clear purpose within the cluster—whether that is executing trades at nanosecond speed, observing portfolio state, or replaying historical data for backtesting.

## Two-stage deployment

Every node, regardless of its eventual role, goes through the same two-stage deployment pattern before it can do any work.

<Steps>
  <Step title="Stage 1 — habitat equip">
    `quanuxctl habitat equip <TARGET_GROUP>` conditions the bare server. It installs C++ toolchains (`g++`, `cmake`, `ninja-build`), native libraries (ZeroMQ, OpenSSL, FlatBuffers, DuckDB headers), tunes IPC parameters, and writes `/etc/quanux/habitat.env`. This file binds the node to the QuanuX internal network by pinning the `NATS_URL` to the internal NATS instance.

    ```bash theme={null}
    quanuxctl habitat equip edge_nodes
    ```

    <Warning>
      If any dependency cannot be provisioned, the habitat deployment fails completely by design. Do not attempt to patch the server over SSH mid-deployment. Diagnose the failure from the `quanuxctl` output and re-provision from scratch if needed.
    </Warning>
  </Step>

  <Step title="Stage 2 — nest drop">
    `quanuxctl nest drop <TARGET_GROUP> --engine <ENGINE_TYPE>` pushes the repository to the remote server, compiles the engine natively using `-O3 -march=native`, and installs the resulting binary as a `systemd` daemon (`quanux-engine.service`).

    ```bash theme={null}
    quanuxctl nest drop edge_nodes --engine spreader
    ```

    The engine is compiled on the target machine—never cross-compiled, never containerized. This guarantees the binary is optimized for the exact CPU microarchitecture of that node.
  </Step>
</Steps>

<Note>
  The `habitat.env` file written in Stage 1 is a hard dependency for Stage 2. If the file is absent, the engine binary will refuse to start.
</Note>

## Node types

<CardGroup cols={2}>
  <Card title="Execution node (Spreader)" icon="bolt">
    The primary trading node. Runs the C++20 Sovereign Engine with Core 3 pinned as the "Dead Core" Spreader for alpha generation and Core 5 as the Sovereign Sentinel for hardware risk enforcement. Compiled against the exchange-closest hardware available, typically labeled `edge-nyc` or similar.
  </Card>

  <Card title="FIX execution node" icon="network-wired">
    A specialized execution node that adds a FIX protocol adapter layer. Intended for qualified clients requiring FIX conformance testing and independent confirmation to trade. Uses QuickFIX or the proprietary OnixS Solarflare Binary Order Handler via `Makefile.onixs`.
  </Card>

  <Card title="NIC / Solarflare node" icon="microchip">
    An execution node equipped with a Solarflare network interface card running in kernel-bypass mode (EF\_VI). Market data ingress bypasses the Linux OS entirely. This is the target for the Neural Singularity ingress path—reducing NIC ingress from \~800ns toward the theoretical minimum.
  </Card>

  <Card title="Observation node" icon="eye">
    Hosts Panopticon components: Vector, GreptimeDB, OpenSearch, and/or Hasura depending on role. Does not execute trades. Consumes the NATS firehose and serves telemetry to dashboards and AI agents.
  </Card>

  <Card title="Statistics node" icon="chart-line">
    Dedicated to quantitative computation outside the live trading path—position analytics, portfolio-level risk metrics, and settlement. Runs DuckDB analytical logic via the C++ DuckDB C API. The Python `duckdb` library is forbidden on this node class.
  </Card>

  <Card title="Backtesting / replay node" icon="clock-rotate-left">
    Runs the QuanuX Arena (the Training Cortex). Uses TSC-injection to feed the same C++ engine object code historical packet timestamps, so the engine's state machine replays historical sessions with zero behavioral drift from the live path. Backed by the Databento L3 HDF5-to-Parquet pipeline.
  </Card>
</CardGroup>

## Verifying a deployed node

After `nest drop` completes, verify the engine is running on the target node:

```bash theme={null}
systemctl status quanux-engine
```

A healthy execution node produces output similar to:

```
● quanux-engine.service - QuanuX Sovereign Engine (59ns Spreader Nest)
   Active: active (running)
   Main PID: 6699 (quanux_spreader)
Starting QuanuX-Spreader (59ns Dual-Thread Core)...
[Spreader] Connected to NATS DMA pipe.
[Thread 1] Innode Data Pipe Started. Spinning on MARKET.BIN.
[Thread 2] Strategy & FIX Order Entry Started.
```

<Tip>
  You can connect to the NATS JetStream mesh independently to confirm the node is publishing messages before deploying a live strategy. Use the `nats` CLI against the internal VPC address (`nats://10.10.10.x:4222`).
</Tip>