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

# Run a node (mxnode)

> Use mxnode to install, configure, operate, upgrade, and remove MultiversX validator, observer, and multikey node shapes.

Use `mxnode` to install and operate MultiversX validators, observers, and multikey hosts from one CLI.

## Use This When

| Need                                                | Command family                                      |
| --------------------------------------------------- | --------------------------------------------------- |
| Install validators, observers, or multikey hosts    | `mxnode install`                                    |
| Start, stop, restart, or inspect services           | `mxnode start`, `stop`, `restart`, `status`, `logs` |
| Upgrade `mx-chain-go` tags across installed nodes   | `mxnode upgrade`                                    |
| Reapply config, prune databases, or run diagnostics | `mxnode config`, `prune`, `doctor`                  |
| Remove node files and generated units               | `mxnode cleanup`                                    |

## Do Not Use This When

| Need                                  | Use instead                        |
| ------------------------------------- | ---------------------------------- |
| You only need RPC reads               | [Gateway](/gateway/overview)       |
| You only need transaction propagation | [Relayer](/relayer/overview)       |
| You need a managed validator service  | Your validator operations provider |

## Entrypoint

```bash theme={"system"}
curl -fsSL https://raw.githubusercontent.com/XOXNO/mx-node/main/install.sh | sh
```

The installer adds the `mxnode` CLI. State-changing commands initialize `~/.config/mxnode/config.toml` with host defaults.

## Flow

<Steps>
  <Step title="Choose an install shape">
    Pick validator, observer, or multikey. A multikey host runs a 4-node squad, one node per shard.
  </Step>

  <Step title="Place keys">
    For validators, place one `node-{i}.zip` per node. For multikey, place `allValidatorsKeys.pem` where the CLI expects it.
  </Step>

  <Step title="Install nodes">
    Run `mxnode install` with the role and shape flags that match the host.
  </Step>

  <Step title="Start and verify">
    Run `mxnode start --all`, then inspect `mxnode status` and logs before funding or relying on the node.
  </Step>
</Steps>

## Install Shapes

| Shape     | Nodes                  | Key model                      | Notes                                                  |
| --------- | ---------------------- | ------------------------------ | ------------------------------------------------------ |
| Validator | User-selected count    | One BLS key per node           | Use for validator operators with per-node key archives |
| Observer  | User-selected count    | Generated throwaway BLS key    | Use for read-only infrastructure                       |
| Multikey  | 4                      | Shared `allValidatorsKeys.pem` | One node per shard; `--count` is rejected              |
| Squad     | 4                      | Per role                       | One node per shard                                     |
| Backup    | Mirrors primary intent | Depends on role                | Used for redundancy, not active double-signing         |

<Warning>
  Validator and multikey flows involve live signing keys. Verify file ownership, backups, and host isolation before starting services.
</Warning>

## Platform Support

| Platform | Supervisor | Status                     |
| -------- | ---------- | -------------------------- |
| Linux    | systemd    | Primary target             |
| macOS    | launchd    | Development and test hosts |

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/mxnode/quickstart">
    Install the CLI, install nodes, start services, and verify status.
  </Card>

  <Card title="Install shapes" icon="grid-2" href="/mxnode/install-shapes">
    Choose validator, observer, multikey, squad, proxy, and backup shapes.
  </Card>

  <Card title="Lifecycle" icon="play" href="/mxnode/lifecycle">
    Start, stop, restart, inspect status, and read logs.
  </Card>

  <Card title="Troubleshooting" icon="triangle-exclamation" href="/mxnode/troubleshooting">
    Diagnose stale locks, key placement, Go bootstrap, and port conflicts.
  </Card>
</CardGroup>