> ## 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 habitat: prepare OS and C++ dependencies

> Stage 1 of the Two-Stage Immutable Deployment. Installs C++ toolchains and native libraries, then writes the habitat.env VPC binding on the target server.

`quanuxctl habitat equip` is the first step in deploying a QuanuX execution node. It takes a virgin Linux server and transforms it into a conditioned node ready to receive the C++ engine — installing all required build tools, native libraries, and writing the `/etc/quanux/habitat.env` file that binds the node to the QuanuX VPC. Until habitat runs successfully, the `nest drop` command will refuse to execute.

## Synopsis

```
quanuxctl habitat equip <TARGET_GROUP>
```

## What habitat provisions

Running `habitat equip` installs the following on the remote server:

| Package                          | Purpose                                                     |
| -------------------------------- | ----------------------------------------------------------- |
| `g++-11`, `cmake`, `ninja-build` | C++20 compilation toolchain                                 |
| `libssl-dev`                     | Native TLS/SSL acceleration                                 |
| `libzmq3-dev`                    | Native ZeroMQ message multiplexing                          |
| `flatbuffers`                    | Memory-mapped struct schema compilation                     |
| `duckdb.hpp` / `libduckdb.so`    | In-memory analytical storage for backtesting and settlement |

In addition to package installation, habitat applies IPC tuning to the OS and generates the node's environment binding.

## Target groups

The `TARGET_GROUP` argument maps to a group of servers in your node inventory. The inventory is resolved from your live infrastructure — never from static IP lists.

| Target group | Description                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `edge_nodes` | Execution nodes positioned physically closest to exchange matching engines |

## The habitat.env contract

The most important output of `quanuxctl habitat equip` is the file `/etc/quanux/habitat.env` written to the remote server. This file binds the node to the QuanuX internal network by pinning `NATS_URL` to the internal NATS instance, resolved dynamically from your infrastructure state at deploy time.

Example `/etc/quanux/habitat.env` written to the execution node:

```bash theme={null}
NATS_URL="nats://10.10.10.x:4222"
QUANUX_ENV=production
```

<Warning>
  IP addresses in `habitat.env` are resolved dynamically from your infrastructure state. Hardcoded IP assignments are not supported. If you modify `habitat.env` manually, subsequent nest deployments will reject the binding.
</Warning>

The `nest drop` command reads this file at startup. If the file is absent or malformed, the engine will not start.

## Example

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

<Tip>
  Confirm your target nodes are live and reachable before running habitat. Habitat reads infrastructure state when generating `habitat.env`, so a missing or unreachable node will cause the deployment to fail early.
</Tip>

## Error handling

Habitat is designed to fail completely and loudly if any dependency cannot be met. This is intentional.

<Warning>
  If `habitat equip` fails partway through, do not SSH into the server and attempt manual fixes. Diagnose the failure from the `quanuxctl` output and re-run the command against a freshly provisioned server if necessary. A partially conditioned node is an unreliable node.
</Warning>

The correct recovery sequence is:

<Steps>
  <Step title="Read the failure output">
    Review the `quanuxctl` terminal output to identify which step failed and why.
  </Step>

  <Step title="Correct the root cause">
    Fix the underlying issue — network access, package availability, or infrastructure state — then re-run the command.
  </Step>

  <Step title="Reprovision if necessary">
    If the server is in an unknown or partially provisioned state, destroy it via your infrastructure provider and recreate it from scratch before re-running habitat.
  </Step>

  <Step title="Re-run habitat">
    Run `quanuxctl habitat equip edge_nodes` again against the clean server.
  </Step>
</Steps>

## Next step

Once habitat completes successfully, proceed to `nest drop` to compile and install the C++ engine:

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

See [quanuxctl nest](/cli/nest) for full details.