> ## 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 engine: tune and start live execution nodes

> Apply OS and kernel tuning, initialize the NATS JetStream topology, and start the Annex C++ decoder services on a conditioned QuanuX execution node.

`quanuxctl engine` bridges your infrastructure's state to the QuanuX execution plane. Once a node has been conditioned by `habitat equip` and `nest drop`, you use `quanuxctl engine` to apply deterministic OS and kernel tuning, initialize the CNATS JetStream topology, and start the Annex C++ decoder and ingestion services that feed market data into the execution loop.

## Synopsis

```
quanuxctl engine <command> --target <do|gcp>
```

<ParamField path="--target" type="string" required>
  The cloud provider target for the operation. Accepts `do` (DigitalOcean) or `gcp` (Google Cloud Platform). Determines which infrastructure inventory is used to resolve active node addresses.
</ParamField>

## Commands

### `tune`

Applies OS and kernel-level tuning playbooks to optimize the execution node for deterministic low-latency performance.

```
quanuxctl engine tune --target <do|gcp>
```

For GCP targets, `tune` performs the following:

* Disables Transparent Huge Pages (THP) and enforces Static Hugepages
* Isolates CPU core assignments via GRUB parameters
* Injects raw network buffer parameters for low-latency transmission protocols

<Note>
  Run `tune` once after initial node provisioning. You do not need to re-run it on every deployment unless you change hardware or cloud provider.
</Note>

### `start`

Initializes CNATS JetStream, starts the Annex ingestion sub-services, and natively compiles the Omega C++ Decoder on the target hardware.

```
quanuxctl engine start --target <do|gcp>
```

This command starts the following services in order:

1. **CNATS JetStream** — The message bus for all inter-node communication within the `10.10.x.x` VPC
2. **Annex ingestion services** — The parent processes responsible for market data ingestion
3. **Omega C++ Decoder** — Compiled natively on the target hardware and started as a managed process

### `setup-topology`

Configures the core JetStream stream and consumer topology required by the execution plane.

```
quanuxctl engine setup-topology --target <do|gcp>
```

This command:

* Creates the `QUANUX_INGEST` JetStream stream with 50 GB file-backed storage limits
* Attaches the `ANNEX_PROCESSOR` consumer configured for Durable Pull requests with Explicit ACKs
* Attaches the `ALEPH_OBSERVER` consumer for observability plane ingestion

<Warning>
  Run `setup-topology` only once per cluster. Re-running it against an existing stream will produce errors unless you first remove the existing stream manually.
</Warning>

## Environment variables

| Variable        | Description                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `QUANUX_TARGET` | Determines the infrastructure provider for inventory resolution. Set to `do` or `gcp`. |

## Exit status

| Code | Meaning                                                        |
| ---- | -------------------------------------------------------------- |
| `0`  | All operations completed successfully                          |
| `1`  | Task or subsystem failure — review output for the failing step |

## Verifying the live execution engine

After running `engine start`, the `quanux-engine.service` systemd daemon (deployed by `nest drop`) should be active and connected to NATS. Verify it directly:

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

A healthy engine 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.
```

Confirm both threads are reported as started. If `[Spreader] Connected to NATS DMA pipe.` is absent, the engine could not reach the NATS endpoint in `habitat.env`. Verify NATS is running on the VPC node at `10.10.x.x:4222`.

## Full execution node startup sequence

<Steps>
  <Step title="Provision and condition the node">
    Run the two-stage deployment to prepare the server and install the engine:

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

  <Step title="Tune the OS">
    Apply kernel and OS tuning for deterministic latency:

    ```bash theme={null}
    quanuxctl engine tune --target do
    ```
  </Step>

  <Step title="Initialize JetStream topology">
    Set up NATS streams and consumers (first time only):

    ```bash theme={null}
    quanuxctl engine setup-topology --target do
    ```
  </Step>

  <Step title="Start the engine services">
    Start CNATS, Annex ingestion, and the Omega decoder:

    ```bash theme={null}
    quanuxctl engine start --target do
    ```
  </Step>

  <Step title="Verify execution">
    Confirm the spreader daemon is active and connected:

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

<Tip>
  The NATS JetStream mesh binds exclusively to the `10.10.x.x` internal VPC interface. Traffic never traverses the public internet. Use `quanuxctl obs cluster-health` to verify all edge nodes are sending heartbeats after startup.
</Tip>