> ## 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.

# quanuxctl nest: deploy the native C++ execution engine

> Stage 2 of the Two-Stage Immutable Deployment. Compiles the C++ engine natively on the target hardware and installs it as a systemd service.

`quanuxctl nest drop` is the second and final stage of deploying a QuanuX execution node. It pushes the repository to a server that has already been conditioned by `habitat equip`, compiles the C++ engine natively on that hardware, and registers it as a `systemd` service. The resulting daemon runs at 59-nanosecond tick-to-trade performance because it is compiled directly on the execution hardware — never cross-compiled, never containerized.

## Synopsis

```
quanuxctl nest drop <TARGET_GROUP> --engine <ENGINE_TYPE>
```

<ParamField path="TARGET_GROUP" type="string" required>
  The node inventory group to deploy to (e.g., `edge_nodes`). Must match a group defined in your QuanuX node inventory.
</ParamField>

<ParamField path="--engine" type="string" required>
  The engine type to compile and deploy (e.g., `spreader`).
</ParamField>

## Prerequisites

`nest drop` requires that `habitat equip` has been run successfully on the target group. Nest reads `/etc/quanux/habitat.env` at startup — if that file is absent, execution is aborted immediately.

<Warning>
  Do not run `nest drop` on a server that has not been through `habitat equip`. The compilation will either fail due to missing libraries or produce a binary that silently lacks the VPC binding it needs to connect to NATS.
</Warning>

## The native compilation pipeline

`nest drop` copies the repository to the remote server and executes CMake natively on the target hardware:

```bash theme={null}
# Executed on the execution node:
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-O3 -march=native"
make -j$(nproc)
```

The `-march=native` flag tells the compiler to emit CPU instructions specific to the actual processor in the execution server. This is the key reason Docker and cross-compilation are forbidden: a binary compiled on a development laptop cannot achieve the same deterministic instruction timing as one compiled on the hardware it will run on.

<Note>
  The `-Werror` flag is active during compilation. Any unused variables in strategy stubs must be prefixed with `[[maybe_unused]]`. The build will fail if this requirement is not met.
</Note>

## What nest installs

After compilation, nest moves the binary to `/opt/quanux/bin/` and registers the systemd service `quanux-engine.service`. The service is configured to read from `/etc/quanux/habitat.env` at startup, binding the engine to the internal VPC NATS endpoint established by habitat.

## Verifying the deployment

After `nest drop` completes, SSH into the node or use your preferred monitoring tool to verify the service is running:

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

A healthy deployment produces output like the following:

```
● 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.
```

The two key lines to confirm are `Active: active (running)` and the `[Spreader] Connected to NATS DMA pipe.` log entry. If the NATS connection line is absent, check that `habitat.env` contains a valid `NATS_URL` pointing to an active NATS instance.

## Full deployment workflow

<Steps>
  <Step title="Condition the node">
    Run habitat to install OS dependencies and write `habitat.env`:

    ```bash theme={null}
    quanuxctl habitat equip edge_nodes
    ```
  </Step>

  <Step title="Deploy and compile the engine">
    Run nest to push the codebase and compile natively:

    ```bash theme={null}
    quanuxctl nest drop edge_nodes --engine spreader
    ```
  </Step>

  <Step title="Verify the service">
    Confirm the engine is running and connected to NATS:

    ```bash theme={null}
    systemctl status quanux-engine
    ```
  </Step>
</Steps>

## Why no Docker

The 59ns execution latency is a physical property of L3 cache bus synchronization on the execution hardware. A Docker layer introduces indeterminate scheduler overhead that breaks this guarantee. QuanuX enforces native compilation as an architectural constraint, not a preference.

<Tip>
  If you need to update the engine after a code change, re-run `nest drop` against the same target group. Nest performs a clean rebuild — you do not need to re-run `habitat equip` unless the OS dependencies themselves have changed.
</Tip>